读取兴趣图标库¶
请求参数¶
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实际验收为准。