4. API 设计原则：RESTful 风格、资源命名规范、版本控制策略、幂等性与安全性要求

平台工程变更风险评估任务编排的 API 设计，必须遵循一套严谨且可落地的设计原则。本章围绕 RESTful 风格、资源命名规范、版本控制策略、幂等性与安全性五大核心维度展开，确保 API 接口具备良好的可读性、可维护性、扩展性与生产级可靠性。

4.1 RESTful 风格与资源建模

变更风险评估任务编排本质上是资源操作的集合。RESTful 风格要求将业务实体抽象为资源，并通过 HTTP 方法表达操作语义。核心资源包括：AssessmentTask（评估任务）、RiskRule（风险规则）、ExecutionPlan（执行计划）、AuditLog（审计日志）。

关键约束：禁止在 URL 中使用动词（如 /createTask），应通过 HTTP 方法表达操作。例如：POST /tasks 表示创建，DELETE /tasks/{id} 表示删除。
RESTful 资源与 HTTP 方法映射 资源 /tasks /tasks/{id} /tasks/{id}/execute /risk-rules HTTP 方法 POST GET / PUT / DELETE POST (动作) GET 语义说明 创建新的评估任务 查询 / 全量替换 / 删除指定任务 触发任务执行（非资源 CRUD） 查询风险规则列表

4.2 资源命名规范

资源命名采用全小写 + 连字符（kebab-case）风格，路径层级清晰表达从属关系。集合资源使用复数名词，单例资源使用单数。

类别 示例路径 说明
集合资源 /api/v1/tasks 评估任务列表
单例资源 /api/v1/tasks/{taskId} 指定评估任务详情
子资源 /api/v1/tasks/{taskId}/steps 任务下的步骤集合
动作资源 /api/v1/tasks/{taskId}/cancel 取消任务（POST）
查询参数 /api/v1/tasks?status=running&page=1 按状态分页查询
命名避坑指南：
  • 避免使用下划线（task_id）或驼峰（taskId）作为路径段。
  • 避免在路径中暴露数据库主键，优先使用业务 UUID。
  • 避免过深的嵌套（超过 3 层），考虑使用查询参数扁平化。

4.3 版本控制策略

API 版本控制采用 URL 路径前缀方式，版本号以 v 开头、整数递增。该策略对客户端最直观，便于缓存和路由。

# 版本控制示例
GET /api/v1/tasks          # 当前稳定版
GET /api/v2/tasks          # 下一迭代版（可能包含破坏性变更）
GET /api/v1/tasks?fields=id,name,status  # 字段筛选（向后兼容）

版本生命周期管理遵循以下规则：

  • v1：当前稳定版，至少维护 6 个月。
  • v2：新功能迭代版，与 v1 并行运行。
  • 废弃策略：在 v2 发布时标记 v1 为 deprecated，响应头携带 Sunset: Sat, 01 Nov 2025 00:00:00 GMT。
注意：避免使用 v1.2 或 v1-beta 等语义版本号作为路径前缀。API 版本控制只反映兼容性边界，不反映内部迭代次数。

4.4 幂等性要求

变更风险评估任务编排涉及多次重试与补偿操作，幂等性是保障数据一致性的核心机制。以下表格列出关键操作的幂等性设计策略：

HTTP 方法 幂等性 实现方式 示例场景
GET 天然幂等 无副作用查询 查询任务状态
PUT 天然幂等 全量替换资源 更新任务配置
DELETE 天然幂等 删除后再次删除返回 404 删除已取消的任务
POST 非幂等（需改造） 客户端传入 Idempotency-Key 请求头 创建评估任务、触发执行
PATCH 非幂等（需改造） 条件更新 + 版本号乐观锁 部分更新任务字段

幂等性关键实现细节：

  • 服务端根据 Idempotency-Key 缓存请求结果，有效期至少 24 小时。
  • 重复请求返回首次操作的响应结果（状态码、响应体一致），不重复执行。
  • 幂等键应包含客户端标识 + 时间戳 + 随机数，保证全局唯一。
// 幂等请求示例
POST /api/v1/tasks
Content-Type: application/json
Idempotency-Key: client-abc-2025-04-01-7a8b9c

{
  "name": "变更风险评估-部署批次A",
  "riskRules": ["rule-001", "rule-002"]
}

4.5 安全性要求

API 安全体系覆盖认证、授权、传输加密、审计与防篡改五个层面。变更风险评估任务编排涉及生产环境变更，安全要求高于普通业务 API。

API 安全五层防护模型 L1 传输加密：TLS 1.2+ / mTLS 双向认证 L2 身份认证：OAuth 2.0 + JWT / + HMAC 签名 L3 细粒度授权：RBAC / ABAC，按任务、环境、操作类型鉴权 L4 请求完整性：请求体 HMAC-SHA256 签名 + 时间戳防重放 L5 审计与监控：全量请求日志 + 敏感操作告警 + 变更溯源

安全实现要点：

  • 认证：服务间调用使用 mTLS + 短期 JWT；外部客户端使用 OAuth 2.0 Client Credentials 流程。
  • 授权：每个 API 端点绑定最小权限 scope，例如 task:read、task:write、task:execute。
  • 防重放：请求头携带 X-Timestamp（Unix 毫秒）和 X-Nonce，服务端窗口允许 ±5 分钟。
  • 审计：所有变更操作记录 who、what、when、result，写入不可篡改的审计日志存储。
安全设计红线：
  • 禁止在 URL 参数中传递明文 或密钥。
  • 禁止返回堆栈跟踪或数据库错误详情到客户端。
  • 所有敏感操作（执行、取消、删除）必须二次确认或携带 X-Confirm: true 头。

4.6 设计原则总结矩阵

原则 核心要求 违反后果 优先级
RESTful 风格 资源路径 + HTTP 方法表达语义 接口混乱，客户端难以理解 P0
资源命名规范 kebab-case、复数名词、扁平嵌套 路径歧义，解析困难 P1
版本控制 URL 路径前缀 v1/v2，废弃有通知 破坏性变更导致客户端故障 P0
幂等性 Idempotency-Key + 结果缓存 重复执行导致数据不一致 P0
安全性 TLS + OAuth + 签名 + 审计 数据泄露、未授权操作 P0
← 上一章 📖 返回目录 下一章 →