2. 接口调用规范设计原则

在混沌工程基线核验场景中，接口调用规范是保障实验注入、状态采集、结果判定一致性的核心契约。本章围绕 RESTful 设计原则、幂等性设计、版本控制策略 和 错误码规范 四个维度展开，为后续模板驱动核验提供可执行的接口契约基线。

2.1 RESTful 设计原则

混沌工程控制面与靶场之间的所有交互接口必须遵循 RESTful 风格，以资源为中心、以 HTTP 动词为操作语义。基线核验要求接口路径、请求方法、响应状态码三者严格对齐，避免歧义。

2.2 幂等性设计

混沌实验注入、基线采集、核验触发等操作在网络抖动或控制面重试时，必须保证多次调用与单次调用的副作用一致。幂等性设计直接决定基线核验结果的可靠性。

• GET / HEAD / OPTIONS：天然幂等，响应可缓存。
• PUT / DELETE：语义幂等，服务端需按资源当前状态处理，重复执行不产生额外副作用。
• POST：非幂等，必须引入 幂等键（Idempotency-Key） 机制。

// 幂等键处理伪代码（服务端中间件）
func IdempotencyMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if r.Method == http.MethodPost {
            key := r.Header.Get("Idempotency-Key")
            if key == "" {
                http.Error(w, "Missing Idempotency-Key", http.StatusBadRequest)
                return
            }
            if cached, ok := cache.Get(key); ok {
                // 直接返回缓存结果，不执行实际逻辑
                w.WriteHeader(cached.StatusCode)
                w.Write(cached.Body)
                return
            }
            // 记录响应到缓存后再返回
            recorder := &responseRecorder{ResponseWriter: w}
            next.ServeHTTP(recorder, r)
            cache.Set(key, recorder.Result(), 24*time.Hour)
        } else {
            next.ServeHTTP(w, r)
        }
    })
}

2.3 版本控制策略

混沌工程基线核验接口必须支持平滑演进，避免因模板或实验定义变更导致核验管道断裂。推荐采用 URL 路径版本 与 请求头版本 双轨策略。

2.4 错误码规范

统一的错误码体系是混沌工程基线核验自动化判定的基础。所有接口错误响应必须遵循固定 JSON 结构，并按照 功能模块 + 错误类型 + 具体原因 三级编码。

// 标准错误响应结构
{
  "error": {
    "code": "EXP-4001",
    "message": "实验模板参数校验失败",
    "details": {
      "field": "duration_seconds",
      "reason": "值 0 不在允许范围 [10, 3600] 内",
      "constraint": "min=10, max=3600"
    },
    "trace_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}