Restful Api 设计规范

RESTful API（Representational State Transfer API）是一种基于 HTTP 的网络接口设计风格，广泛用于网络应用之间的交互。REST 本质上是一组架构原则和约束，而不是具体的标准或协议。一个 Web 服务被称为“RESTful”，意味着它遵循 REST 的设计原则，提供高效、可靠且可扩展的网络服务。

RESTful 设计强调无状态通信，每个请求都应包含处理该请求所需的所有信息，服务器不应维护客户端的会话状态。此外，RESTful API 采用分层架构，允许系统的不同部分独立扩展和优化。

unsetunset1. URI 设计unsetunset

RESTful API 采用清晰且易读的 URI（统一资源定位符）来表示资源（宾语），而使用 HTTP 方法（如 GET、POST、PUT、DELETE）来表示对资源的操作（动词）。遵循以下最佳实践可以确保 API 的一致性和可维护性。

1.1 HTTP 方法与 CRUD 操作的映射

示例

GET /users           # 获取所有用户
GET /users/123       # 获取 ID 为 123 的用户
POST /users          # 创建新用户
PUT /users/123       # 更新 ID 为 123 的用户信息
PATCH /users/123     # 部分更新用户信息
DELETE /users/123    # 删除 ID 为 123 的用户

1.2 URL 设计原则

✅ 使用名词表示资源，而非动词

错误示例：

/getAllUsers
/createNewUser
/deleteAllOrders

正确示例：

/users
/orders

URI 应该专注于资源的表示，而非操作行为。

✅ 使用复数形式表示集合

/users       # 表示所有用户
/users/123   # 表示某个特定用户

✅ 使用嵌套关系表示层级

/users/123/posts       # 获取用户 123 发表的所有文章
/posts/456/comments    # 获取文章 456 的所有评论

✅ 避免过深的 URL 层级

❌ 不推荐：

GET /users/123/orders/456/items/789

✅ 推荐：

GET /orders/456/items/789

对于复杂的查询，可以使用查询参数：

GET /orders?user_id=123

unsetunset2. HTTP 状态码unsetunset

RESTful API 通过 HTTP 状态码指示请求结果，正确使用状态码可以减少客户端的解析成本，提高交互的清晰度。

2.1 常见状态码

示例

HTTP/1.1 201 Created
Location: /users/123
Content-Type: application/json
{
  "id": 123,
  "name": "John Doe"
}

unsetunset3. 服务器响应格式unsetunset

3.1 统一使用 JSON 作为返回格式

RESTful API 应返回结构化的 JSON 数据，并在响应头中指定：

Content-Type: application/json

示例

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}

3.2 发生错误时返回适当的状态码

错误信息应提供足够的上下文，帮助客户端理解问题。

❌ 错误示例（不推荐）

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "failure",
  "error": "Invalid user ID"
}

✅ 推荐：

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "Invalid user ID",
  "detail": "User ID must be a positive integer"
}

3.3 API 响应应包含链接（HATEOAS）

在 RESTful 设计中，返回的 JSON 结构可以包含指向相关资源的链接。

示例

{
  "id": 123,
  "name": "John Doe",
  "_links": {
    "self": { "href": "/users/123" },
    "orders": { "href": "/users/123/orders" }
  }
}

unsetunset4. API 设计最佳实践unsetunset

✅ 4.1 一致性

所有资源的 URL 结构应保持一致，避免混用不同的风格。例如，不要在同一 API 中既使用 /user 又使用 /users。

✅ 4.2 采用分页机制

对于返回大量数据的请求，应提供分页参数：

GET /users?page=2&limit=20

标准响应格式：

{
  "total": 100,
  "page": 2,
  "limit": 20,
  "data": [
    { "id": 21, "name": "Alice" },
    { "id": 22, "name": "Bob" }
  ]
}

✅ 4.3 允许跨域访问（CORS）

如果 API 需要支持跨域请求，应在响应头中添加：

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE

✅ 4.4 避免暴露敏感信息

• API 响应不应包含数据库 ID 或密码哈希。
• 仅返回客户端所需的字段，避免返回不必要的数据。

✅ 4.5 采用版本控制

避免在 URL 级别硬编码版本号，如 /v1/users，推荐使用 HTTP 头：

Accept: application/vnd.myapi.v1+json

unsetunset5. 结论unsetunset

RESTful API 设计强调资源的表述、无状态交互和标准化 HTTP 方法。通过遵循一致的 URL 规则、合理使用状态码、提供结构化的 JSON 响应、优化性能（如分页、缓存）以及实现安全性控制（如身份验证和 CORS），我们可以构建一个高效、易扩展、可维护的 API。

RESTful 设计不仅使 API 更具可读性，也提升了开发和使用的便捷性。良好的 API 设计是构建现代 Web 应用程序的关键。