103 个接口,为什么只留一个 GET 和一个返回信封
2026-11-19 · Finewisdom 技术笔记
结论:接口数量越多,越应该收敛调用形态。103 个接口如果各有一套 URL、参数风格和错误码,接入成本会压死转化;而统一成 /api?method=xxx 之后,客户只需要学一次,AI Agent 也能靠一份目录自己选方法。
一、103 套 RESTful 路由的代价
理想主义的写法是 GET /v1/douyin/videos/{id}/comments、GET /v1/xhs/notes/{id}……
好看,但真实成本在别处:
- 每个平台一套路径语义:抖音叫
aweme_id、小红书叫note_id、B站叫bv_id、 微博叫post_id、1688 直接用item_id。做成路径参数后,客户每次都要查"这个平台这个资源叫什么"。 - SDK 与网关都要按路径写规则:限流、鉴权、计费、日志全部要按 103 条路由重复配置。
- 新增一个方法 = 新增一条路由 + 一次网关变更,而这类平台的接口是天天变的。
所以真正的取舍不是"RESTful 好不好",而是「接入成本」和「URL 语义美感」哪个更值钱。 对一个按次计费的数据平台,前者决定转化率。
二、统一路由:一个 GET,method 当分发键
GET https://finewisdom.top/api?token=fw_xxx&method=douyin_video_comments&aweme_id=...&page=0
好处很直接:
- 客户只记一个 URL、一套鉴权(
?token=或X-FW-Token头)。 - 新增方法不动网关:网关只认
/api,方法名是业务层的事。 - Agent 友好:REST 与 MCP 的 工具名 = 方法名 = 参数名,一套心智模型通吃。
代价也要说清楚:丢了 HTTP 语义(没有 404/409 这种资源级状态码),缓存也只能按 query 维度做。 对一个"每次调用都计费、都要鉴权"的接口,这两个代价可以接受。
三、统一信封:{status, message, data}
{"status": "success", "message": "...", "data": { ... }}
为什么一定要包一层,而不是直接返回 data?因为要区分三种"看起来一样"的情况:
| status | 含义 | 该不该计费 | 客户端该做什么 |
|---|---|---|---|
success | 真的拿到了数据 | 计费 | 解析 data |
error / api_error | 参数错、目标不存在、上游失败 | 不计费 | 读 message,别原样重试 |
preview | 游客模式,没充值 | 不计费 | 提示充值,别重试 |
关键设计是「失败不计费」和「信封」是绑在一起的:只有在服务端能明确判定 status=success 时才扣费。
如果没有统一信封,扣费判定就得靠 HTTP 状态码 + 返回体结构去猜,一定会出现"扣了钱但没有数据"的争议。
还有一个细节:空结果(目标已删除)也不算失败,返回 success 但 data 为空 —— 这种通常直接不计费,
避免客户为"查了一个不存在的 ID"付钱。
四、计费的工程含义:预扣 + 回滚 + 幂等
"成功才扣费"写进文案只要一句话,落到工程上是三件事:
- 预扣:请求进来先冻结一次单价,防止并发把余额扣成负数;
- 回滚:失败、超时、上游异常时把冻结额度退回;
- 幂等:同一个请求重试不应该扣两次(按 token + method + 关键参数做幂等键)。
这三件事没做好,客户对账时一定会吵。所以我一直建议客户:余额和调用日志要能对上账, 而不是只看余额数字。
五、机器可读的契约:catalog.json 比文档重要
103 个方法,人写文档永远跟不上代码。真正稳定的契约是一份 免鉴权、可程序化读取 的能力目录:
GET https://finewisdom.top/catalog.json
{
"capabilities": [
{"method": "xhs_note_comments", "platform_slug": "xhs",
"description": "获取小红书笔记的一级评论列表",
"price_cny": 0.2,
"params": [{"name": "note_id", "required": true, "desc": "笔记ID"}, ...]}
]
}
它同时服务三类读者:人(看单价和参数)、程序(动态生成表单/SDK)、AI Agent(评估阶段免注册就能读,
决定要不要用你)。这也是为什么我在站点上把 /catalog.json、/openapi.json、
/llms.txt 和 /llms-full.txt 都做成免鉴权 —— 让 Agent 在"还没注册"的时候就能读懂你。
六、MCP 一对一是最省事的,但不是没代价
把 103 个 REST 方法一对一映射成 103 个 MCP 工具,实现成本几乎为零(工具名即方法名,参数完全一致)。 但工具一多,Agent 选错的概率就上去了。第三方评分机构给这类 server 的反馈很直白:
- 同族方法描述太像(
douyin_video_like_count和douyin_video_play_count都在说"视频数据"); - 版本后缀逼着模型去推理(
_v2/_v3到底该用哪个); - 超过 25 个工具之后,选择成本陡增。
可落地的解法不是"砍工具",而是让每个描述都自带"什么时候用我、什么时候别用我"。 比如 v2/v3 这种同能力多通道,描述里必须写清数据源差异和字段差异,否则模型只能瞎选。
七、版本化:宁可加后缀,不要原地改
taobao_original_detail、jd_comments / jd_comments_v2、
douyin_product_detail / _v2 / _v3 —— 看着乱,但比"原地改返回结构"安全得多。
客户的解析代码是写死的,字段一改就全炸;而新增一个 _v2 只是多一个选项。
规则只有一条:已发布的方法,返回结构只增不改;要改就起新名字。这条比任何命名规范都重要。
常见问题
因为 103 个方法横跨 15 个平台,路径语义无法统一(aweme_id / note_id / bv_id / item_id),统一成一个 GET + method 分发键后,客户只需学一次,新增方法也不用改网关。
会多一点(status 和 message 两个字段),换来的是扣费判定可靠、错误可区分。这个交换是明确划算的。
会。工具超过 25 个后选择成本明显上升,所以工具描述必须写清「什么时候用我」,而不是只写「我返回什么」。