如何通过 TypeScript 映射类型自动构建支持双向校验的 API 契约模型？

本文共计688个文字，预计阅读时间需要3分钟。

映射类型本身不直接实现双向绑定，但可为双向绑定提供强类型基础——关键在于将API路径+请求/响应结构精确建模为可导引、可约束的类型契约，再结合运行时校验逻辑，实现闭环。

先定义清晰的 API 契约映射表

不要用 Record<string any></string> 或泛型占位，而是显式声明每个 endpoint 对应的请求参数（Req）和响应数据（

Res</code）：</p> <ul> <li><code>type ApiPath = '/users' | '/users/:id' | '/posts' —— 所有合法路径必须是字面量联合类型

interface ApiSchema { '/users': { req: { role?: string }; res: User[] }; '/users/:id': { req: { id: string }; res: User }; }

路径中 :id 不参与字符串匹配，而是作为独立参数字段抽象进 req，避免类型失配

用映射类型生成强类型客户端接口

基于契约表，批量构造带参数校验和返回类型推导的方法签名：

• type ApiClient = { [K in keyof ApiSchema]: (params: ApiSchema[K]['req']) => Promise<apischema> };</apischema>
• 调用 client.getUsers({ role: 'admin' }) 时，TS 能检查 role 是否合法、是否必填，且返回值自动为 User[]
• 若传入不存在的字段（如 { roles: 'admin' }），编译期直接报错

在运行时注入双向校验逻辑

类型系统只管“描述”，校验要靠代码执行。可在请求发起前、响应解析后插入校验钩子：

• 请求侧：对 params 调用 zod.object(...).safeParse() 或自定义守卫函数，拦截非法输入
• 响应侧：用类型守卫（isUserArray(data): data is User[]）验证返回体结构，防止后端字段变更导致前端崩溃
• 把校验结果与 TypeScript 类型联动——例如校验失败时抛出带 expected: User[] 字段的错误，便于调试定位

让模型支持自动同步更新

当 OpenAPI Schema 变更时，手动改类型易出错。可借助工具链自动化：

• 用 openapi-typescript 将 YAML 自动生成 ApiSchema 初始结构
• 配合 ts-morph 或自定义脚本，把生成类型注入到映射类型定义中，保持契约一致
• CI 阶段加入类型差异比对：若新生成的 ApiSchema 与当前客户端方法签名不兼容，则阻断发布