RESTful API 作为一种基于 REST（Representational State Transfer）架构风格的 API 设计方法，凭借其简洁性、可扩展性和无状态性，已成为业界事实标准。根据 2026 年 API 调查报告，83% 的公共 API 采用 RESTful 风格，而在企业内部微服务中，这一比例高达91%。
然而，设计一个优秀的 RESTful API 并非易事。许多开发者在设计 API 时常常遇到以下问题：
❌ 资源命名不规范，URL 混乱难懂
❌ HTTP 方法使用不当，混淆 GET 和 POST
❌ 状态码滥用，无法准确反映操作结果
❌ 缺乏版本控制，升级导致兼容性问题
❌ 错误处理不统一，客户端难以处理异常
❌ 安全机制薄弱，存在数据泄露风险
本文将系统性地介绍 RESTful API 设计的最佳实践，涵盖从基础概念到高级特性的完整知识体系。通过 3 个架构图、2 个实战案例和大量代码示例，帮助你设计出专业、规范、易用的 RESTful API。
二、RESTful 核心概念
2.1 什么是 REST？
REST（Representational State Transfer）是一种软件架构风格，由 Roy Fielding 在 2000 年的博士论文中首次提出。REST 不是协议，也不是标准，而是一组设计原则和约束。
REST 的六大约束：
1 2 3 4 5 6 7 8 9 10 11 12 13 14
graph TB A[REST 架构] --> B[客户端 - 服务器分离] A --> C[无状态] A --> D[可缓存] A --> E[统一接口] A --> F[分层系统] A --> G[按需代码] B --> B1[前端专注 UI<br/>后端专注数据] C --> C1[每个请求包含<br/>所有必要信息] D --> D1[响应可缓存<br/>提升性能] E --> E1[资源标识<br/>操作标准化] F --> F1[隐藏实现细节<br/>提高可扩展性] G --> G1[动态下载执行代码<br/>如 JavaScript]
2.2 RESTful API 的核心要素
1. 资源（Resource）
资源是 RESTful API 的核心概念。任何事物都可以被视为资源，如用户、订单、商品等。每个资源通过URI（统一资源标识符） 唯一标识。
1 2 3 4 5
# 资源示例 /users # 用户集合 /users/123 # ID 为 123 的用户 /orders # 订单集合 /orders/456 # ID 为 456 的订单
sequenceDiagram participant Client as 客户端 participant API as RESTful API participant DB as 数据库 Client->>API: POST /users (创建) API->>DB: INSERT INTO users DB-->>API: 返回 ID=123 API-->>Client: 201 Created + Location: /users/123 Client->>API: GET /users/123 (获取) API->>DB: SELECT * FROM users WHERE id=123 DB-->>API: 返回用户数据 API-->>Client: 200 OK + 用户 JSON Client->>API: PUT /users/123 (更新) API->>DB: UPDATE users SET ... DB-->>API: 更新成功 API-->>Client: 200 OK + 更新后数据 Client->>API: DELETE /users/123 (删除) API->>DB: DELETE FROM users WHERE id=123 DB-->>API: 删除成功 API-->>Client: 204 No Content
三、资源命名规范
3.1 使用名词，避免动词
RESTful API 的核心是资源，而非操作。URL 应该使用名词表示资源，操作通过 HTTP 方法表达。
1 2 3 4 5 6 7 8 9 10 11 12
✅ 正确做法： GET /users # 获取用户列表 POST /users # 创建用户 GET /users/123 # 获取用户详情 PUT /users/123 # 更新用户 DELETE /users/123 # 删除用户
❌ 错误做法： GET /getUsers POST /createUser POST /updateUser POST /deleteUser
# 用户相关 GET /users # 获取用户列表 POST /users # 创建用户 GET /users/{id} # 获取用户详情 PUT /users/{id} # 更新用户（全量） PATCH /users/{id} # 更新用户（部分） DELETE /users/{id} # 删除用户
# 订单相关 GET /orders # 获取订单列表 POST /orders # 创建订单 GET /orders/{id} # 获取订单详情 PUT /orders/{id} # 更新订单 DELETE /orders/{id} # 删除订单
# 嵌套资源 GET /users/{id}/orders # 获取用户的订单 GET /orders/{id}/items # 获取订单的商品
# 子资源操作 POST /users/{id}/avatar # 上传用户头像 GET /users/{id}/followers # 获取用户的粉丝 POST /users/{id}/follow # 关注用户
四、HTTP 方法使用规范
4.1 标准 HTTP 方法
RESTful API 应充分利用 HTTP 协议的标准方法，每种方法都有明确的语义。
1 2 3 4 5 6 7 8 9 10 11 12
graph LR A[HTTP 方法] --> B[GET] A --> C[POST] A --> D[PUT] A --> E[PATCH] A --> F[DELETE] B --> B1[获取资源<br/>安全/幂等] C --> C1[创建资源<br/>不安全/不幂等] D --> D1[全量更新<br/>不安全/幂等] E --> E1[部分更新<br/>不安全/幂等] F --> F1[删除资源<br/>不安全/幂等]
# 2xx 成功 200 OK # 请求成功（GET/PUT/PATCH） 201 Created # 资源创建成功（POST） 204 No Content # 请求成功，无返回内容（DELETE）
# 3xx 重定向 301 Moved Permanently # 资源永久移动 304 Not Modified # 资源未修改（缓存）
# 4xx 客户端错误 400 Bad Request # 请求格式错误 401 Unauthorized # 未认证 403 Forbidden # 无权限 404 Not Found # 资源不存在 409 Conflict # 资源冲突（如重复） 422 Unprocessable Entity # 数据验证失败 429 Too Many Requests # 请求过多（限流）
# 5xx 服务器错误 500 Internal Server Error # 服务器内部错误 502 Bad Gateway # 网关错误 503 Service Unavailable # 服务不可用
5.2 状态码选择指南
1 2 3 4 5 6 7 8 9 10 11 12 13 14
graph TD A[请求处理] --> B{认证？} B -->|否 | C[401 Unauthorized] B -->|是 | D{授权？} D -->|否 | E[403 Forbidden] D -->|是 | F{资源存在？} F -->|否 | G[404 Not Found] F -->|是 | H{数据有效？} H -->|否 | I[422 Unprocessable Entity] H -->|是 | J{操作成功？} J -->|是 | K{有返回？} K -->|是 | L[200 OK] K -->|否 | M[204 No Content] J -->|否 | N[500 Internal Server Error]
# 多字段过滤 GET /users?status=active&city=beijing&role=admin
# 范围过滤 GET /orders?created_at[gte]=2026-01-01&created_at[lte]=2026-03-12
# 模糊搜索 GET /users?name[john]=contains
# IN 查询 GET /users?role[in]=admin,user
7.3 排序
1 2 3 4 5 6 7 8
# 单字段排序 GET /users?sort=created_at
# 多字段排序 GET /users?sort=created_at,-name
# 指定方向 GET /users?sort[created_at]=desc&sort[name]=asc
7.4 字段选择
1 2 3 4 5
# 只返回指定字段 GET /users?fields=id,name,email
# 嵌套资源字段选择 GET /users?fields=id,name&include=orders&fields[orders]=id,total
八、安全与认证
8.1 认证方式对比
1 2 3 4 5 6 7 8 9 10
graph TB A[认证方式] --> B[API Key] A --> C[JWT] A --> D[OAuth 2.0] A --> E[Basic Auth] B --> B1[简单<br/>适合服务端<br/>❌ 无过期] C --> C1[无状态<br/>适合移动端<br/>✅ 推荐] D --> D1[授权流程<br/>适合第三方<br/>✅ 标准] E --> E1[基础认证<br/>❌ 不推荐生产]
# 用户相关 POST /api/v1/users # 注册 POST /api/v1/auth/login # 登录 GET /api/v1/users/me # 获取当前用户 PUT /api/v1/users/me # 更新用户信息 POST /api/v1/users/me/avatar # 上传头像
# 商品相关 GET /api/v1/products # 商品列表 GET /api/v1/products/{id} # 商品详情 POST /api/v1/products # 创建商品（管理员） PUT /api/v1/products/{id} # 更新商品 DELETE /api/v1/products/{id} # 删除商品 GET /api/v1/categories # 分类列表 GET /api/v1/categories/{id}/products # 分类下商品
# 购物车 GET /api/v1/cart # 获取购物车 POST /api/v1/cart/items # 添加商品 PUT /api/v1/cart/items/{id} # 更新数量 DELETE /api/v1/cart/items/{id} # 删除商品
# 订单 POST /api/v1/orders # 创建订单 GET /api/v1/orders # 订单列表 GET /api/v1/orders/{id} # 订单详情 POST /api/v1/orders/{id}/pay # 支付订单 POST /api/v1/orders/{id}/cancel # 取消订单 POST /api/v1/orders/{id}/refund # 申请退款
# 评价 POST /api/v1/orders/{id}/review # 创建评价 GET /api/v1/products/{id}/reviews # 商品评价列表