接口简介
「API 测试」是数据鱼API平台提供的基础测试插件接口,Base 路径 /api/apitest,共 4 个端点,定位是「插件生命周期与接入联调的基准件」。它在平台侧验证从上传、安装、启用、调用到禁用的完整链路,同时向集成方提供四个语义极简的端点:健康检查、服务器时间、请求体回显与文本重复。
这类端点的价值在于行为完全可预期:不带业务逻辑、不依赖上游数据源,任何一个请求的响应都能手算出来。接入新项目时,先用它打通鉴权、请求体解析与参数校验三条通路,再切换到业务接口,可以把「参数没传对」和「业务接口真出了问题」这两类故障干净地分开。
四个端点全部返回全站统一的 {code, msg, data} JSON 结构,错误码同样遵循平台约定,因此它也常被用作错误处理逻辑的验证样本。数据鱼API 的其他插件在发布前,通常以本插件的调用行为作为一致性参照。
端点总览
方法 路径 说明 鉴权
GET /api/apitest/ping 健康检查,返回插件版本与服务器时间 需要
GET /api/apitest/time 返回服务器当前时间、Unix 时间戳与时区 需要
POST /api/apitest/echo 原样回显请求体及请求元信息 需要
GET /api/apitest/repeat 将文本重复 N 次后返回 需要
通用约定
鉴权使用全站统一 Key,通过 X-API-Key 请求头或 ?api_key= 查询参数传递;缺少 Key 返回 4011,Key 无效返回 4013。响应统一为 {code, msg, data},code 为 0 表示成功;4001 缺少参数、4002 参数超限、4003 参数非法、4040 路由不存在、5000 服务器内部错误。响应 Content-Type 为 JSON,时区默认 Asia/Shanghai。以上为数据鱼API平台全站统一约定。
核心端点详解
服务器时间 time
返回服务器当前时间,用于调用方校时与签名时间戳核对。
参数 类型 必填 默认 说明
(无) - - - 不接受任何参数
返回 datetime(Y-m-d H:i:s 格式)、timestamp(Unix 秒级时间戳)与 timezone(由应用配置决定,默认 Asia/Shanghai)。
GET /api/apitest/time
X-API-Key: YOUR_API_KEY
原样回显 echo
原样回显请求体,用于联调客户端的请求体序列化与服务端解析是否一致。请求体为合法 JSON 数组时按 JSON 解析,否则回退到表单解析。响应除 received(解析后的请求体)外,还带 content_type、content_length(原始字节长度)、method 与 client_ip,可用于核对网关是否改写了方法或截断了报文。
参数 类型 必填 默认 说明
(任意) object 否 - 请求体内容不校验,原样返回
POST /api/apitest/echo
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{"foo": "bar", "n": 1}
重复文本 repeat
将指定文本重复 N 次后返回,用于验证参数校验与边界处理路径。
参数 类型 必填 默认 说明
text string 是 - 待重复文本,非空,最长 1024 字符
times integer 否 1 重复次数,小于 1 时自动修正为 1,最大 100
返回 text(原始输入)、times(修正后的实际次数)、result(重复结果)与 length(结果字符数,即输入长度乘以次数)。
GET /api/apitest/repeat?text=hello×=3
X-API-Key: YOUR_API_KEY
数据与限制
repeat 的 text 上限 1024 字符(按字符数而非字节数计),超限返回 4003 并附实际长度与上限;times 上限 100,超限返回 4002。
echo 的请求体上限 64KB,超限返回专用错误码 4131 与 HTTP 413,附实际长度与上限值。
无状态服务:不落库、不写文件,所有响应仅由当次请求决定。
典型使用场景
新接入方联调鉴权:用任一端点验证 Key 传递方式(请求头与查询参数均可),确认 4011/4013 的分支处理正确。
客户端 HTTP 库验证:用 echo 核对 JSON、表单两种序列化格式的解析结果,以及网关对请求头与字节数的透传情况。
自动化冒烟测试:以 time 校时、repeat 验证参数边界,作为部署后的固定冒烟用例。
注意事项
健康检查 ping 在文档示例中未携带 Key,但按平台「所有接口均需鉴权」的约定实现,实测不带 Key 会返回 4011;实际响应字段为 version 与 time,文档示例中的 php、server_ip 字段在当前实现中已不存在。
echo 超长请求体的错误码 4131 未列入通用错误码表,处理该分支时需单独适配;其 HTTP 状态码为 413 而非 400。
repeat 的 times 传 0 或负数不会报错,而是静默修正为 1;这与「超上限报 4002」的行为不对称,断言测试时注意区分。
文中行为以当前部署实测为准;服务器时间与时区取决于服务端配置,调用方不应假设其与本地时区一致。