公共请求头

闪屏布局由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鉴权。