RESTful API 设计最佳实践指南

设计良好的 API 应该是易于理解、易于使用且难以误用的。REST（Representational State Transfer）是目前最主流的 API 设计风格。

核心原则

1. 面向资源: URI 应该代表资源，使用名词（如 /users），避免动词（如 /getUsers）。
2. 使用 HTTP 动词:
   • GET: 获取资源
   • POST: 创建资源
   • PUT: 全量更新资源
   • PATCH: 部分更新资源
   • DELETE: 删除资源
3. 状态码: 正确使用 HTTP 状态码（200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Server Error）。
4. 版本控制: 在 URL 或 Header 中包含版本号（如 /v1/users），保证向后兼容性。
5. 分页与过滤: 对于返回列表的接口，必须支持分页（page, limit）和过滤，防止一次性返回过多数据。