接口地址命名规范：为什么推荐 RESTful 风格？

水无痕
· 3 分钟阅读
接口地址命名规范：为什么推荐 RESTful 风格？
接口地址命名规范：为什么推荐 RESTful 风格？

在浏览不同项目的代码时，你可能会发现接口地址的写法千差万别：有的叫 /getUser，有的叫 /api/users，还有的叫 /api/users/123。这些写法背后究竟有什么讲究？是否有一套通用的规范？

缺乏规范的混乱现状

如果没有统一的命名规范，一个项目中的接口可能会呈现出如下混乱的状态：

  • 查询用户：/getUser
  • 删除用户：/DeleteUser
  • 修改用户：/UpdateUserInfo
  • 新增用户：/AddNewUser

缺乏规范的混乱接口现状

虽然这些接口在功能上可能都能跑通，但存在明显的问题：

  1. 命名风格不统一：动词和名词的大小写、组合方式随意。
  2. 长度参差不齐：有的简短，有的冗长。
  3. 维护成本高：前端对接时需要逐个查阅文档，一旦更换维护人员，理解成本极高。

核心设计思路：资源与动作分离

接口地址设计的核心原则只有一条：地址表示资源是什么，HTTP 方法表示要做什么操作。

资源与动作分离的核心原则

1. 地址表示资源（名词）

URL 路径中应使用名词来标识资源，而不是动词。

  • 集合资源：用户列表对应 /users，订单列表对应 /orders。
  • 具体资源：某个特定用户对应 /users/123，其中斜杠后的数字代表该数据的 ID。

通过这种方式，仅看地址就能明确知道操作的对象是什么，无需通过名字去猜测。

2. 动作由 HTTP 方法区分

具体的操作行为（增删改查）应交给 HTTP 方法（Method）来处理，而不是写在 URL 中：

  • GET：查询资源
  • POST：新建资源
  • PUT / PATCH：修改资源
  • DELETE：删除资源

以 /users/123 为例：

  • 发送 GET 请求：查询 ID 为 123 的用户。
  • 发送 DELETE 请求：删除 ID 为 123 的用户。
  • 发送 PATCH 请求：修改 ID 为 123 的用户的部分字段。

HTTP 方法对资源的操作映射

地址保持不变，动作由方法区分。 这样避免了在地址中重复出现 get、delete 等动词。

新旧写法对比

通过对比可以更直观地看出 RESTful 风格的优势：

操作 传统写法 (动词式) RESTful 写法 (资源式)
查询用户 GET /getUser?id=123 GET /users/123
删除用户 DELETE /deleteUser?id=123 DELETE /users/123
修改用户 POST /updateUser PATCH /users/123

传统写法与 RESTful 写法对比

RESTful 风格的优势：

  1. 地址更短：去除了冗余的动词。
  2. 含义更清晰：资源与动作职责分明。
  3. 接口数量减少：同一资源的不同操作共用同一地址，降低了路由配置的复杂度。

例外情况与最佳实践

虽然 RESTful 风格是主流推荐，但并非所有接口都适合强行套用此模式。以下场景通常需要根据业务灵活处理：

  • 登录/认证：通常使用 /login 或 /auth。
  • 搜索：涉及复杂查询条件，可能使用 /search。
  • 批量操作：如批量删除、批量更新，可能需要特定的接口设计。

对于日常的增删查改（CRUD）操作，坚持“名词地址 + HTTP 方法”的思路，能让接口文档更加清晰。此外，在与 AI 协作编程时，结构清晰的接口定义也能帮助 AI 更准确地理解你的系统架构，从而生成更高质量的代码。

你觉得哪种接口命名方式更清晰？欢迎在评论区分享你的观点。