GET/api/v1/admin/interests/icon-library
独立管理员Cookie、HTTPS、ADMIN_INTERESTS_READ、JWEJSON 响应接入指南 ↗

读取兴趣图标库

请求参数

OWNER及VIEWER可读,八项公共请求头全部必填,固定admin/web/admin_web;必须HTTPS、独立Cookie及真实JWE。此路径是JSON接口,不属于图标文件的协议例外。

查询参数 类型 必填 限制
page integer 否 默认1,至少1
pageSize integer 否 默认50,1–100
unusedOnly boolean 否 默认false返回全部;true只返回未被任何标签引用的图标,包含停用标签的引用

无业务正文。按创建时间倒序、UUID升序稳定分页,总数使用相同筛选和快照。图标总容量2000个;清理时先通过丢弃接口删除确认不再使用的未引用素材。

请求示例

import {createJweEncryption} from '../../examples/budyoo-encryption.mjs';
const codec = createJweEncryption({baseUrl:location.origin});
const url = new URL('/api/v1/admin/interests/icon-library?page=1&pageSize=50&unusedOnly=true',location.origin);
const encrypted = await codec.prepare({url,method:'GET',body:null,headers:{
  'Accept-Language':'zh-CN','X-Client-Type':'admin','X-Platform':'web',
  'X-App-Version':'1.0.0','X-App-Build':'1','X-Channel':'admin_web',
  'X-Device-Id':installationId,'X-Request-Id':crypto.randomUUID(),
  'X-Request-Timestamp':String(Date.now())
}});
const response = await fetch(url,{headers:encrypted.headers,credentials:'same-origin',redirect:'error'});
const result = await encrypted.decode(response);

成功响应

HTTP200,Cache-Control:no-store,外层JWE,以下为解密后的合成示例。

{
  "code":"SUCCESS","message":"操作成功。",
  "data":{"total":1,"page":1,"pageSize":50,"items":[
    {"id":"4d4ae3ea-6a4a-4b34-a292-8e94551851d7","contentType":"image/png","size":2048,
     "used":false,"createdAt":"2026-11-05T12:00:00Z",
     "iconUrl":"/api/v1/admin/interests/icons/4d4ae3ea-6a4a-4b34-a292-8e94551851d7"}
  ]},"errors":[]
}
data字段 类型/可空 说明
total/page/pageSize integer,非空 筛选总数和实际分页参数
items array,非空 当前页,无结果为[]
items[].id UUID string,非空 不可变图标编号,标签保存作为iconId
items[].contentType string,非空 image/png或初始化可信image/svg+xml
items[].size integer(int64),非空 存储的实际字节数
items[].used boolean,非空 是否被任意标签引用,停用标签也计入;true不可丢弃
items[].createdAt date-time string,非空 带时区ISO8601创建时间
items[].iconUrl string,非空 后台同源读取路径,按Cookie和公共头获取图片Blob

失败响应

400 BAD_REQUEST/INVALID_CLIENT_HEADERS表示分页、格式或元数据错误;401 UNAUTHORIZED表示Cookie失效;403 FORBIDDEN/ADMIN_CSRF_INVALID表示权限、Origin等边界拒绝;426 HTTPS_REQUIRED;429入口限流;503 SERVICE_UNAVAILABLE表示存储依赖不可用。JSON/JWE失败与公共协议一致,message支持四语并默认英文,不把失败解释为空列表。

接入说明

图标库可用于标签编辑时复用已有素材,并找回浏览器中断后遗留的未引用上传图标。只返回媒体元信息,不返回图标字节、管理员身份或内部文件路径。此GET不会绑定、删除或修改图标,也不改变目录版本;点击选择后仍需保存标签才完成引用。预览使用返回的iconUrl,不能关闭TLS验证或把SVG作为HTML插入。

服务器隔离PostgreSQL/Redis已通过551项完整回归,新增22项覆盖初始6类/108项与全部108个实际图标、四语/英文回退、分类/标签新建修改、换图与素材库、停用准入、注册完成前复核、版本冲突、上传配额、独立权限/CSRF/JWE、审计失败真实回滚,以及V25旧资料升级后原昵称/版本/注册步骤/兴趣ID保持。未在运行库创建测试用户、改选真实用户兴趣或创建演示标签。前端接入以Flutter和Java-web实际验收为准。