3. 接口调用规范设计原则：RESTful原则、幂等性、无状态性、资源导向设计、版本控制策略

在平台工程与混沌工程基线核验场景中，接口调用规范是保障系统可观测性、可恢复性与可演进性的核心契约。本章围绕五大设计原则展开，确保核验接口在故障注入、流量调度与基线比对过程中具备一致性与鲁棒性。

3.1 RESTful 原则：以资源为中心的交互范式

RESTful 风格将平台能力抽象为资源集合，通过标准 HTTP 方法表达操作语义。在混沌工程基线核验中，核验目标、故障场景、基线数据均被视为资源。

3.2 幂等性：保障故障注入与重试安全

幂等性确保同一请求无论执行一次还是多次，资源最终状态一致。在混沌工程中，网络抖动、超时重试频繁发生，非幂等接口可能导致基线数据重复写入或故障状态错乱。

// 幂等性校验示例：客户端生成唯一键
POST /api/v1/verifications
Content-Type: application/json
Idempotency-Key: 7a1b2c3d-4e5f-6789-abcd-ef0123456789

{
  "baselineId": "bl-20250301",
  "scenario": "network-latency",
  "targetService": "payment-svc"
}

3.3 无状态性：水平扩展与故障隔离的基础

无状态性要求每个请求包含所有必要信息，服务端不依赖会话上下文。在混沌工程基线核验中，无状态设计使得核验引擎可以快速扩缩容，单点故障不影响全局核验进度。

3.4 资源导向设计：从操作到资源的范式转换

资源导向设计将核验能力抽象为可嵌套的资源树，而非 RPC 式的动作调用。每个资源支持标准的 CRUD 操作，便于混沌工程工具链进行自动化编排。

// 资源导向 vs 动作导向 对比
// ❌ 动作导向（不推荐）
POST /api/startVerification
POST /api/getBaselineData
POST /api/compareResult

// ✅ 资源导向（推荐）
POST   /api/v1/verifications              // 创建核验任务
GET    /api/v1/verifications/{id}         // 查询核验状态
GET    /api/v1/baselines/{id}             // 获取基线数据
POST   /api/v1/verifications/{id}/results // 提交核验结果

3.5 版本控制策略：兼容演进与基线回溯

版本控制确保核验接口在平台演进过程中保持向后兼容，同时支持多版本基线数据的同时比对。推荐使用 URL 路径版本 与 请求头版本 相结合的策略。

// 版本控制示例：请求头版本协商
GET /api/baselines/bl-20250301
Accept: application/vnd.chaos.baseline.v2+json
Authorization: Bearer <>

// 响应
HTTP/1.1 200 OK
Content-Type: application/vnd.chaos.baseline.v2+json
Sunset: Sat, 01 Nov 2025 00:00:00 GMT

{
  "apiVersion": "2",
  "baselineId": "bl-20250301",
  "metrics": { ... },
  "metadata": { ... }
}