国密标准接口治理教程 - 第2节

第2章 接口治理基础

接口治理这事儿，说白了就是把一群人的接口行为纳入一个可管可控的框架里。我在刚做技术负责人那会儿，团队接口文档全靠口头传承，上线前一问接口改了啥，大家一脸懵。嗯，后来我才意识到，治理不是管人，是管好接口的生命周期。

2.1 API治理概念

API治理不是一两个规则就能搞定的。我理解它是一套持续演进的机制：定义、发布、变更、退役，每一步都得有明确的责任人和评审流程。

2.2 RESTful设计原则

RESTful不是严格的协议，而是一套风格约束。我个人习惯把它当成“接口江湖的武林规矩”，大家都遵守，协作成本就低。核心就是六条约束，真正工作中最常用的是前三：

• 资源导向：把业务对象映射成URL，操作通过HTTP动词表达
• 无状态：每个请求都携带足够信息，服务器不保存客户端上下文
• 统一接口：GET/ POST/ PUT/ DELETE 语义明确

举个我参与过的国密标准项目中的例子。我们要设计密钥管理接口，如果按RPC风格可能写成/api/getKey /api/createKey。改成RESTful之后：

GET    /keys                // 获取密钥列表
POST   /keys                // 创建新密钥
GET    /keys/{id}           // 获取某个密钥详情
PUT    /keys/{id}           // 更新密钥信息
DELETE /keys/{id}           // 删除密钥

你看，URL只描述资源“keys”，动词统一。前端同事一看就知道用什么方法。不过有一点要注意：资源命名尽量是复数名词。我之前图省事用了/api/key/123，后来发现统计接口数量时，单复数混在一起，脚本处理很痛苦。

2.3 接口版本管理

版本管理算是接口治理里最绕不开的话题。你想想看，接口上线后永远会有老客户端在用，你不可能停掉旧版本。怎么做到“改而不破”？

常见的版本管理策略，我整理了一张对比表：

我以前在国密项目中踩过一个坑：使用URL路径版本，但忘记在新版本中保持旧版本字段的兼容性。客户端传了v2的请求，返回结果里少了某个旧字段，导致下游解析报错。从那以后我强制要求：每个新版本必须跑一遍“旧客户端兼容测试”——用老版本的请求模板来测，失败就拒绝发布。

# 我团队里加的CI检查脚本片段
def check_backward_compat(old_schema, new_schema):
    # 检查新schema是否删除了旧schema中required字段
    for field in old_schema.get('required', []):
        if field not in new_schema.get('properties', {}):
            raise Exception(f"破坏兼容: required字段 {field} 被删除")
    # 检查响应结构是否有非向后兼容的变化
    # ... 更多逻辑略

本章知识体系

从图上你也能看出来，API治理不是单点工艺，它需要规则、原则、版本管理三足支撑。我个人觉得，新团队先从“资源命名规范”和“冲突版本通知”起步，跑通后再加RESTful约束，这样团队不会觉得自己在被管着，而是慢慢习惯这套协同方式。