RESTful 风格的接口命名规范

近期在实习项目中，负责人要求调研 RESTful 风格的接口命名规范，并对项目现有的 URL 命名进行规范化调整。以下是基于此次调研整理的 RESTful 接口设计心得与规范总结。

什么是 RESTful

REST 是 REpresentational State Transfer（表征状态转移）的缩写。它是一套风格约定（Style Constraint），而 RESTful 是其形容词形式，用于描述符合 REST 风格的接口或系统。

目前，许多项目仅使用 GET 和 POST 两种 HTTP 方法，如下所示。这种做法无疑浪费了 HTTP 协议的潜力，而 REST 风格则充分利用了 HTTP 规范中的方法，实现了接口描述的语义化。

HTTP 方法使用现状
RESTful 方法示意

REST 描述了 HTTP 层中客户端与服务器端的数据交互规则：客户端通过发送 HTTP/HTTPS 请求，接收服务器响应，完成一次交互。在此过程中，REST 架构主要约定了两个核心方面：HTTP 请求方法 与 请求链接（URL）。

因此，REST 规范可以抽象为以下两条核心规则：

  • URL：用于定位资源（Resource）；
  • METHOD：用于表示对资源进行的操作（Action）。

以下将基于这两条规则，详细描述如何构造符合 REST 规范的请求。

一、API 的 URL 设计

URL 用于定位资源，应与具体操作区分开。这意味着 URL 路径中不应包含动词。

1.1 避免在路径中使用动词

以下示例中的 get、create、search 等动词，都不应该出现在 REST 架构的后端接口路径中：

/api/getUser
/api/createApp
/api/searchResult
/api/deleteAllUsers

1.2 针对单个资源的操作

当需要对单个用户进行操作时，不应通过 URL 动词区分，而应通过 HTTP 方法区分。错误的示例如下：

/api/getUser      （获取某个用户信息，需传入 ID）
/api/updateUser   （更新用户信息）
/api/deleteUser   （删除单个用户）
/api/resetUser    （重置用户信息）

1.3 避免针对字段细分接口

在更新用户不同信息时，也不应提供细分接口，例如：

/api/updateUserName
/api/updateUserEmail
/api/updateUser

1.4 设计总结

上述三种情况的弊端在于：

  1. 引入动词导致 URL 过长；
  2. 对同一资源实体的不同操作对应不同 URL，导致接口数量过多，难以管理。

回顾 URL（Uniform Resource Locator，统一资源定位符）的定义，其本质是定位资源，而非描述操作行为。

在 REST 架构中，链接设计应遵循以下原则：

  1. 名词化：URL 中不应出现表示操作的动词，链接仅用于对应资源；
  2. 复数形式：URL 中建议统一使用资源复数形式。例如 GET /api/users 表示获取用户列表；若获取单个资源，则传入 ID，如 /api/users/123 表示获取 ID 为 123 的用户信息；

  3. 层级嵌套：按照资源的逻辑层级对 URL 进行嵌套。例如，用户属于团队，团队属于组织。获取某团队下某成员的接口可设计为：

    GET /api/teams/123/members/234

    表示获取 ID 为 123 的团队下，ID 为 234 的成员信息。

    按照类似规则，可衍生出以下接口结构：

    • /api/teams：对应团队列表
    • /api/teams/123：对应 ID 为 123 的团队
    • /api/teams/123/members：对应 ID 为 123 的团队下的成员列表
    • /api/teams/123/members/456：对应 ID 为 123 的团队下 ID 为 456 的成员

二、API 请求方法

在 REST 架构中，除了 GET 和 POST，还应充分利用以下 HTTP 方法：GET、POST、PUT、PATCH、DELETE。

以下重点介绍更新与删除操作对应的方法。

2.1 更新操作（PUT 与 PATCH）

Update 操作用于更新资源，对应的 HTTP 方法有两个：PUT 和 PATCH。两者都应实现为幂等方法，即多次相同的更新请求对服务器产生的副作用相同。

  • PUT：用于更新资源的全部信息。请求 Body 中需要传入修改后的完整资源主体。
  • PATCH：用于局部更新。请求 Body 中只需传入需要改动的资源字段。

PATCH 的优势：当资源字段较多时，局部更新只需传输变更字段。若使用 PUT，则需将整个资源模型发送回服务器，造成网络资源浪费。

