一个 API 项目是否顺手，并不完全取决于框架，而是取决于接口设计是否一致。字段名乱、状态码随意、分页结构不统一、错误响应风格不一致，这些问题会快速放大前后端协作成本。这一篇会把最基础也最常见的接口设计问题集中梳理出来。
为什么资源命名比“路径好不好看”更重要？
接口路径不是随便凑出来的字符串，它背后代表的是你如何理解系统里的资源边界。如果资源概念本身不清楚，那么路径再短再整齐也没太大意义。
比如一个接口到底是在表达：
- 用户资源；
- 文章资源；
- 评论资源；
- 还是某种业务动作。
只要这层边界不清楚，后面状态码、字段和权限规则也很容易跟着混乱。
从这个角度看，资源命名其实是在给整个 API 定世界观。你到底是在围绕资源建模，还是围绕页面动作堆接口，最后会直接影响路由组织、权限判断、缓存策略和前端理解成本。路径看起来只是字符串，背后其实是系统边界的表达。
状态码为什么不能随意用？
状态码不是附属信息，而是接口对外契约的一部分。它帮助调用方快速判断：这次请求是成功了、参数错了、权限有问题，还是资源根本不存在。
如果一个项目里：
- 创建成功有时返回 200，有时返回 201；
- 参数错误和权限错误都混成同一种状态；
- 找不到资源却返回一切正常；
那前后端协作和问题定位都会变得非常痛苦。也就是说，状态码的一致性不只是“讲究”，而是接口可理解性的基础。
更重要的是，状态码应该先回答“大类判断”，而不是把所有语义都塞进响应体。调用方首先要知道这是成功、客户端错误、权限问题还是服务端异常，至于更细的业务信息，再由统一错误结构去表达。
错误响应为什么也需要统一？
很多项目只重视成功响应，觉得错误情况“报个 message 就行”。但在真实协作里，错误响应同样需要稳定结构。原因很简单：调用方也需要根据错误内容做判断、提示和降级。
一个成熟的错误响应通常至少应该让人知道：
- 这是哪一类错误；
- 是参数问题、权限问题还是系统问题；
- 是否适合直接展示给用户；
- 是否需要前端或调用方做特殊处理。
如果错误响应完全没有结构，那它就只能当字符串日志看，很难真正成为契约。
一个稳定的错误响应模型，通常至少会让调用方能依赖这几件事：
- 错误类别是否可判断；
- 文案是否适合直接展示；
- 是否包含可定位的问题字段或错误码；
- 是否能和日志、监控里的错误链路对应起来。
只要这套结构稳定，调用方做表单提示、重试、降级和埋点都会轻松很多。
为什么分页和筛选要尽早定规范？
列表接口几乎是任何业务系统都会有的东西，而分页和筛选又是列表接口中最容易被“先凑合一下”的部分。结果就是后面很容易出现：
- 有的接口用
page，有的用offset； - 有的返回
items，有的返回list； - 有的返回总数，有的完全不返回；
- 筛选参数命名也前后不一致。
这种不一致会迅速放大前端适配成本，也会让接口维护越来越难。所以，分页、排序、筛选和统一响应结构越早形成规范，后面越省事。
尤其是列表接口一旦多起来，规范缺失会迅速积累成历史包袱。因为每个新接口都在重复做一次分页设计决策，而这些决策往往又互相不兼容。与其后面大规模回收，不如在第一批接口时就把命名、返回结构和边界条件尽量稳住。
一个更顺手的 API 契约通常要提前统一什么？
如果把这一篇压缩成一套很实用的接口基线，通常至少包括：
- 资源命名尽量稳定，动作型接口保持克制；
- 状态码表达大类语义，不乱用成功态；
- 成功响应和错误响应都保持统一结构；
- 列表接口的分页、排序、筛选参数保持一致；
- 调用方能够通过契约而不是猜测来使用接口。
总结
这一篇我们把接口设计最基础也最容易失控的几个点串起来了：资源命名决定接口边界，状态码和错误响应决定契约表达，而分页和筛选则决定列表接口是否长期一致。
接口设计真正难的地方，从来不是路由路径怎么写，而是能不能形成一套前后端都能稳定依赖的规则。
下一篇我们会继续把这条契约主线推进到输入输出校验和序列化层。