POST/api/v1/system/request-test
匿名访问 · 需客户端元数据JSON 响应接入指南 ↗

标准请求测试

请求参数

仅在 local/dev 环境启用;启用 prod 时不注册该接口。App 和管理网页都可用它验证公共请求协议,不写入数据库,也不创建账号或管理员会话。

无路径参数和查询参数。请求头需要按下表填写,完整规则见公共请求头:

请求头 必填 本例使用的值
Content-Type 是 application/json
Accept 建议 application/json
Accept-Language 建议 zh-CN
X-Client-Type 是 app
X-Platform 是 android
X-App-Version 是 1.0.0
X-App-Build 是 1
X-Channel 是 dev
X-Device-Id 是 应用持久保存的安装 UUID
X-Request-Id 是 本次请求新生成的 UUID
X-Request-Timestamp 是 本次发送时的 13 位 Unix 毫秒时间戳
X-OS-Version 否 Android 15
X-Device-Model 否 Pixel 8

JSON 请求体:

字段 类型 必填 限制 示例
message string 是 非全空白,最多 200 个 UTF-16 代码单元;中文一般计 1,部分 emoji 计 2 Budyoo 接口测试
number integer 是 JSON 整数,1–100;字符串 "7" 和小数 1.5 不接受 7

请求示例

以下命令可在 macOS/Linux 终端运行;设备 ID 是合成示例,实际 App 应使用自己的持久 ID。当前是无传输加密的开发地址,只传测试数据。

request_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
timestamp="$(date +%s)000"

curl -i --fail-with-body \
  -X POST 'https://api.budyoo.cn/api/v1/system/request-test' \
  -H 'Content-Type: application/json' \
  -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-4f34-a292-8e94551851d7' \
  -H "X-Request-Id: $request_id" \
  -H "X-Request-Timestamp: $timestamp" \
  -H 'X-OS-Version: Android 15' \
  -H 'X-Device-Model: Pixel 8' \
  --data '{"message":"Budyoo 接口测试","number":7}'

iOS 把平台改为 ios 并使用实际发布渠道。管理网页改为 X-Client-Type: admin、X-Platform: web、X-Channel: admin_web;其余公共头仍需提供,接口仍是匿名测试,不授予后台权限。

成功响应

HTTP 200。响应包含 Content-Language: zh-CN、Vary: Accept-Language 与本次 X-Request-Id。下面的 ID、时间戳为示例,实际值来自请求:

{
  "code": "SUCCESS",
  "message": "请求测试通过。",
  "data": {
    "passed": true,
    "method": "POST",
    "headers": {
      "contentType": "application/json",
      "accept": "application/json",
      "acceptLanguage": "zh-CN"
    },
    "client": {
      "clientType": "app",
      "platform": "android",
      "appVersion": "1.0.0",
      "appBuild": "1",
      "channel": "dev",
      "deviceId": "4d4ae3ea-6a4a-4f34-a292-8e94551851d7",
      "requestId": "632e403d-fbf8-43a1-8dc6-d87c20371a2e",
      "timestamp": "1793631600000",
      "osVersion": "Android 15",
      "deviceModel": "Pixel 8"
    },
    "language": "zh-CN",
    "received": {
      "message": "Budyoo 接口测试",
      "number": 7
    }
  },
  "errors": []
}
data 字段 类型 说明
passed boolean 成功时固定 true,仅表示请求绑定及格式校验通过
method string 固定 POST
headers object 实际收到的三个标准头;可选头未传时为 null
client object 解析后的客户端元数据,各值为 string;可选系统版本和型号未传时为 null
language string 实际响应语言 zh-CN/en/ja/ko;地区变体会归一,不支持语言回退英文
received object 校验通过的 message 与 number,不做重复发送或数据库写入

设备和请求 UUID 输出统一小写。英文或不支持语言的成功提示为 Request test passed.;日文为 リクエストのテストに成功しました。,韩文为 요청 테스트를 통과했습니다.。接口只回显明确列出的头,不回传 Authorization、Cookie 或其他任意头。

失败响应

缺少 X-Device-Id,其他头和正文正确:HTTP 400。

{
  "code": "INVALID_CLIENT_HEADERS",
  "message": "客户端请求头校验失败。",
  "data": null,
  "errors": [
    {"field":"X-Device-Id","message":"请求头 X-Device-Id 不能为空。"}
  ]
}

message 传空字符串,其他值正确:HTTP 400。

{
  "code": "VALIDATION_FAILED",
  "message": "请求参数校验失败。",
  "data": null,
  "errors": [
    {"field":"message","message":"测试文本不能为空。"}
  ]
}
HTTP 业务码 条件
400 INVALID_CLIENT_HEADERS 必填元数据缺失、格式错误、重复或平台组合不匹配
400 VALIDATION_FAILED JSON 字段缺失、空文本、长度超限或数值越界
400 BAD_REQUEST 损坏 JSON、无正文或 number 类型错误
415 UNSUPPORTED_MEDIA_TYPE 未设置 JSON Content-Type 或使用纯文本等类型
406 无 JSON 正文 Accept 明确不接受 JSON;客户端需按 HTTP 状态处理
401 UNAUTHORIZED 匿名使用未开放的方法,例如对该路径发送 GET

HTTP 媒体类型与正文校验可能先于元数据校验;一次请求同时出错时,先修复已返回的问题再重试。具体结构见请求与响应。

测试用例结果

2026-11-03 00:36(北京时间)在当时的部署服务器实测,26 项检查全部通过,已包含日文、韩文和未知语言回退;测试只使用合成的设备 ID 和测试字段。

用例 数量 实际 HTTP/业务结果 结果
完整标准头部与 JSON 1 200/SUCCESS;回传输入、版本、渠道、设备及请求 ID 通过
分别缺少八个必填元数据头 8 400/INVALID_CLIENT_HEADERS;指出缺少的头名称 全部通过
版本号、平台组合、设备 ID、时间戳错误 4 400/INVALID_CLIENT_HEADERS 全部通过
空文本、数字超范围 2 400/VALIDATION_FAILED 全部通过
字符串数字、小数、损坏 JSON 3 400/BAD_REQUEST 全部通过
错误或缺省 Content-Type 2 415/UNSUPPORTED_MEDIA_TYPE 全部通过
Accept 只接受 XML 1 406,无正文 通过
日文、韩文及不支持语言 3 ja-JP→ja、ko-KR→ko、fr-FR→en,200/SUCCESS 通过
公开 JS 封装真实请求 1 200/SUCCESS,自动附加元数据 通过
管理网页元数据 1 200/SUCCESS,admin + web 通过

当前整合版本的服务器 Maven 140 项测试全部通过,包含本接口请求/头部校验、四语 HTTP/WebSocket 提示、环境边界、认证和真实 PostgreSQL/Redis 验证。真实客户端联调使用合成上下文,不代表真机原生设备信息或第三方短信投递验收。

可下载 verify-request-test.mjs 和 budyoo-client.mjs 放在同一目录,用支持 fetch 的 Node.js 执行:

node verify-request-test.mjs https://api.budyoo.cn

接入说明

  • 标准请求头是后续版本策略和风控的数据基础,不代表已有设备认证、黑名单、限流、签名或防重放。
  • 本接口只在dev且非prod运行配置下开放;启用prod时,即使同时启用dev,也不会加载该测试控制器。这是配置条件,不代表存在独立测试服。
  • 前端可复用请求封装,在统一层注入元数据,不在每个业务页面手动拼接。