公共请求头¶
闪屏布局由GET /api/v1/app/bootstrap根据可信入口的连接IP返回,不新增客户端IP/国内国际/苹果商店国家请求头;X-Channel继续表示发行来源。协议新模式的layoutPolicy=ip-v1是查询参数并由既有JWE上下文认证,详见启动布局。
适用范围¶
以下 X-* 是 Budyoo 自定义的客户端元数据协议,配合标准 HTTP 头使用。新接入的 App/管理网页业务接口以此为基础,并在独立接口页声明是否强制校验。
当前标准请求测试已完整校验,缺失或非法返回 HTTP 400/INVALID_CLIENT_HEADERS。现有系统信息仍允许不带元数据,用于基础连通性和启动前检查。框架健康检查不要求这组头。
长连接在 HTTP 申请票据时校验同一组元数据,WebSocket 首帧只提交一次性票据;浏览器无需向原生 WebSocket 握手添加这些自定义头。
标准 HTTP 头¶
| 请求头 | 是否必填 | 示例 | 说明 |
|---|---|---|---|
Content-Type |
JSON 正文必填 | application/json |
可带 charset=UTF-8;GET 无正文无需设置 |
Accept |
建议传 | application/json |
省略或 */* 可接收 JSON;只接受 XML 等格式可能返回 406 |
Accept-Language |
客户端统一传;服务端允许缺省 | zh-CN |
当前 App 界面语言;支持中文、英文、日文、韩文,未提供或未匹配时回退英文 |
当前 App 语言¶
语言使用标准 Accept-Language,不再重复增加 X-Language。应读取 App 当前生效的语言选择,每次请求动态注入;不要直接固定为手机系统语言、国家、母语或学习语种。App 切换语言后,下一次请求立即发送新值。
| App 语言 | 建议发送值 | 响应 Content-Language |
|---|---|---|
| 简体中文 | zh-CN |
zh-CN |
| 英文 | en-US 或 en |
en |
| 日文 | ja-JP 或 ja |
ja |
| 韩文 | ko-KR 或 ko |
ko |
未传或不支持,例如 fr-FR |
可缺省 | en |
服务端将成功提示、业务错误、参数校验和鉴权错误中的 message、errors[].message 转换为相应语言,code 与字段名称保持固定。同一语言的地区变体归一为表中的语言包;有权重的语言列表按支持情况匹配。
WebSocket 在申请票据时保存语言,认证后的提示沿用该语言;每个客户端消息还可传 language 更新当前选择,详见连接协议。
客户端元数据¶
下表“必填”指启用本协议的接口;所有请求头均为单个字符串值,不重复传送。
| 请求头 | 必填 | 示例 | 格式与来源 |
|---|---|---|---|
X-Client-Type |
是 | app |
app 或 admin;标识调用端,不授予权限 |
X-Platform |
是 | android |
App 使用 ios/android;管理网页使用 web |
X-App-Version |
是 | 1.0.0 |
发布版本,三段数字,每段 1–4 位;可附预发布及构建标识,各最多 32 位,例如 1.0.0-beta.1+build.7 |
X-App-Build |
是 | 1 |
1–9 位非负整数字符串;来自客户端构建配置 |
X-Channel |
是 | dev |
小写字母开头,后接小写字母、数字、下划线或短横线,总长 1–32;来自发布配置 |
X-Device-Id |
是 | 4d4ae3ea-6a4a-4f34-a292-8e94551851d7 |
标准 UUID 格式;应用安装/浏览器实例首次生成并持久保存,推荐 UUIDv4 |
X-Request-Id |
是 | 632e403d-fbf8-43a1-8dc6-d87c20371a2e |
每次请求新生成的 UUID;用于关联诊断,成功响应头会回传 |
X-Request-Timestamp |
是 | 1793631600000 |
发出请求时的 Unix 毫秒时间戳,13 位数字;每次发送更新 |
X-OS-Version |
否 | Android 15 |
系统版本,1–64 个可打印 ASCII 字符;未知时不传 |
X-Device-Model |
否 | Pixel 8 |
设备型号,1–64 个可打印 ASCII 字符;未知时不传,不传硬件序列号 |
基本渠道统一为国内xiaomi、vivo、huawei、oppo、yingyongbao、honor、baidu;海外google_play、app_store。对应名称、平台、地区和客户端预设见App发行渠道。当前验证格式,不依据这些字符串自动放行或封禁。
七个国内商店及google_play使用android,app_store使用ios;管理网页固定admin_web,测试版本可用dev。APP_REGION与界面语言分别配置,不按手机品牌或用户国家推断发行渠道。
通过验证码或三方身份首次成功创建账号时,服务端将该验证请求的X-Channel保存为账号渠道,供授权后台只读展示。历史账号该字段为null时,在后续成功登录、成功刷新或通过Bearer认证的请求中,以本次合法渠道原子补录一次;已有值始终不覆盖,注销时清除。补录要求账号可用、凭证及安装绑定有效,并通过渠道/平台和现有会话渠道校验;匿名、认证失败、非法渠道和过期/已撤销凭证不补录。客户端继续使用已有统一请求头,无需增加接口或请求。历史补录表示首次补获的渠道,不声称还原当年的注册来源;不按国家、手机号或旧会话批量猜测。该值仍为客户端自报,不作为身份、商店签名或可信设备证明,也不用于决定当前会话的VIP门槛。
标识生命周期¶
设备风控新增独立检查流程,保留X-Device-Id的安装UUID语义,不把Android ID或Apple token塞进公共头。材料在明确同意后通过专门HTTPS正文提交,既有JWE上下文及八项必填头保持。
- 设备标识用来识别一次应用安装或浏览器存储实例,不等同于用户 ID。App 在本地持久存储中保存,管理网页可使用本域 localStorage;清除数据或重装可能重新生成。
- 不使用 IMEI、MAC、硬件序列号或广告 ID 作为本协议的默认设备标识;不把登录 Token 填入设备标识。
- 每次请求生成新的请求 ID 和时间戳,不作为业务幂等键;普通模式用于传输与诊断,加密模式按下述规则校验防重放,不代表客户端身份签名。
- 普通明文请求仅校验时间戳格式;AES 加密模式会绑定请求头和正文,限制120秒时钟偏差,并通过 Redis 原子拒绝重复请求 ID。该防重放只适用于已验证的加密信封,不等于业务幂等或所有明文接口的防重放。
- OS、型号、版本和渠道均由客户端自报,能被伪造。服务端风控仍需结合认证、行为、限流和可信设备证明,不能只凭这些头认定设备可信。
失败与兼容¶
缺失、空值、格式错误、重复头、客户端与平台组合不一致均返回 INVALID_CLIENT_HEADERS。errors[].field 是原始头名称,例如 X-Device-Id;提示不包含未经信任的原始头值。
登录注册、本人资料、字典和头像接口强制校验全部八项元数据,且只接受app。本人资料与会话操作另须Authorization: Bearer <accessToken>;刷新接口只传正文refreshToken,不携带旧访问凭证。详见登录注册接入。不要把X-Client-Type: admin当成管理员认证。正式HTTPS和额外报文加密状态见加密与认证。
已实现的后台接口使用相同八项元数据,固定admin/web/admin_web,身份通过独立Secure HttpOnly Cookie验证,写请求另有Origin和X-Admin-CSRF,全部要求HTTPS,JSON业务要求JWE;明确的头像/相册文件端点不套JWE但不豁免认证或CSRF。不接受App Bearer,见后台安全协议。系统信息与标准请求测试仍保留原匿名探测语义。
统一媒体交付¶
2026-11-20统一App媒体协议已部署:不再要求X-Media-Delivery,不传、cdn-v1和oss-v1均返回同一份交付结构,也不回传能力头。CDN/OSS/API由服务端配置和资源类型选择,客户端读取transport、requestHeaders和authorization处理;它们不代替上述八项必填头、Bearer或JWE。
唯一正式部署环境已启用上述协议,运行配置仍为dev;客户端使用统一字段解析,设备验收单独记录。完整字段、缓存、鉴权及验证范围见统一媒体交付和CDN鉴权。