2.2 删除操作（DELETE）

Delete 操作用于删除资源，对应的 HTTP 方法为 DELETE。该方法也应实现为幂等方法。

示例：

DELETE /api/users/123

用于删除服务器上 ID 为 123 的资源。多次请求的副作用一致，即确保服务器上 ID 为 123 的资源不存在。

三、过滤与查询

REST 风格的接口地址可能指向单个资源，也可能指向资源集合。访问资源集合时，设计良好的接口应支持通过参数过滤，仅返回满足特定条件的资源列表。

支持关键词搜索与排序：

GET /api/users?keyword=libinm&sort=classId

支持根据字段过滤：

GET /api/users?gender=1

遵循此类规范后，通过观察接口即可理解其 CRUD 操作意图。例如以下接口表示：搜索 ID 为 123 的图书馆中的书籍，书籍信息包含关键字「game」，按价格排序，返回前 10 条结果。

GET /api/libraries/123/books?keyword=game&sort=price&limit=10&offset=0

四、标准结构与设计示例

标准的 API URL 格式建议如下：

http(s)://server.com/app-name/{version}/{domain}/{rest-convention}
  • {version}：代表 API 的版本信息。
  • {domain}：用于定义技术区域（如安全域，允许指定用户访问）或业务区域（如相同功能归于同一前缀）。
  • {rest-convention}：代表该域下约定的 REST 接口集合。

以下是常见的资源设计场景示例：

  • 单资源 (singular-resource)

    • URL 样例：/order/（order 指单独的资源 X）
    • GET：返回一个新的 order 实例
    • POST：创建一个新的 order，值从请求体中获取

  • 单资源带 ID (singular-resource/{id})

    • URL 样例：/order/1
    • GET：返回 ID 为 1 的 order
    • DELETE：删除 ID 为 1 的 order
    • PUT：更新 ID 为 1 的 order，值从请求体中获取

  • 复数资源 (plural-resources)

    • URL 样例：/orders/
    • GET：返回所有 orders

  • 复数资源查找 (plural-resources/search)

    • URL 样例：/orders/search?name=123
    • GET：返回所有满足查询条件的 order 资源（例如 order 名字等于 123）

  • 复数资源特定条件查找 (plural-resources/searchByXXX)

    • URL 样例：/orders/searchByItems?name=ipad
    • GET：返回所有满足自定义查询的 orders（例如获取所有与 items 名字为 ipad 相关联的 orders）

  • 单资源下的复数子资源 (singular-resource/{id}/plural-resources)

    • URL 样例：/order/1/items/
    • GET：返回所有与 order ID 为 1 关联的 items

  • 单资源下的单数子资源 (singular-resource/{id}/singular-resource)

    • URL 样例：/order/1/item/
    • GET：返回一个瞬时的新的与 order ID 为 1 关联的 item 实例
    • POST：创建一个与 order ID 为 1 关联的 item 实例，值从请求体中获取

  • 多层级单资源嵌套 (singular-resource/{id}/singular-resource/{id}/singular-resource)

    • URL 样例：/order/1/item/2/package/
    • GET：返回一个瞬时的新的与 item 2 和 order 1 关联的 package 实例
    • POST：创建一个新的与 item 2 和 order 1 关联的 package 实例，值从请求体中获取

上述规则可递归应用。需注意，复数资源路径后通常不再跟随复数资源。

关键点总结：

  • 使用复数资源时，返回的是最后一个复数资源对应的实例集合。
  • 使用单个资源时，返回的是最后一个单数资源对应的实例。
  • 查询操作时，返回的是最后一个复数实体对应的实例集合。

五、其他命名规范

除上述结构外，还需遵循以下 URI 设计规范：

  1. 结尾斜杠：URI 结尾不应包含斜杠（/）。
  2. 层级分隔：必须使用正斜杠（/）来指示层级关系。
  3. 可读性：应使用连字符（-）来提高 URI 的可读性（例如 user-profile）。
  4. 禁止下划线：不得在 URI 中使用下划线（_）。
  5. 大小写：URI 路径中应全部使用小写字母。
说明：文中部分图片链接来源于 2019 年，接口设计实践可能随技术演进有所更新，请结合当前项目实际需求参考适用。