最近在群里看到有哥们为了给十几个 API 做版本控制，居然去折腾 Kong 网关 and K8s 路由，还要给每个版本拉个微服务分支。这一套折腾下来，版本没管好，运维先累瘫了。说实话，小团队天天去套大厂那一套“多版本网关动态路由”的方案，纯粹是给自己加戏，心智负担直接拉满。
大厂之所以在网关层做 API 分流，是因为他们后台服务跨着几十个团队，语言各异、数据库不通，只能用物理隔离加网关路由的方式续命。我们这种前后端一共才几个人的小团队，明明一套 Nest.js/Express 就能搞定的事情，非要搞黑盒网关，一旦路由配置出点偏差，排查起来简直是灾难。
对于我们来说，最痛的其实不是路由问题，而是前端老版本客户端没升级，后端改了数据库字段，导致接口字段直接崩溃。所以，API 版本管理本质上是 DTO（数据传输对象）的转换和向前兼容问题。
我们干脆在应用层直接用 TypeScript 和 Zod Schema 来做版本拦截与多版本 DTO 自动转换。核心逻辑很简单：路由层依然用同一个 Endpoint，或者通过简单的版本路由前缀（/v1/user, /v2/user）分发到同一个 Controller，然后根据请求带过来的版本号（可以放 Header 或 Query），直接在 Zod 的 transform 里做结构转换。
下面是我们目前正在跑的一套真实方案。不需要搞多套实体，用 Zod 直接搞定：
import { z } from 'zod';
// 原始 V1 版本的 DTO 定义
const UserV1Schema = z.object({
id: z.string(),
user_name: z.string(), // 老版本用的是下划线
avatar_url: z.string(),
status: z.number(), // 老版本用 0/1 代表状态
});
// 新 V2 版本的 DTO 定义
const UserV2Schema = z.object({
id: z.string(),
username: z.string(), // 驼峰命名
avatar: z.string(), // 字段精简
isActive: z.boolean(), // 状态改成布尔值
email: z.string().email(), // 新增字段
});
type UserV1 = z.infer<typeof UserV1Schema>;
type UserV2 = z.infer<typeof UserV2Schema>;
// 版本适配器：将 V2 的数据向下兼容转换成 V1
export function adaptUserV2ToV1(v2Data: UserV2): UserV1 {
return {
id: v2Data.id,
user_name: v2Data.username,
avatar_url: v2Data.avatar,
status: v2Data.isActive ? 1 : 0,
};
}
// 统一对外输出的 Schema，在 Schema 层面做版本分发和兼容
export const UserResponseSchema = z.preprocess((val: any) => {
// 假设 val 是我们从数据库查出来的最新 V2 格式数据
return val;
}, z.custom<UserV2>()).transform((data, ctx) => {
// 从上下文中获取客户端请求的版本号
const version = (ctx as any).meta?.version || 'v2';
if (version === 'v1') {
// 自动兼容旧版本客户端，做字段平滑转换
try {
const v2Parsed = UserV2Schema.parse(data);
return adaptUserV2ToV1(v2Parsed);
} catch (err) {
// 降级处理或者抛出不兼容异常
throw new Error('Failed to adapt data to v1');
}
}
// 默认返回 V2 数据
return UserV2Schema.parse(data);
});
// 模拟 Express 控制器中的使用场景
export async function getUserController(req: any, res: any) {
const clientVersion = req.headers['x-api-version'] || 'v2';
const mockDbUser = {
id: "usr_9527",
username: "tianma",
avatar: "https://avatar.io/tianma.png",
isActive: true,
email: "tianma@example.com"
};
try {
// 注入版本信息到解析上下文
const result = UserResponseSchema.safeParse(mockDbUser, {
meta: { version: clientVersion }
} as any);
if (!result.success) {
return res.status(500).json({ error: "Data serialization error" });
}
return res.json(result.data);
} catch (error) {
return res.status(400).json({ error: "Version mismatch" });
}
}这样搞的好处简直太多了。首先，代码极其直观，哪个字段在哪个版本被干掉了，哪个字段换了名字，在 adapt 函数里一目了然。其次，类型安全直接拉满，前端同事用 zod-to-ts 生成出来的类型跟后端也是完全匹配的，根本不需要猜。最爽的是，部署时还是同一个容器，根本不存在网关配置漂移导致的诡异 Bug。
对于日活没有上百万、开发团队就几个人的项目，千万别去碰微服务和网关路由那套大坑。老老实实在单体应用里把 DTO 转换写好，比什么都强。
你们目前是怎么做 API 版本控制的？也是用 DTO 适配器，还是直接任性地让前端改代码适配？