2、RESTful API 设计原则：资源命名规范、HTTP 方法使用、状态码选择、版本控制策略

RESTful API 是构建日志检索准入门禁自助服务的核心通信契约。遵循统一的设计原则，能显著提升 API 的可读性、可维护性与安全性。本节围绕资源命名、HTTP 方法、状态码与版本控制四大支柱展开。

2.1 资源命名规范

REST 的核心是“资源”（Resource），每个资源通过 URI 唯一标识。命名应使用名词复数，避免动词，并采用小写字母与连字符（-）分隔单词。

2.2 HTTP 方法使用

HTTP 方法对应资源的 CRUD 操作。在日志检索与门禁场景中，方法选择直接影响安全性与幂等性。

2.3 状态码选择

状态码是 API 响应语义的第一道关口。选择恰当的状态码能帮助调用方快速定位问题，减少日志排查成本。

• 2xx 成功：
  • 200 OK — GET、PUT、PATCH 成功返回资源。
  • 201 Created — POST 创建资源成功，响应头应包含 Location 指向新资源 URI。
  • 204 No Content — DELETE 成功，或操作成功但无需返回 body。
• 4xx 客户端错误：
  • 400 Bad Request — 请求参数格式错误或校验失败。
  • 401 Unauthorized — 未提供或提供了无效的鉴权凭证。
  • 403 Forbidden — 已认证但无权限执行操作（如普通员工尝试删除管理员日志）。
  • 404 Not Found — 资源不存在。
  • 409 Conflict — 资源当前状态冲突（如重复提交已审批的申请）。
  • 429 Too Many Requests — 触发限流策略。
• 5xx 服务端错误：
  • 500 Internal Server Error — 未预期的服务端异常。
  • 503 Service Unavailable — 服务暂时不可用（如数据库连接池耗尽）。

2.4 版本控制策略

API 版本控制是保障向后兼容、支持渐进式演进的关键。推荐使用 URI 路径版本控制，将版本号显式嵌入路径中。

# 推荐：路径版本控制
GET /api/v1/access-logs
GET /api/v2/access-logs

# 不推荐：请求头版本控制（难以缓存和调试）
GET /api/access-logs
Headers: Accept: application/vnd.company.v1+json

版本号从 v1 开始，每次引入不兼容变更时递增主版本号。小版本（如 v1.1）应保持完全向后兼容，仅通过新增字段或可选参数扩展。

2.5 设计原则总结

将上述原则应用于日志检索准入门禁自助服务时，可形成以下 API 设计清单：

1. 资源路径：/api/v1/access-logs、/api/v1/employees/{empId}/badges、/api/v1/approvals。
2. 方法映射：查询用 GET，创建申请用 POST，更新权限用 PUT，撤销用 DELETE。
3. 状态码：成功创建返回 201，参数错误返回 400，无权限返回 403，资源不存在返回 404。
4. 版本控制：当前使用 v1，未来不兼容变更时升级到 v2，v1 保留至少 6 个月过渡期。