RESTful API 设计规范

核心原则

资源导向

API 应围绕资源设计，使用名词而非动词：

• ✅ /users/123
• ❌ /getUsers

HTTP 方法语义

• GET：获取资源
• POST：创建资源
• PUT：更新资源（全量）
• PATCH：更新资源（部分）
• DELETE：删除资源

状态码规范

版本控制

/api/v1/users
/api/v2/users

响应格式

{
  "code": 200,
  "data": { "id": 123, "name": "John" },
  "message": "success"
}

分页设计

GET /users?page=1&limit=20

良好的 API 设计能显著提升开发体验和系统可维护性。