2、接口契约设计原则：RESTful设计规范、幂等性、安全性、版本控制策略

支付订单聚合接口的契约设计是系统稳定性的基石。本章围绕RESTful设计规范、幂等性、安全性和版本控制策略四大核心原则展开，确保接口在复杂支付场景下具备可维护性、一致性和抗风险能力。

2.1 RESTful设计规范

支付接口遵循RESTful风格，利用HTTP动词表达操作语义，资源路径清晰反映业务实体。核心设计要点如下：

RESTful接口的响应统一使用JSON格式，包含标准状态码和错误结构：

// 成功响应示例
{
  "code": 0,
  "message": "success",
  "data": {
    "order_id": "202503211234567890",
    "status": "pending",
    "amount": 1999,
    "currency": "CNY"
  }
}

// 错误响应示例
{
  "code": 40001,
  "message": "订单金额不能为负数",
  "request_id": "req-abc123"
}

2.2 幂等性设计

支付接口的幂等性确保同一请求多次执行产生相同结果，避免重复扣款、重复退款等严重资损问题。幂等性通过幂等键（Idempotency Key）机制实现。

Go语言中幂等性中间件的核心实现：

// 幂等性中间件示例
func IdempotencyMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        key := r.Header.Get("Idempotency-Key")
        if key == "" {
            // 非幂等请求直接放行
            next.ServeHTTP(w, r)
            return
        }

        // 查询幂等缓存
        result, err := cache.Get(r.Context(), key)
        if err == nil {
            // 已存在幂等记录，直接返回缓存结果
            w.Header().Set("X-Idempotent-Replayed", "true")
            w.Write(result)
            return
        }

        // 记录请求开始，防止并发重复
        lock := redis.NewLock(key, 30*time.Second)
        if !lock.Acquire() {
            http.Error(w, "并发请求冲突", http.StatusConflict)
            return
        }
        defer lock.Release()

        // 执行实际处理
        next.ServeHTTP(w, r)
    })
}

2.3 安全性设计

支付接口面临篡改、重放、越权等安全威胁。安全性设计从传输加密、签名校验、身份认证和防重放四个维度构建防护体系。

Go语言签名校验示例：

// 签名生成函数
func GenerateSignature(params map[string]string, secret string, timestamp int64, nonce string) string {
    // 1. 参数排序
    keys := make([]string, 0, len(params))
    for k := range params {
        keys = append(keys, k)
    }
    sort.Strings(keys)

    // 2. 拼接待签名字符串
    var buf strings.Builder
    for _, k := range keys {
        buf.WriteString(k)
        buf.WriteString("=")
        buf.WriteString(params[k])
        buf.WriteString("&")
    }
    buf.WriteString("timestamp=")
    buf.WriteString(strconv.FormatInt(timestamp, 10))
    buf.WriteString("&nonce=")
    buf.WriteString(nonce)

    // 3. HMAC-SHA256签名
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(buf.String()))
    return hex.EncodeToString(mac.Sum(nil))
}

2.4 版本控制策略

支付接口的版本控制解决向后兼容性问题，避免因接口升级导致已有客户端不可用。推荐使用URL路径版本和请求头版本两种策略。

版本控制的生命周期管理：

• v1（当前版本）：稳定运行，仅修复安全漏洞和严重Bug。
• v2（开发中）：新增功能，保持与v1的兼容性过渡期。
• 废弃版本：提前6个月发布废弃通知，在响应头中添加 Sunset: Sat, 31 Dec 2025 23:59:59 GMT。
• 强制升级：废弃版本到期后返回 410 Gone，并在响应体中提供迁移指南。

2.5 原则协同与Go实现

四大设计原则在支付订单聚合接口中协同工作，形成完整的契约体系：

• RESTful 定义资源结构和操作语义，是接口的骨架。
• 幂等性 保证重复请求的安全性，是资金安全的底线。
• 安全性 提供传输、签名、认证和防重放保护，是接口的护城河。
• 版本控制 管理接口演进，是长期维护的保障。

// 项目目录结构示例
internal/
├── handler/
│   ├── v1/
│   │   ├── order.go
│   │   ├── payment.go
│   │   └── refund.go
│   └── v2/
│       ├── order.go
│       └── payment.go
├── middleware/
│   ├── signature.go
│   ├── idempotency.go
│   └── version.go
├── service/
│   └── order.go
└── model/
    └── order.go