RESTful API设计核心是围绕资源构建清晰契约：用名词定义URL（如/users）、严格匹配HTTP方法语义（GET安全幂等、POST创建等）、使用标准状态码（201 Created、404 Not Found等）、统一响应结构（code/message/data）并支持分页过滤。

设计 RESTful 风格的 API 接口，关键不是堆砌 HTTP 方法或拼凑 URL，而是围绕“资源”建立清晰、一致、可演进的通信契约。它不追求绝对教条，但忽略核心原则容易导致后期维护成本飙升、跨团队协作低效、缓存与安全机制失效。

用名词定义资源，而非动词表达操作

URL 路径应始终代表业务实体（如用户、订单、设备），而不是动作。这是 RESTful 的起点，也是最容易被忽视的一环。

• ✅ 正确：/users、/orders、/devices/{id}/sensors
• ❌ 错误：/getUser、/createOrder、/deleteDevice?id=123
• 复数形式更自然：/products 比 /product 更符合集合语义；/users/123/items 表达归属关系，比 /items?userId=123 更具可发现性
• 避免多级嵌套（超过 3 层），例如 /orgs/a/depts/b/teams/c/members 不如 /members?teamId=c 清晰可控

严格匹配 HTTP 方法语义

每个方法承载明确意图，客户端和服务端据此建立稳定预期。滥用会导致幂等性混乱、缓存失效、前端逻辑错乱。

• GET：只读查询，必须安全且幂等；不带副作用，可被浏览器、CDN、代理缓存
• POST：创建新资源，非幂等；响应应返回 201 Created + Location 头指向新资源地址
• PUT：全量替换指定资源，幂等；要求客户端提供完整资源表示
• PATCH：局部更新，非幂等；适合修改个别字段（如 status 或 tags）
• DELETE：移除资源，幂等；成功后再次调用应返回 404 或 204

用标准状态码传递机器可读的语义

不要所有成功都返回 200 OK，也不要所有失败都塞进 500 Internal Server Error。状态码是协议层的“第一语言”，前端、网关、监控系统都依赖它做自动化决策。

• 200 OK：GET 成功，或 PUT/PATCH 更新成功并返回完整资源
• 201 Created：POST 创建成功，必须附带 Location 头
• 204 No Content：DELETE 成功或 PUT/PATCH 成功但无需返回体
• 400 Bad Request：客户端请求格式错误（如 JSON 解析失败、必填字段缺失）
• 401 Unauthorized：认证凭证缺失或无效（未登录）
• 403 Forbidden：已认证但无权限访问该资源
• 404 Not Found：资源不存在（不是“查无结果”，而是 URI 根本不指向有效资源）
• 422 Unprocessable Entity：语义验证失败（如邮箱格式错误、金额为负数）——比 400 更精准

保持响应结构统一，兼顾人机友好

前端解析、日志追踪、错误归因都依赖一致的响应体格式。不必强求 HATEOAS（除非有超媒体驱动需求），但基础结构需稳定。

• 推荐最小结构：{ "code": 0, "message": "success", "data": {...} }，其中 code 是业务码（如 1001 表示用户不存在），便于快速定位问题域
• 集合类接口必须支持分页：用 page 和 size 查询参数，后端强制限制 size 上限（如 ≤ 100），防拖库
• 过滤与排序通过查询参数实现：/products?category=phone&sort=price:desc&minPrice=1000
• 版本控制优先用路径前缀：/v1/users，比 Accept 头或自定义 header 更直观、易调试、兼容性更好