读取完整兴趣标签目录¶
请求参数¶
匿名读取,仍需完整八项公共请求头,X-Client-Type=app、平台ios/android。当前dev可按既有HTTP明文兼容模式联调,JWE请求仍须可信HTTPS;prod强制JSON的HTTPS/JWE。二进制图标不套JWE,仍保留公共头、正式HTTPS及统一错误规则。
无业务请求体或查询参数。返回完整有界目录,无分页;初始6类108项,后续按后台配置变化。
请求示例¶
curl --fail-with-body 'https://api.budyoo.cn/api/v1/catalogs/interests' \
-H 'Accept: application/json' -H 'Accept-Language: zh-CN' \
-H 'X-Client-Type: app' -H 'X-Platform: android' \
-H 'X-App-Version: 1.0.0' -H 'X-App-Build: 1' -H 'X-Channel: dev' \
-H 'X-Device-Id: 4d4ae3ea-6a4a-4b34-a292-8e94551851d7' \
-H 'X-Request-Id: 1b8d414b-4491-4ead-9d71-07365e864c3b' \
-H "X-Request-Timestamp: $(date +%s)000"
每次请求使用新的X-Request-Id,上例ID仅为合成示意;仅当前dev使用HTTP。
成功响应¶
HTTP200,合法请求ID回传X-Request-Id。目录及JSON响应Cache-Control:no-store。
以下仅截取一组/一项,实际包含完整目录。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"catalogVersion": 0,
"minSelection": 1,
"maxSelection": 6,
"groups": [
{
"id": "friends",
"name": "交友",
"names": {
"zh-CN": "交友",
"en": "Friends",
"ja": "友だち",
"ko": "친구"
},
"enabled": true,
"sortOrder": 0,
"version": 0
}
],
"tags": [
{
"id": "meet",
"groupId": "friends",
"name": "跨国交友",
"names": {
"zh-CN": "跨国交友",
"en": "Global friends",
"ja": "国際交流",
"ko": "글로벌 친구"
},
"iconId": "2b9f5dc9-bcc2-5a81-a991-74cfe75393d2",
"iconUrl": "/api/v1/media/interest-icons/2b9f5dc9-bcc2-5a81-a991-74cfe75393d2",
"enabled": true,
"selectable": true,
"sortOrder": 0,
"version": 0
}
]
},
"errors": []
}
| data字段 | 类型/可空 | 说明 |
|---|---|---|
| catalogVersion | integer(int64),非空 | 整体修订号,每次分类/标签保存递增;图标暂存不递增 |
| minSelection/maxSelection | integer,非空 | 1/6 |
| groups | object[],非空 | 按sortOrder、id排序,含停用分类 |
| groups[].id | string,非空 | 不可变稳定ID,原6类ID保留,新建由服务端生成 |
| groups[].name/names | string/object,非空 | 当前请求语言名称/完整四语名称,未知语言回退英文 |
| groups[].enabled/sortOrder/version | boolean/integer/int64,非空 | 分类启停、排序和并发版本 |
| tags | object[],非空 | 全部已配置标签含停用历史;按groupId、sortOrder、id排序 |
| tags[].id/groupId | string,非空 | 稳定标签ID及所属分类,原108项ID保留 |
| tags[].name/names | string/object,非空 | 当前语言文字及四语名称 |
| tags[].iconId/iconUrl | UUID string/string,非空 | 不可变图标编号及同调用端的相对读取路径,不能拼本地素材名 |
| tags[].enabled/selectable | boolean,非空 | 自身启用/实际可选,selectable还要求分类启用 |
| tags[].sortOrder/version | integer/int64,非空 | 分类内排序及并发保存版本 |
失败响应¶
| HTTP | code | 条件/处理 |
|---|---|---|
| 400 | INVALID_CLIENT_HEADERS/BAD_REQUEST/VALIDATION_FAILED | 公共头、UUID、正文类型或必填字段不合法 |
| 426 | HTTPS_REQUIRED | 不满足当前HTTPS策略 |
| 429 | TOO_MANY_REQUESTS | 网关限流,按公共协议处理 |
| 503 | SERVICE_UNAVAILABLE | 数据库/Redis依赖不可用,不回退本地标签 |
code固定不翻译,message中英日韩,未知/缺省回退英文;错误结构见公共协议。
接入说明¶
兴趣名称与图标由服务端维护,新增标签不要求Flutter预置对应翻译键或图片。完整目录及图标与注册/App/后台资料保存共用同一数据;只显示selectable=true项作为新选择,历史停用项可以通过完整元数据继续显示。新加入停用项返回400 INTEREST_UNAVAILABLE;原已选停用项可保留或取消,完成注册仍要求1–6个当前可选项。分类停用同时影响其全部标签;保存即生效,无单独发布按钮。
旧注册字典及后台旧资料字典保持原结构和旧分组映射,只返回原108项中当前可选的代码,不包含新建标签;完整新目录保留所有历史元数据。旧客户端仍依赖本地名称/图片,必须升级到完整目录接入才能显示后台新增或更名内容。读取失败显示重试,不能回退固定标签后提交;空可选目录须显示真实空态。
目录写入、整体版本及后台审计同事务,审计仅记录编号、版本、启停与大小摘要,不记录图标字节;图标存储于数据库,随数据库备份。服务器隔离PostgreSQL/Redis已通过551项完整回归,新增22项覆盖初始6类/108项与全部108个实际图标、四语/英文回退、分类/标签新建修改、换图与素材库、停用准入、注册完成前复核、版本冲突、上传配额、独立权限/CSRF/JWE、审计失败真实回滚,以及V25旧资料升级后原昵称/版本/注册步骤/兴趣ID保持。未在运行库创建测试用户、改选真实用户兴趣或创建演示标签。前端接入以Flutter和Java-web实际验收为准。