标准请求测试¶
请求参数¶
仅在 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,也不会加载该测试控制器。这是配置条件,不代表存在独立测试服。
- 前端可复用请求封装,在统一层注入元数据,不在每个业务页面手动拼接。