3. API 设计原则：RESTful vs gRPC、资源导向设计、版本控制策略

在平台工程中，API 是运营任务编排的“神经系统”。选择错误的通信范式、资源建模方式或版本策略，将直接导致编排链路断裂、客户端兼容性灾难以及运维复杂度飙升。本章从三个核心维度展开：协议选型（RESTful vs gRPC）、资源导向设计（Resource-Oriented Design）、版本控制策略（URL / Header），为团队提供可落地的标准化决策框架。

3.1 协议选型：RESTful 与 gRPC 的权衡

编排 API 的底层传输协议决定了性能边界、开发体验与生态兼容性。下表从平台工程最关心的维度进行对比：

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

传统 RPC 风格 API 容易产生大量自定义动作端点（如 /task/start、/task/stop、/task/retry），导致接口膨胀且难以缓存。资源导向设计（Resource-Oriented Design）将编排能力抽象为资源 + 标准方法，显著提升接口的一致性与可发现性。

3.2.1 核心映射规则

• 资源 = 名词：/tasks、/pipelines、/executions、/triggers
• 方法 = 标准 HTTP 动词：GET（查询）、POST（创建）、PUT（全量替换）、PATCH（部分更新）、DELETE（删除）
• 动作 = 子资源或自定义方法：POST /tasks/{id}/cancel、POST /executions/{id}/retry

3.2.2 编排资源模型设计清单

3.3 版本控制策略：URL 路径 vs 请求头

编排 API 的版本管理直接关系到存量任务、回调钩子与客户端 SDK 的兼容性。业界主流有两种策略：URL 路径版本与请求头版本。平台工程团队需要根据消费者类型与变更频率做出选择。

3.3.1 两种策略对比

3.3.2 平台工程版本控制规范

1. 主版本号（Major）：非向后兼容的变更（如删除字段、修改请求结构）必须提升主版本。URL 路径中体现为 v1 → v2。
2. 次版本号（Minor）：向后兼容的新增字段或端点，通过请求头 X-API-Version: 1.2 协商，不改变 URL。
3. 废弃策略（Deprecation）：旧版本至少保留 6 个月，响应头中加入 Sunset: Sat, 01 Nov 2025 00:00:00 GMT 告知客户端迁移截止时间。

3.3.3 版本协商代码示例

以下展示一个基于请求头版本协商的 Go 中间件片段，用于内部编排 API 网关：

// versionMiddleware 根据 Accept Header 选择处理器版本
func versionMiddleware(next map[string]http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        accept := r.Header.Get("Accept")
        var version string

        switch {
        case strings.Contains(accept, "vnd.myorg.v2"):
            version = "v2"
        case strings.Contains(accept, "vnd.myorg.v1"):
            version = "v1"
        default:
            version = "v1" // 默认路由到最新稳定版
        }

        if handler, ok := next[version]; ok {
            handler.ServeHTTP(w, r)
            return
        }
        http.Error(w, "unsupported API version", http.StatusNotAcceptable)
    })
}