首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API · 请求回显接口接入指南

数据鱼API · 请求回显接口接入指南

原创
作者头像
用户12862874
发布于 2026-11-21 21:26:33
发布于 2026-11-21 21:26:33
120
举报

接口简介

「请求回显」是数据鱼API平台提供的调试类接口,Base 路径 /api/echo,共 11 个端点。它把服务端实际收到的请求整理成 JSON 返回,包含方法、路径、查询参数、请求头、请求体、来源地址与时间戳。调用方据此判断请求在链路上被改写成了什么样子。

能力范围限于观测:回显请求、单独回显请求头、按指定秒数延迟响应、返回指定 HTTP 状态码、生成有限跳数的重定向链。接口不对业务参数做校验,不保存回显内容,也不替代日志系统。它是 httpbin 风格的联调工具,用于客户端、网关、代理与重试策略的验证。

设计上有一层脱敏:查询参数中的 api_key 统一替换为 <redacted>,X-API-Key、Authorization、Cookie、Proxy-Authorization 四个请求头按首尾各两位加长度显示。请求体原始内容超过 64 KB 时截断并标注,避免响应无限膨胀。

端点总览

方法

路径

说明

鉴权

GET

/api/echo/ping

健康检查,返回版本、时间与端点列表

免鉴权

GET

/api/echo/echo

回显请求的方法、参数、头、体与来源

需要

POST

/api/echo/echo

同上,并解析 JSON 或表单请求体

需要

PUT

/api/echo/echo

同上

需要

PATCH

/api/echo/echo

同上

需要

DELETE

/api/echo/echo

同上

需要

GET

/api/echo/headers

仅回显请求头

需要

POST

/api/echo/headers

仅回显请求头

需要

GET

/api/echo/delay

延迟指定秒数后返回回显

需要

GET

/api/echo/status

返回指定 HTTP 状态码

需要

GET

/api/echo/redirect

生成指定跳数与状态码的重定向链

需要

通用约定

鉴权使用全站统一 Key,通过 X-API-Key 请求头或 api_key 查询参数传入;未携带返回 4011,无效返回 4013。GET 与 POST 均可,POST 支持 JSON body 与表单。多数端点的 code 为 0 表示成功,参数越界返回 4002;status 与 redirect 是例外,它们会有意返回非 200 的 HTTP 状态。数据鱼API在这一组端点里没有批量入口,每次调用只描述当前这一个请求。

核心端点详解

请求回显 GET /api/echo/echo

返回当前请求的完整快照。方法支持 GET、POST、PUT、PATCH、DELETE,路径相同。

参数

类型

必填

默认值

说明

raw

array/object

否

—

仅作为查询参数原样回显,不改变响应结构

json

array/object

否

—

同上

json_valid

array/object

否

—

同上

form

array/object

否

—

同上

text

array/object

否

—

同上

返回字段分为几组:method 与 path 是请求行信息;query 是按名称排列的查询参数对象,同名参数的表现取决于 PHP 的解析规则;headers 为小写名称的请求头;body 含 size,非空时附 raw,JSON 请求会再给出解析后的 json 与布尔 json_valid,表单请求给出 form,文本请求给出 text;ip 与 x_forwarded_for 分别取直连地址与转发头;timestamp 为服务端本地时间。

代码语言:javascript
复制
GET /api/echo/echo?text=hello&form=json
代码语言:javascript
复制
POST /api/echo/echo
Content-Type: application/json

{"order_id": "A1001", "amount": 19.9}

请求头回显 GET /api/echo/headers

只返回 data.headers 一个对象,结构与 echo 中的请求头部分一致。用于确认代理是否添加或覆盖了 X-Forwarded-For、Accept-Encoding、User-Agent 等字段,响应体积比 echo 小。

延迟响应 GET /api/echo/delay

参数

类型

必填

默认值

说明

s

string

否

1

延迟秒数,浮点解析,优先于 seconds

seconds

string

否

—

延迟秒数,仅在未传 s 时生效

延迟值会被限制在 0 至 10 秒之间,响应在 echo 的结构上增加 delayed_seconds,表示实际等待的秒数。适合验证客户端超时阈值、连接池回收与重试退避。

状态码回显 GET /api/echo/status

参数

类型

必填

默认值

说明

code

string

否

500

目标状态码,取值 100 至 599

HTTP 状态码等于传入的 code,响应体仍是标准 JSON,code 字段为 0、msg 为 requested status N,并附带完整的请求回显。越界返回 4002。

重定向链 GET /api/echo/redirect

参数

类型

必填

默认值

说明

n

string

否

1

剩余跳数,取值 0 至 5

code

string

否

302

重定向状态码,仅支持 301、302、303、307、308

n 大于 0 时返回一次重定向,Location 指向同一路径下 n 减一的目标,并带 X-Echo-Redirects-Left;n 为 0 时不再重定向,直接返回回显并标记 redirects_done。

数据与限制

  • 延迟上限 10 秒,重定向上限 5 跳,状态码范围 100 至 599。
  • 请求体 raw 最多保留 65536 字节,超出部分截断并追加提示标记;size 始终是真实长度。
  • 请求体解析按 Content-Type 分支:application/json 解析为 json 并给出 json_valid,application/x-www-form-urlencoded 解析为 form,text/* 写入 text,其他类型只保留 raw。
  • 脱敏覆盖 api_key 查询参数与 X-API-Key、Authorization、Cookie、Proxy-Authorization 四个头;本地直连时 x_forwarded_for 为 null。
  • 文档未给出缓存 TTL,回显内容即时生成。

典型使用场景

  • 客户端联调:确认请求方法、路径、查询参数与请求头是否按预期发出。
  • 网关与代理验证:检查转发链是否改写 Host、X-Forwarded-For 或压缩头。
  • 超时与重试测试:用 delay 构造慢响应,观察客户端的超时、重试与熔断行为。
  • 错误分支覆盖:用 status 返回 4xx 或 5xx,验证前端与服务端的异常处理。
  • 重定向策略验证:用 redirect 构造 301 与 307 链,确认客户端是否保留方法与请求体。

注意事项

  • API.md 把 raw、json、json_valid、form、text 列为 echo 的请求参数,但它们不会填充 data 的顶层字段,只是作为查询参数出现在 query 里;真正决定 body 结构的是请求体与 Content-Type。
  • delay 的 s 优先于 seconds,两者同时出现时只有 s 生效;API.md 的示例里 seconds=1 而 delayed_seconds 为 8.8,正是 s 中的浮点数被解析后的结果。
  • status 返回的 HTTP 状态是请求的目标码,但响应体 code 仍为 0。只检查 body 的客户端会把 5xx 误判为成功,判断成败应以 HTTP 状态码为准。
  • redirect 的 n 表示剩余跳数而非总跳数,n=1 只会重定向一次;不跟随重定向的客户端需要自行读取 Location 与 X-Echo-Redirects-Left。
  • 脱敏只覆盖约定的几个字段,自定义头与请求体中的密钥会原样返回,调试时不要发送生产凭据。
  • 本接口定位为调试工具,不承诺回显内容的持久化,也不适合作为业务链路的依赖。数据鱼API将其与业务接口同域提供,便于在同一套鉴权下做联调,但不应在生产流程中调用。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 请求回显 GET /api/echo/echo
    • 请求头回显 GET /api/echo/headers
    • 延迟响应 GET /api/echo/delay
    • 状态码回显 GET /api/echo/status
    • 重定向链 GET /api/echo/redirect
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档