API 设计入门：先想清楚这五个问题，再写第一行代码

很多新手开发者第一次设计 API 时，习惯直接动手写接口：先定一个 URL，再拼几个参数，调通了就算完成。等到前端同事来对接，才发现字段含义不清、错误码全靠猜、改一个字段就全线崩溃。API 是前后端、系统与系统之间的契约，写得好不好，直接决定了联调的痛苦程度。动手之前，先想清楚下面五个问题。

一、这个接口到底给谁用？

API 的第一位用户不是服务器，而是调用它的人。可能是前端同事，可能是另一个微服务，也可能是第三方开发者。把调用方的视角放在前面，命名和结构就会自然很多。

先写一句人话说明：这个接口是用来“做什么”的。比如“根据订单号查询订单的当前状态”，而不是“获取 OrderInfo”。一句话说不清用途的接口，往往职责不清。接着列出调用方最关心的三件事：需要传什么、会返回什么、出问题时怎么知道。把这三件事想清楚，接口文档的骨架就有了。

二、资源怎么命名？

REST 风格里，URL 描述的是资源，而不是动作。用名词的复数形式表示集合，比如 /users、/orders；单个资源用 /users/{id}。动作交给 HTTP 方法表达：GET 查、POST 建、PUT 全量改、PATCH 局部改、DELETE 删。

新手最常见的错误，是把动词塞进 URL，比如 /getUserList、/deleteOrder。这类 URL 一旦多了，维护和记忆成本都会上升。动词应该出现在方法里，而不是路径里。另外，层级不要太深，一般不超过三层，太深的嵌套既难读也难改。

三、版本号放在哪里？

接口一定会变，问题只是早晚。发布第一天就把版本机制定下来，是成本最低的一次性投入。常见做法是把版本放在路径里，如 /v1/users；也有放在请求头里的。路径版本更直观，调试和排查都方便，推荐新手优先使用。

定了版本号，就要守住一条规矩：已发布的版本只做加法，不做破坏性修改。新增字段可以，老字段改名、改类型、删字段都不行。实在要改，就发新版本，让旧版本继续跑一段时间，给调用方留出迁移窗口。

四、出错时，调用方怎么知道错在哪？

好的错误返回有三个要素：HTTP 状态码、业务错误码、人类能读懂的提示。状态码表达“哪一类错”：400 是请求有问题，401 是没登录，403 是没权限，404 是资源不存在，500 是服务端出问题。业务错误码表达“具体是什么错”，比如 10001 表示“订单号格式错误”。提示信息要写给人看，而不是把异常堆栈直接甩出去。

另外，成功和失败的返回结构要保持一致。建议统一包一层：code、message、data 三个字段，成功时 code 为 0，失败时 data 为空。这样调用方写一次解析逻辑就能复用，不用每个接口单独处理。

五、分页、幂等和限流，别等上线才补

列表接口几乎都要分页。统一用 page 和 page_size 两个参数，返回里带上 total，让调用方知道一共有多少条。默认每页 20 条，上限 100 条，避免一次返回全表数据把服务拖垮。

涉及钱和状态变更的接口要考虑幂等：同一个请求重复发多次，结果和发一次一样。常用做法是让调用方传一个唯一请求号，服务端用它做去重。网络抖动导致重试时，幂等能避免重复下单、重复扣款。

限流则是保护服务的安全阀。给每个调用方设定合理的每秒请求上限，超限返回 429 状态码。这既防止误调用，也防止恶意刷接口。

最后，写完接口先写文档和示例

很多团队的文档是“事后补”的，接口上线了，文档还停留在三天前的版本。建议把文档当作接口的一部分：接口写完，顺手写一段调用示例，包括请求示例和返回示例，字段含义逐条说明。对照示例自测一次，经常能发现自己设计里的别扭之处。

API 设计没有银弹，但有一条朴素的标准：一个没见过这套接口的人，能不能在不问你的情况下，靠文档把第一次调用跑通。如果能，这份设计就是合格的。先想清楚这五个问题，再写第一行代码，联调时你会感谢现在的自己。