请求与响应¶
本页描述 App 与管理后台共享的接口格式;各接口的权限、业务字段和状态以对应模块文档为准。
公网请求先经过Nginx入口限流。入口可在Java处理前返回429、403、410、413或415;加密请求同样可能遇到明文网关拒绝,不能将其当成已验证JWE业务响应。
下述结构是业务 JSON。启用AES 加密时,外层使用 application/jose 和 JWE,解密后仍得到相同的 code/message/data/errors;原接口路径、认证要求和参数语义不变。
请求¶
| 项目 | 约定 |
|---|---|
| 方法与路径 | 按接口文档发送;已有系统信息接口为 GET /api/v1/system/info |
| 查询参数 | 放在 URL 查询参数中,正文参数使用 JSON;不要自行混用 |
| 请求体类型 | 有 JSON 正文时使用 Content-Type: application/json;无正文的 GET 无需设置 |
| 响应格式 | 业务接口返回 JSON,可发送 Accept: application/json |
| 语言 | 通过 Accept-Language 传当前 App 语言,支持 zh-CN、en、ja、ko,接受相应地区变体 |
| 语言回退 | 未提供或未匹配这四种语言时使用英文;某个翻译键缺失时回退基础英文文案 |
| 响应语言 | Content-Language 表示实际语言,Vary: Accept-Language 表示响应会随语言变化 |
| 认证 | App使用Authorization: Bearer <accessToken>;本站凭证不透明,公共入口匿名调用,受保护接口未认证返回401 |
App登录、刷新和注册状态遵循登录注册接入。后台使用独立Cookie与CSRF协议,不能把App凭证或客户端类型当作管理员身份。
客户端版本、渠道、设备标识和请求追踪头统一见公共请求头,包含 X-Client-Type、X-Platform、X-App-Version、X-App-Build、X-Channel、X-Device-Id、X-Request-Id 和 X-Request-Timestamp。当前标准测试接口已强制校验,系统信息与健康检查保留基础探测例外。
统一业务响应¶
{
"code": "SUCCESS",
"message": "Budyoo 后台已就绪。",
"data": {},
"errors": []
}
| 字段 | 类型 | 含义 |
|---|---|---|
code |
string | 固定业务码,成功为 SUCCESS,客户端以它判断业务结果 |
message |
string | 按请求语言生成的展示提示,不用于条件判断 |
data |
object/array/标量/null | 具体类型由接口定义;普通失败或无业务返回值为null;四个封禁/设备复核错误带受限提示及短期申诉凭据,见封禁接入 |
errors |
array | 字段校验明细,无明细时为 [] |
errors[].field |
string | 校验失败的字段名 |
errors[].message |
string | 对应字段的本地化错误提示 |
mediaDelivery |
可选array | App成功响应的媒体交付与缓存说明;详见统一媒体交付,后台网页响应不增加 |
保留 HTTP 状态和业务码两个维度。服务不可达、超时及网关非 JSON 响应属于传输错误,客户端应使用本地提示,不能假设所有响应都能解析成业务结构。
例如 HTTP 401 的 code 始终为 UNAUTHORIZED,message 分别为“请先登录。”、Authentication is required.、ログインしてください。、로그인해 주세요.。业务逻辑依据错误码处理,不能用翻译文案做条件判断。
错误码¶
| HTTP 状态 | 业务码 | 含义 |
|---|---|---|
| 400 | BAD_REQUEST |
请求格式不正确 |
| 400 | VALIDATION_FAILED |
参数校验失败,读取 errors |
| 400 | INVALID_PHONE_FORMAT |
登录发码时手机号格式不正确,客户端可直接展示 message |
| 400 | INVALID_EMAIL_FORMAT |
登录发码时邮箱格式不正确,客户端可直接展示 message |
| 400 | INVALID_CLIENT_HEADERS |
客户端元数据头缺失或非法,errors[].field 指出对应请求头 |
| 401 | UNAUTHORIZED |
尚未认证或认证不通过 |
| 403 | FORBIDDEN |
已认证但权限不足 |
| 401 | ADMIN_LOGIN_INVALID |
后台凭证错误或临时锁定 |
| 403 | ADMIN_CSRF_INVALID |
后台Origin或CSRF校验失败 |
| 400 | ADMIN_PASSWORD_INVALID |
后台新密码不符合长度或更换要求 |
| 409 | ADMIN_CONFIG_CONFLICT |
全局配置版本冲突,需刷新确认 |
| 409 | TOPIC_CONFIGURATION_CONFLICT |
话题代码重复或版本已变化,核对最新配置后保存 |
| 409 | TOPIC_FEATURED_CONFLICT |
已有其他今日话题,先保存原话题的featured=false后再设置新项 |
| 403 | PROFILE_COUNTRY_VIP_REQUIRED |
非VIP实际修改国家/地区,保留原输入,不等同登录失效或VIP准入拦截 |
| 409 | PROFILE_CONFLICT |
资料版本已变化,重新读取后确认修改 |
| 409 | PROFILE_REVIEW_CONFLICT |
资料审核修订、候选或当前公开来源已变化,请只读核对后再决定 |
| 400 | PROFILE_REVIEW_REASON_REQUIRED |
驳回或下架用户资料时必须填写非空原因 |
| 400 | INVALID_INTEREST/INVALID_INTEREST_ICON/INTEREST_UNAVAILABLE |
兴趣配置、图标或当前可选状态不符合要求 |
| 409 | INTEREST_CATALOG_CONFLICT/INTEREST_CATALOG_LIMIT/INTEREST_ICON_IN_USE |
兴趣版本冲突、容量上限或仍有图标引用 |
| 429 | INTEREST_ICON_LIMIT |
管理员本小时图标上传额度已用完 |
| 400 | INVALID_APP_CHANNEL |
登录/VIP渠道未知、平台不匹配或prod误用dev |
| 400 | PROFILE_LANGUAGES_SAME |
我会的语言与想学习的语言相同,重新选择不同语言 |
| 400 | INVALID_PHOTO |
相册图片无效、重复、已删除或不属于目标用户 |
| 409 | PHOTO_IN_USE |
图片已绑定相册,须通过资料保存移除 |
| 429 | PHOTO_QUOTA_EXCEEDED |
有效及暂存照片达到30张,先丢弃未使用照片 |
| 403 | VIP_REQUIRED |
资料已完成,但当前会话渠道VIP门槛开启且当前无有效会员权益 |
| 404 | NOT_FOUND |
资源不存在 |
| 405 | METHOD_NOT_ALLOWED |
请求方法不支持 |
| 406 | NOT_ACCEPTABLE |
请求的响应格式不支持 |
| 415 | UNSUPPORTED_MEDIA_TYPE |
请求体类型不支持 |
| 410 | UPLOAD_ENDPOINT_REMOVED |
五个旧App文件上传POST已移除,更新客户端并使用OSS直传;读体前退役响应不套JWE |
| 413 | PAYLOAD_TOO_LARGE |
上传内容或加密请求正文超过限制 |
| 426 | HTTPS_REQUIRED |
新认证/资料接口要求HTTPS |
| 429 | AUTH_RATE_LIMITED |
验证码、验证或上传限流 |
| 503 | AUTH_PROVIDER_UNAVAILABLE/AUTH_DELIVERY_FAILED |
登录供应商未配置或发送失败 |
| 429 | TOO_MANY_REQUESTS |
连接票据签发频率超限 |
| 503 | SERVICE_UNAVAILABLE |
数据库/Redis 连接不可用或超时 |
| 400 | ENCRYPTION_REQUIRED |
当前环境要求加密请求 |
| 400 | INVALID_ENCRYPTED_REQUEST |
密文、算法或请求上下文校验失败 |
| 400 | ENCRYPTION_KEY_EXPIRED |
公钥 kid 已不可用 |
| 400 | ENCRYPTED_REQUEST_EXPIRED |
加密请求时间戳超窗 |
| 409 | ENCRYPTED_REQUEST_REPLAYED |
同一加密请求 ID 重复提交 |
| 500 | INTERNAL_ERROR |
未预期服务端错误 |
这些是当前框架错误码;单个接口只列出实际适用项。未登录请求受保护路径时可能先返回 401,不能据此判断路径是否存在。
验证码申请的AUTH_RATE_LIMITED可携带具体等待文案与Retry-After秒数,区分发送冷却和固定小时额度;详见验证码申请。其他接口的限流提示与网关429仍按各自契约处理,不把该等待信息推断为全站统一行为。
如果请求的 Accept 明确排除 JSON,406 使用无正文响应,按 HTTP 状态处理。成功响应是否回传 X-Request-Id 由接口说明,目前标准请求测试已实现。
中文未认证响应示例:
{
"code": "UNAUTHORIZED",
"message": "请先登录。",
"data": null,
"errors": []
}
运维与示例接口边界¶
GET /actuator/health是框架健康检查,成功使用 Actuator 原生结构{"status":"UP"},服务器环境可能同时返回groups;不套用业务响应封装。/actuator/health以外的/actuator/*受 ADMIN 权限保护,目前没有可用的管理员登录流程。这些端点不属于管理后台网页业务。POST /api/v1/demo/greetings仅用于local环境演示,服务器dev/prod不启用;不列入 App 可调用业务目录。- 分页、幂等、上传及业务认证规则将按实际功能确定,目前没有已实现的统一契约。
2026-11-20统一媒体响应已部署(运行配置仍为dev):已认证App成功聚合响应中的用户媒体自动采用统一交付结构,不再通过能力头选择格式;顶层mediaDelivery与data中的URL同步。独立下载授权的data[]使用同一结构,无额外mediaDelivery;匿名、管理员、错误及二进制响应保持原边界。本站JSON仍为no-store;媒体单项故障不推翻已提交业务,公开字节缓存与凭证期限分别处理。