第三世界的妖孽说实话，我见过太多“能用但谈不上好用”的接口了。你问一个后端工程师接口写得怎么样，他会说“没问题啊，都能通”；但如果你去问对接的前端、第三方开发者，甚至两个月后的他自己，答案往往就变成“有点乱”“有些坑”“说不清楚”。我做过后端、写过 SDK、也带过团队，对 RESTful API 设计这件事最大的感悟就是：“优雅”不是一个审美问题，而是一个成本和工程问题。 接口设计得优雅，不只是看着舒服，而是每次联调少返工、每个新人对接少踩坑、每个接口上线后少几个“紧急修复”。这篇文章我想把这些年设计 RESTful 接口的完整思路、踩过的坑、沉淀下来的规范一次性讲透，适合初级后端、对接口规范有追求的工程师、以及前端开发者在设计联调时参考。
1. 先认清：接口的“优雅”到底在解决什么问题
1.1 一个接口给团队带来的隐性成本
很多人设计接口时只考虑“怎么让这次需求跑通”，没有想过一个接口的完整生命周期里，有多少人要跟它打交道。我粗略算过一笔账：一个典型的业务接口，从定义到联调再到上线后的维护，至少要经过后端开发、前端开发（甚至多端）、测试、运维这几双手。如果接口设计得模棱两可，光联调阶段的沟通成本就会翻倍。
举个最直观的例子。我们团队有一个老接口，URL 长这样：/api/updateUserInfo。当时写这个接口的同事已经离职了，新来的前端同学要对接，问了我三个问题：“这个接口是全量更新还是部分更新？”“如果用户不存在，是返回报错还是自动创建？”“password 字段传不传？传空字符串会怎么样？”我答不上来，只能去翻代码。翻完代码又发现一个问题：这个接口内部对“字段不存在”和“字段传空串”的处理完全不一样。就这么一个小接口，前后花了四个人、两个小时的沟通时间才确认清楚。
这种成本是很隐蔽的，它不会出现在需求文档里，也不会被排期你头上，但它真实消耗着每个团队的产能。而好的 API 设计，本质上就是把这些“藏起来的沟通成本”提前用约定消灭掉——让调用方看一眼接口就能猜个八九不离十，不用一次一次找人确认。
1.2 优雅接口的三个可量化特征
我这些年指导团队做接口设计，从来不谈“美观”“风格”之类的虚词，而是把目标收敛成三个可验证的特征：可预测性、自解释性、可演化性。
可预测性，意思是调用方基于对资源和 HTTP 协议的基础认知，就能猜出这个接口大概的行为。比如看到 DELETE /api/orders/123，任何人都能猜到这是“删除订单123”，而不是“把订单移到回收站”或者“软删除但返回200”。自解释性，意思是接口的入参、出参、错误信息合在一起，能让调用方在尽量少查文档的情况下完成对接。可演化性，意思是 v1 上线之后，加字段、加功能不会破坏已有调用方，不需要动不动就推倒重来。
这三条就是我后面所有设计决策的判断标准。一句话说不清楚该不该这样设计时，就拿这三条去卡，基本不会出错。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 资源命名：URL 是接口给调用方的第一印象
2.1 名词复数与层级表达：别在 URL 里写“动作”
REST 的核心思想是“资源”。URL 只应该回答一个问题：我操作的是哪一类东西？ 至于“操作”是什么，交给 HTTP 方法去表达。
很多从 MVC 框架入门的朋友，最容易犯的一个习惯就是把接口写成 RPC 风格，在 URL 里面写动词。我随便列几个看过无数次的反面教材：
text复制/api/createOrder
/api/getUserInfo
/api/order/delete?id=123
/api/checkStock
这种写法不是不能用，而是在“可预测性”上非常差。第一，动词的选取没有标准，同一个团队有人写 delete，有人写 remove，有人写 del，调用方根本没法预测。第二，动作和资源耦合在一起，导致资源的生命周期管理变得混乱。比如 deleteOrder 接口一开始是物理删除，后来业务要求改成只做标记，前端还在调旧接口，后端只能偷偷改逻辑，结果接口名变成了“撒谎”。
正确的做法是让 URL 只描述资源，动词完全交给 HTTP 方法：
text复制POST /api/orders 创建订单
GET /api/orders 查询订单列表
GET /api/orders/123 查询订单详情
PUT /api/orders/123 全量替换订单
PATCH /api/orders/123 局部更新订单
DELETE /api/orders/123 删除订单
同一个资源，五种行为，URL 完全没有重复信息。调用方只需要记住“资源长什么样”，剩下的事情全是 HTTP 协议已经规定好的常识。
2.2 层级与集合：嵌套几层才算合理
资源之间会有从属关系，这就要谈到 URL 的层级设计。我见过最多的问题是“两个极端”：一种是所有接口全部平铺，靠查询参数关联；另一种是一层层嵌套，比如 /api/companies/{companyId}/departments/{departmentId}/employees/{employeeId}/salary，看到第五层人都晕了。
我的判断标准其实很简单：子资源有没有独立的生命周期？ 有，就把它独立出来；没有，就作为嵌套子资源。
拿“公司-员工”举例。如果员工必须属于某个公司，且脱离了公司没有任何独立存在的意义，那 /api/companies/{companyId}/employees 这种