请求与响应

本页描述 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;媒体单项故障不推翻已提交业务,公开字节缓存与凭证期限分别处理。