RESTful

简单易用：基于 HTTP 协议，使用常见的 GET、POST、PUT、DELETE 等方法，易于理解和实现。
无状态性：每个请求都是独立的，服务器不需要保存客户端状态，便于扩展和维护。
资源导向：以资源为核心，URL 结构清晰，易于管理和文档化。
跨平台支持好：可以被各种语言和平台调用，兼容性强。
可缓存性：HTTP 协议自带缓存机制，提高性能。
与 Web 技术天然集成：易于与浏览器、前端框架等集成。

缺点：

• 功能有限：仅支持 HTTP 协议，无法实现一些高级特性（如双向通信、事务等）。
• 安全性需额外设计：需要自行实现认证、授权等安全机制（如 OAuth、JWT 等）。
• 无状态带来的问题：某些场景下需要频繁传递重复信息，增加带宽消耗。
• 标准不够严格：实现方式灵活，可能导致不同团队风格不一致，影响协作。
• 对复杂操作支持不佳：对于批量操作或复杂事务处理不如传统 API 灵活。

总结：
RESTful API 更适合互联网应用、微服务等场景，简单、易扩展，但在需要复杂协议支持或强事务保障时，传统 API 可能更合适。

---

RESTful API 示例

假设有一个“用户”资源：

操作	HTTP 方法	URL	说明
获取所有用户	GET	/users	查询用户列表
获取指定用户	GET	/users/	查询单个用户
创建新用户	POST	/users	新增用户
更新用户信息	PUT/PATCH	/users/	修改用户信息
删除用户	DELETE	/users/	删除用户

每个操作都直接对应 HTTP 方法，URL 结构清晰。

---

传统 API 示例（如基于 RPC 或 SOAP）

操作	HTTP 方法	URL	参数	说明
获取所有用户	POST	/api	method=getAll	查询用户列表
获取指定用户	POST	/api	method=getById	查询单个用户
创建新用户	POST	/api	method=create	新增用户

所有操作都通过同一个端点（如 /api），通过参数区分具体方法，结构不如 RESTful 直观。

---

总结
RESTful API：URL 语义化，操作直观，易于理解和维护。
传统 API：通常通过单一端点和方法参数实现，结构灵活但不直观，学习和维护成本较高。

---

RESTful 批量操作设计

批量新增（Batch Create）

使用 POST 方法，向资源集合的 URL 发送一个包含多个对象的数组。

POST /users
Content-Type: application/json

[
  { "name": "张三", "email": "zhangsan@example.com" },
  { "name": "李四", "email": "lisi@example.com" }
]

批量删除（Batch Delete）

常见做法有两种：

1. 通过请求体传递要删除的 ID 列表：

DELETE /users
Content-Type: application/json

[1, 2, 3]

2. 或通过查询参数传递：

DELETE /users?ids=1,2,3

注意：部分 HTTP 客户端或服务器对 DELETE 方法带请求体的支持不佳，推荐使用查询参数或 POST + 动作语义（如 /users/batch-delete）。

批量更新（Batch Update）

使用 PUT 或 PATCH 方法，传递对象数组，每个对象包含要更新的 ID 和内容。

PUT /users
Content-Type: application/json

[
  { "id": 1, "email": "new1@example.com" },
  { "id": 2, "email": "new2@example.com" }
]

也可以使用 PATCH /users 批量部分更新。

---

设计建议与最佳实践

• URL 命名应简洁、语义化，使用复数表示资源（如 /users）。
• 推荐使用 HTTP 状态码表达操作结果（如 200、201、204、400、404、500 等）。
• 支持分页、过滤、排序等查询参数（如 /users?page=1&limit=20）。
• 返回统一的数据结构，便于前后端协作和错误处理。
• 对于复杂批量操作，可考虑专门的批量端点（如 /users/batch-update）。
• 文档应详细说明每个接口的请求方法、参数、返回值和示例。

---