用 SDD 方法开发一个 AI Gateway

AI Gateway 不是在写代码，是在写规范。本文不讲代码，只讲方法——如何用规范驱动开发（SDD）把一个 AI 网关从想法变成可运行的系统。

一、AI Gateway 的本质

企业用大模型，四个问题绕不开：谁在调模型？敏感数据有没有出内网？花了多少钱？出事怎么查？AI Gateway 做的就是在客户端和上游模型之间插一层治理层，把这四个问题在请求链路中前置解决。

功能拆开是五块：模型目录（管"有哪些模型可用"）、路由引擎（管"该发给谁"）、风险控制（管"能不能发"）、审计追踪（管"发了什么"）、成本核算（管"花了多少"）。功能边界清晰，天然适合 SDD。

二、SDD 的四步工作法

SDD 一句话概括：先写规范，再写代码。拆成四步走。

第一步：写架构规范。一页纸说清楚五件事：入口是什么（OpenAI 兼容接口）、请求经过哪几层（解析→扫描→路由→调用→记录）、对接哪些上游、每层之间用什么数据交互、异常路径怎么处理（模型不存在、上游超时、风险阻断）。这一步不写代码，但写完团队每个人都知道系统长什么样。

第二步：拆模块规范。把架构中的每一层抽成独立模块，每个模块按统一格式描述：（1）这个模块负责什么；（2）接收什么输入；（3）做什么处理；（4）产出什么输出；（5）异常情况怎么处理。以路由引擎为例：输入是客户端请求体和用户上下文，处理逻辑是"先看请求的 model 字段是 auto 还是具体名称来初选模型，再根据风险扫描结果决定是否切到安全模型"，输出是最终选定的模型配置和调用结果。

第三步：定数据契约。模块之间的交互靠结构化的数据对象。模型配置对象描述一个模型的全貌（名称、供应商、地址、是否安全、单价），风险分析结果对象描述一次扫描的结论（命中哪些规则、最高严重级别、最终动作是放行/转安全模型/阻断），审计事件对象描述一次记录（谁、什么时候、做了什么操作、结果如何、关联的 trace_id）。这些契约定义好了，后端写逻辑、前端画界面、测试写用例可以并行开工。

第四步：按规范翻译成代码。规范写到位了，这一步就是翻译——每个模块对应一个文件，输入输出完全照搬规范中的定义，不需要边写边想。翻译顺序建议从底层到上层：先写数据持久化（模型仓库、审计存储、成本存储），再写业务服务（风险扫描、成本计算），最后写路由引擎把各服务串起来，最外层是 Flask 应用注册路由和中间件。每写完一个模块立刻用规范中定义的验收条件做测试。

三、验收：用规范反向检验

SDD 好不好，看验收是否省心。六个验收条件直接来自规范：（1）model 传 auto 是否自动选到第一个非安全模型；（2）消息含手机号是否自动切到安全模型；（3）消息含 API Key 模式是否直接返回 403；（4）流式请求是否能逐块透传不卡顿；（5）用 trace_id 查审计日志能否还原完整链路；（6）成本统计是否能按人、按模型、按时间维度拆开。六条通过，开发完成。不需要额外写测试计划——规范就是测试计划。

四、为什么 SDD 适合 AI Gateway

AI Gateway 是一种"边界清晰的管道系统"——每个模块做什么是确定的，模块之间的数据流向是确定的，异常分支是可枚举的。这类系统用 SDD 开发有三个直接收益：一是规范写完就可以让前端和测试并行开工，不堵在后端代码上；二是设计问题（比如风险扫描到底放路由之前还是之后）在规范阶段就暴露，不用写到一半推翻重来；三是新人接手先看规范，半小时理解全貌，不用对着代码猜意图。

五、下一步：从 Gateway 到管理平面

做完 AI Gateway，企业 AI 治理只完成了三分之一。剩下两个能力——Agent 实例的批量管理和生命周期控制、Skill 和工具链的安全审核与复用——同样适合用 SDD 推进。方法不变：先写架构规范定边界，再拆模块规范定行为，定数据契约，最后翻译成代码。三块拼在一起，就是一个完整的企业 AI 治理控制平面。