Finewisdom API Hub
首页 › 技术笔记 › 接口架构设计 统一信封

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}…… 好看,但真实成本在别处:

所以真正的取舍不是"RESTful 好不好",而是「接入成本」和「URL 语义美感」哪个更值钱。 对一个按次计费的数据平台,前者决定转化率。

二、统一路由:一个 GET,method 当分发键

GET https://finewisdom.top/api?token=fw_xxx&method=douyin_video_comments&aweme_id=...&page=0

好处很直接:

代价也要说清楚:丢了 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"付钱。

四、计费的工程含义:预扣 + 回滚 + 幂等

"成功才扣费"写进文案只要一句话,落到工程上是三件事:

  1. 预扣:请求进来先冻结一次单价,防止并发把余额扣成负数;
  2. 回滚:失败、超时、上游异常时把冻结额度退回;
  3. 幂等:同一个请求重试不应该扣两次(按 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 的反馈很直白:

可落地的解法不是"砍工具",而是让每个描述都自带"什么时候用我、什么时候别用我"。 比如 v2/v3 这种同能力多通道,描述里必须写清数据源差异和字段差异,否则模型只能瞎选。

七、版本化:宁可加后缀,不要原地改

taobao_original_detail、jd_comments / jd_comments_v2、 douyin_product_detail / _v2 / _v3 —— 看着乱,但比"原地改返回结构"安全得多。 客户的解析代码是写死的,字段一改就全炸;而新增一个 _v2 只是多一个选项。

规则只有一条:已发布的方法,返回结构只增不改;要改就起新名字。这条比任何命名规范都重要。

常见问题

为什么不用 RESTful 风格?

因为 103 个方法横跨 15 个平台,路径语义无法统一(aweme_id / note_id / bv_id / item_id),统一成一个 GET + method 分发键后,客户只需学一次,新增方法也不用改网关。

统一信封会让返回变大吗?

会多一点(status 和 message 两个字段),换来的是扣费判定可靠、错误可区分。这个交换是明确划算的。

MCP 工具太多会不会影响 Agent 使用?

会。工具超过 25 个后选择成本明显上升,所以工具描述必须写清「什么时候用我」,而不是只写「我返回什么」。

相关场景

电商评论采集 差评分析电商评论挖掘 · 完整代码与分步成本达人筛选 账号画像达人筛选 · 完整代码与分步成本TikTok 选品TikTok 选品 · 完整代码与分步成本

文中提到的接口

xhs_note_comments参数、单价与返回结构jd_comments_v2参数、单价与返回结构douyin_product_detail_v3参数、单价与返回结构item_review_1688参数、单价与返回结构