接口设计的十个决定：从状态码到分页策略

接口一旦被客户端依赖，改动成本就很高。所以设计阶段多花一小时，后面能省几十小时。

最容易被忽略的不是 RESTful 风格，而是错误结构、分页与幂等这三件事。

先说结论

状态码表语义、错误统一结构、列表必须分页、写操作考虑幂等。

• 2xx 成功 / 4xx 客户端错 / 5xx 服务端错
• 错误体统一含 code、message、request_id
• 分页用游标（cursor）避免深翻页
• 支付、下单类接口支持幂等键

先把问题说清楚

客户端最讨厌两件事：错误信息不可读、分页越翻越慢。这两件事都可以在设计阶段解决。

游标分页依赖稳定排序字段（时间 + id），比 offset 更适合大数据量。

具体怎么做

按顺序执行，每步都验证完再进下一步：

• 先定资源模型与路径命名（复数、名词）
• 定义状态码使用规则，避免全用 200
• 设计统一错误结构，包含可读 message 与 trace id
• 列表接口默认分页，提供 cursor 与 limit
• 为写接口设计幂等键与重试语义

参数与成本对照

把关键数值摊开，方便判断该选哪条路：

几个容易踩的坑

下面这些是最常见的错误做法：

• 全用 200 + 业务码：监控与网关无法判断错误
• 返回 stack trace：泄露内部结构
• offset 分页到十万条：查询越来越慢
• PUT 与 POST 语义混用

最后补两句

好接口的标准：不看文档也能猜对，出错时能看懂。

工具是手段，理解机制才是能力。命令记不住没关系，知道「该看什么」就够了。