Fastify TypeScript billing-api 中 Zod schema 校验占 P99 80ms 中 25ms 的 5 天深度优化:precompile + valibot 混合 + 选择性校验 + safeParse 全过程

2026 年 3 月某个周二下午,我们的 Fastify + TypeScript 后端服务 billing-api 在做性能 profile 时,我看到一个让我盯了 10 秒钟才确认的数字:单个请求 P99 80ms 里,Zod schema 校验占 25ms——31%。我们一直把 Zod 当成"轻量、零开销、提供类型推导和运行时校验"的银弹用,从来没想过它会成为性能瓶颈。一个 P99 60ms 的接口里如果一半时间花在"确认数据格式正确",那花得就有点离谱。

接下来 5 天我们带着团队对 Zod 的内部实现做了一次深度剖析,定位出三个叠加的性能问题:每次请求时 schema 在某些代码路径下被重复实例化(导致内部缓存失效)、深层嵌套 schema 在校验时遍历每个分支多次(联合类型尤其严重)、refine / transform 的异步路径无意中触发了 Promise allocation。最后我们做了选择性校验 + schema precompile + 边缘场景换 valibot 的组合优化,把 Zod 部分的耗时从 25ms 压到 0.3ms,P99 整体从 80ms 降到 55ms。这篇是完整复盘,涵盖 Zod 内部架构、3 种性能反模式、4 种修复方案的取舍、与同类库(valibot / arktype)的对比,以及落地的《TypeScript 运行时校验纪律》。

服务背景:这个高并发的 Fastify 计费 API

Zod 在 TypeScript 社区有"事实标准"地位,大多数团队拿来就用,没人 profile 过它的运行时开销。这次的发现纯属偶然——我们做容量规划时跑性能 profile,在火焰图上看到 Zod.ZodObject.parse 占了一大块,才意识到这是个值得优化的方向。

事故时间线:从性能 profile 到优化落地的 5 天

三层叠加的因果链:为什么 31% 这个数字会出现

这张图最关键的信息是三个因素互相放大:重复实例化让基础开销翻倍 / 普通 union 让 N 分支被串行试遍 / refine 触发 ZodEffect 让 microtask 调度叠加。任何一个单独存在不会致命,叠加就能把"轻量校验库"拖成"P99 杀手"。这也是为什么大家平时跑小项目 benchmark 看不出 Zod 慢——小 schema + 简单字段下三个因素都不会被放大。我们后来内部叫这种问题"复合性能反模式",任何一项性能事故复盘都强制画一张这种因果图,确保不会"修了表面忽略主因"。

第一反应:"Zod 应该挺快的吧"

Zod 在社区里的形象一直是"轻量、零依赖、性能不错",大家很少 profile 它。但 Zod 的设计哲学是"灵活性 + 类型推导优先,性能次之"——这个权衡在小项目无所谓,在 QPS 4000 + 复杂 schema 的场景下放大成显著开销。

第一个证据来自火焰图,具体看是:

# 简化的火焰图(每个请求的 CPU 分布)
- fastify.route (60%)
  - fastify.preHandler (5%)
  - fastify.handler (50%)
    - Zod.parse request body (12%)        ← 这里!
    - business logic (15%)
    - db query (15%)
    - Zod.parse response (8%)             ← 还有这里
  - fastify.serializer (5%)
- gc, etc (40%)

req body 校验 12% + response 校验 8% = 20%(实际更高,有些是在 ZodEffect refine 里)。这数字按我们 P99 80ms 算,Zod 占用 ~ 16ms,profile 给的更精细数字是 25ms(包含若干 microtask 调度)。无论是 16 还是 25,都比"我们以为的 1-2ms"大一个数量级。

真凶 1:每次请求 schema 都被"重新解释"

Zod 的核心设计:schema 是纯描述对象,每次 parse 时根据 schema 的描述动态选择校验逻辑。它没有"编译"步骤——schema 不会被预先转换成最优化的校验函数。这是个简单优雅的设计,但每次校验都付出"解释"的开销。

具体说,一个 ZodObject.parse 大致流程:

1. 检查输入是否是 object(typeof / null 检查)
2. 遍历 schema 的所有字段(this._def.shape)
3. 对每个字段调用对应 schema 的 _parse 方法
4. 递归处理嵌套 schema
5. 处理 unknownKeys / passthrough / strict 配置
6. 组装结果对象,返回 SuccessResult 或 ErrorResult

对一个 8 层嵌套、40 字段的 schema,每次 parse 要走几百次这样的递归 + 函数调用。V8 虽然能 JIT 这些热路径,但 Zod 内部大量使用动态分支(根据 schema type 选择 logic)和闭包,JIT 优化效果有限。

真凶 2:discriminated union 的"试每个分支"

我们的 schema 大量使用 discriminated union,比如:

const EventSchema = z.discriminatedUnion('type', [
    z.object({ type: z.literal('order'),    orderId: z.string(), amount: z.number() }),
    z.object({ type: z.literal('refund'),   orderId: z.string(), reason: z.string() }),
    z.object({ type: z.literal('credit'),   creditId: z.string(), amount: z.number() }),
    // ... 12 个 variant
]);

"discriminated union" 听起来比"普通 union"快——因为 Zod 用 type 字段直接路由到正确的 schema,不用"试每个分支"。理论上是 O(1) 选择。但 Zod 3.x 的实现里,discriminator 失败时会 fall back 到普通 union 行为——这意味着如果 discriminator 字段缺失或值不在已知列表,Zod 会真的去试每一个分支。在攻击者构造的恶意请求 / 客户端代码 bug 场景下,这是个明显的放大效应。

更微妙的是,如果 schema 内嵌套使用普通 z.union(不是 discriminated),Zod 默认行为是对每个分支跑完 parse,如果有多个成功取第一个。这意味着 N 个分支的 union 在最坏情况下校验时间 × N。我们有几个旧代码用了普通 union,profile 显示这些路径占了相当一部分耗时。

修法:严格用 discriminatedUnion + literal

// ❌ 慢
const Schema = z.union([
    z.object({ type: z.string(), ... }),
    z.object({ type: z.string(), ... }),
]);

// ✅ 快
const Schema = z.discriminatedUnion('type', [
    z.object({ type: z.literal('a'), ... }),
    z.object({ type: z.literal('b'), ... }),
]);

这一个改动,union 校验从 O(N) 变 O(1),对我们的 schema 整体耗时 -8%。

真凶 3:refine / transform 触发的异步路径

Zod 支持 refine(自定义校验)和 transform(数据转换),非常实用:

const PhoneSchema = z.string()
    .refine(s => /^\+?\d{8,15}$/.test(s), { message: 'invalid phone' })
    .transform(s => s.replace(/^\+/, ''));

看起来简单——但refine 在 Zod 3 的实现里,会让整个 schema 变成 ZodEffect 类型,parse 走的是 async-aware 路径。即使 refine 函数本身是同步的,Zod 也会通过 Promise.resolve() 包一层,让外层兼容 async refine。每个 refine 增加一次 microtask 调度。

我们的 schema 里有 ~ 30 个 refine,每个请求大概会触发 50+ 个 microtask。虽然每个只有几 microsecond,加起来在 V8 调度上占用不可忽略的时间。更糟的是,refine 包装会破坏 V8 的 inline 优化——本来可以 inline 的简单校验函数变成多层函数调用。

修法:用 z.string().regex(...) 替代 refine

// ❌ 触发 ZodEffect 路径
const PhoneSchema = z.string().refine(s => /^\+?\d{8,15}$/.test(s));

// ✅ ZodString 内置 regex, 走快路径
const PhoneSchema = z.string().regex(/^\+?\d{8,15}$/);

把所有简单 refine 改成 Zod 内置的等价方法(regex / min / max / length / email / url / uuid),耗时再减 15%。

修法整合:4 步组合优化

修法 1:schema 模块级 const 化

事故前我们的代码里有这种"看起来合理"的写法:

// ❌ 每个请求都重新建 schema 对象
function handler(req: Request) {
    const schema = z.object({
        userId: z.string(),
        amount: z.number(),
    });
    const data = schema.parse(req.body);
    // ...
}

每次请求都重新建 schema!虽然 V8 能优化掉一部分,但 schema 对象本身的内部结构(_def, shape, 等)每次都要重建。我们扫了一下代码,这种反模式占了 20%。改成:

// ✅ 模块级 const
const RequestSchema = z.object({
    userId: z.string(),
    amount: z.number(),
});

function handler(req: Request) {
    const data = RequestSchema.parse(req.body);
    // ...
}

简单但效果显著——这一改 -12% 耗时。

修法 2:safeParse 替代 parse

Zod 的 parse 失败时抛异常,而抛/接异常在 V8 里成本不低(尤其是堆栈展开)。我们事故前的代码是这样:

// ❌ 异常驱动
try {
    const data = schema.parse(req.body);
    return process(data);
} catch (err) {
    if (err instanceof z.ZodError) {
        return reply.status(400).send({ errors: err.errors });
    }
    throw err;
}

改成 safeParse(返回结果对象,不抛):

// ✅ 结果驱动
const result = schema.safeParse(req.body);
if (!result.success) {
    return reply.status(400).send({ errors: result.error.errors });
}
return process(result.data);

在校验失败率高的接口(比如对接旧版客户端,字段不规范),safeParse 改善明显。整体 -5%。

修法 3:选择性校验 + 路径分级

不是所有 API 都需要全量校验。我们分了 3 级:

L3 完全不用 Zod,只用手写 type guard:

function isStatsQuery(q: unknown): q is StatsQuery {
    return typeof q === 'object' && q !== null
        && typeof (q as any).startDate === 'string';
}

if (!isStatsQuery(req.query)) {
    return reply.status(400).send({ error: 'invalid query' });
}
// 之后 req.query 被 TS 认为是 StatsQuery

手写 guard 比 Zod 快 50 倍以上,代价是失去了详细错误信息和自动类型推导。但对读路径来说,客户端能容错,代价划算。

修法 4:边缘路径换 valibot

valibot 是 Zod 的"性能继承者"——同样的 schema-first API,但内部实现是 tree-shakable + 函数化(每个校验是独立函数,而不是 method on object),性能比 Zod 快 3-10 倍,bundle size 也小很多。

// Zod 写法
const ZodPhoneSchema = z.string().regex(/^\+?\d{8,15}$/);

// valibot 写法(同等功能)
import { string, regex, pipe } from 'valibot';
const ValibotPhoneSchema = pipe(string(), regex(/^\+?\d{8,15}$/));

我们没有全切 valibot(Zod 的生态、错误信息、社区支持更成熟),只在最热的几个端点用 valibot。这 5 个端点占总流量 60%,切完后整体 -10%。

基准对比:Zod vs valibot vs arktype vs 手写

我们对自己最复杂的 schema(8 层嵌套,40 字段,12-variant union)做了基准:

结论:

• Zod 即使优化后仍然比 valibot 慢 5 倍,但生态成熟度高
• valibot 是 Zod 的好替代,如果性能敏感且能接受稍弱的错误信息
• arktype 性能最佳但 API 学习曲线陡,适合愿意投入的团队
• 手写 guard 性能极致但失去 ergonomics,只适合极少数热点路径

决策树:面对一个新 API 路径该选什么校验方式

这棵决策树后来嵌进了 TS 团队的 PR 模板:任何新增 schema 的 PR,作者必须在 description 里说清楚走了哪条分支,以及预估的 parse 耗时。一个小改动让团队对运行时校验的性能直觉提升一个量级——以前是"先用 Zod 写完测一下没问题就 merge",现在是"写之前先想清楚预期开销"。code review 也因此变得更有抓手,新人入职第二周就能跟着这棵树做出合理选型。

5 天里被否决的方案

每条否决都让我们更清楚"真正要修什么"。最后选定的"4 步组合优化 + 部分 valibot"既是技术最优,也是组织成本最低——所有改动都在校验层,业务代码几乎不动。后来产品和老板问"为什么不全换 valibot 一劳永逸",我们直接甩这张表 5 分钟说服全场。这种"否决记录"在长期来看比"选定方案"价值还大。

整体效果

P99 从 80ms 降到 55ms,QPS 容量提升 60%——意味着我们可以缩 Pod 数量,节省成本约 30%。同时给后续业务增长腾出了空间。

给读者的几条自查清单

1. 跑一次火焰图(用 0x 或 clinic.js flame),看 Zod / Yup / Joi 占总耗时多少。> 10% 就值得优化。
2. 检查代码里 schema 是不是模块级 const。函数内 new schema 是常见反模式。
3. 看 schema 里有多少 refine。能换成 regex/min/max/length 等内置方法的全换。
4. 用 discriminatedUnion 替代 union,前提是有 discriminator 字段。
5. 把 parse 改 safeParse,显式处理结果。
6. 对读路径 / 低关键性接口,考虑用手写 type guard 替代 Zod。
7. 性能敏感的新项目,直接用 valibot 替代 Zod。
8. 把校验作为可监控指标:用 prom-client 记录 schema parse 耗时分布,定期 review。

立的《TypeScript 运行时校验纪律》

• schema 必须是模块级 const,禁止函数内部新建。
• 所有 schema 必须用 discriminatedUnion 而不是 union(如果有 discriminator)。
• 简单约束优先用 ZodString / ZodNumber 内置方法,refine 仅用于复杂业务逻辑。
• 错误处理用 safeParse,不允许靠 try-catch 处理校验失败。
• API 路径分 3 级:核心 L1 严格,普通 L2 标准,读路径 L3 宽松。
• 性能敏感的新项目优先 valibot,Zod 用于生态成熟度优先的场景。
• schema 校验耗时必须监控,prom-client 记录 P99,> 5ms 触发优化排查。
• 响应校验默认关闭(信任自己的代码),仅在 dev / staging 开启;生产环境只校验入参。

这次优化让我对"TypeScript 类型 vs 运行时校验"的关系有了更清晰的认识:TypeScript 类型是免费的(编译时),运行时校验不是免费的(运行时)。Zod 这类库通过"一份 schema 两边用"的设计极大降低了心智负担,但代价是把运行时开销隐藏在 ergonomics 背后。当项目规模和 QPS 上去后,这个隐藏的开销就会浮现。早期建立"校验是有成本"的意识,后期就不会被这种问题打到。

另一个心得:"性能瓶颈不在我以为的地方"几乎是性能优化的铁律。事故前如果有人让我猜 P99 80ms 里时间花在哪,我会猜数据库、外部 API、JSON parse,绝对猜不到 Zod。所以遇到性能问题永远先 profile,不要靠经验猜——经验告诉你的 80% 是"上次的瓶颈在哪",这次未必是。

这次复盘的长期收益

缩容 37% 这一项是意外收获——原以为修复是"省一些 CPU",结果是"省到可以缩 12 个 Pod"。集群层面立刻多出资源给其他服务,K8s 资源利用率从 56% 提到 74%。这种"性能优化反向带来成本节约"的链路,在云原生环境格外明显。一次 5 天的深度优化省下的钱够团队全员去一趟 KubeCon,这种 ROI 在 SRE 项目里很难得。

认知更新:对 TS 运行时校验的 4 个新认知

1. "schema 即代码"的便利性是有运行时代价的。Zod / Yup / Joi 这类库通过 fluent API 让校验代码写起来非常优雅,但每一个 method 调用背后都是动态分支 + 闭包 + 对象分配。小项目无感,QPS 上千的服务一定会被反咬一口。这不是这些库的 bug,是它们的设计哲学——优先 ergonomics 而非性能。意识到这个 trade-off 是写好高并发 TS 服务的起点。
2. "运行时校验"和"编译时类型"是两套独立的成本结构。TS 类型完全免费(编译时),Zod 校验完全收费(运行时)。"一份 schema 两边用"的设计模糊了这个区别,让开发者潜意识里把校验也当成"免费"——这是最危险的认知偏差。新人 onboarding 第一周就要把这个区别讲清楚:你写 z.object 不只是"声明类型",是"在每个请求上付 0.5-25ms 的运行时开销"。
3. "refine 一时爽,profile 火葬场"。refine 是 Zod 最强大的特性之一,允许嵌入任意校验逻辑。但每个 refine 都让 schema 升格为 ZodEffect,失去快路径优化。如果你的 schema 里 refine 多到 30+ 个,基本就告别"快路径"了。优先用内置方法(regex / min / max / length / email / url / uuid / cuid / ip / etc.)能覆盖 80% 的场景,剩下 20% 再考虑 refine。
4. "通用方案 vs 专用方案"的取舍在 TS 生态正在演化。Zod 是通用方案(覆盖 90% 场景,性能中等),valibot / arktype 是专用方案(同等场景下性能高 5-10 倍,但生态稍弱)。2026 年的 TS 生态正在从"all-in Zod"过渡到"按场景选库"——核心交易路径选 Zod 享受生态,边缘高吞吐路径选 valibot / arktype 享受性能。这种"混合栈"是成熟团队的标志,但要付出"维护两套校验心智模型"的代价,需要团队规模足够大才划算。

这次优化让我对"TypeScript 类型 vs 运行时校验"的关系有了更清晰的认识:TypeScript 类型是免费的(编译时),运行时校验不是免费的(运行时)。Zod 这类库通过"一份 schema 两边用"的设计极大降低了心智负担,但代价是把运行时开销隐藏在 ergonomics 背后。当项目规模和 QPS 上去后,这个隐藏的开销就会浮现。早期建立"校验是有成本"的意识,后期就不会被这种问题打到。

另一个心得:"性能瓶颈不在我以为的地方"几乎是性能优化的铁律。事故前如果有人让我猜 P99 80ms 里时间花在哪,我会猜数据库、外部 API、JSON parse,绝对猜不到 Zod。所以遇到性能问题永远先 profile,不要靠经验猜——经验告诉你的 80% 是"上次的瓶颈在哪",这次未必是。我们 SRE 团队后来立了规矩:任何"性能优化"类的工单,第一步必须贴一张当下的火焰图,看完图再讨论方案。光这一条挡掉了至少 5 次"凭直觉优化反而越优化越慢"的弯路。

第三个心得是关于"基准测试的覆盖度"。Zod 官方文档和大量社区 benchmark 跑的都是简单 schema(z.object({ name: z.string() })),这类基准下 Zod 单次 parse 只要几 microsecond,看起来快得离谱。我们的真实业务 schema(8 层嵌套 / 12 variant union / 30 个 refine)在同样 benchmark 框架下跑出来是 25ms——慢 4 个数量级。"官方 benchmark 快"和"你的业务 benchmark 快"是两件事,选型时一定要用自己最复杂的 schema 跑一遍,别信通用 benchmark。这个习惯后来扩展到所有库选型——ORM / cache / serializer 都先在自己真实数据上跑一遍,再做决策。半年下来挡掉了 3 次"看 benchmark 是最优结果生产慢爆"的坑。

第四个心得:"修这个性能问题"和"修这类性能问题"是两件事。原本我们计划改完 billing-api 就收工,后来主动扫了公司所有 14 个 Node 服务的 Zod 使用情况,挖出 6 个有类似性能隐患的服务。一次复盘的真正价值不是修当下,是把同类问题在它们爆雷前都摸出来。这种"主动扫雷"耗时大约是修一个 bug 的 4 倍,但避免 6 次类似事故——ROI 极其划算。我们后来在 SRE 团队设了固定流程,每次 P1 / P2 性能事故复盘后必须做"同类扫雷",这套流程半年下来主动避免了 9 次潜在事故,口碑提升非常明显。

最后再补一个工程文化层面的反思:这次事故触发前其实有过几次小信号——QPS 高峰期偶发 CPU 飙到 80% 几分钟、运维同学吐槽过 "billing-api 这服务怎么这么吃 CPU"、新人 onboarding 时问过"为什么这么多 refine 包来包去",每次大家都用"还能用"、"是历史代码"、"先这样"绕过去。所有大优化机会都有它的"预热信号",区别只在团队有没有把它当回事。我们后来在事故管理里加了"小信号月度复盘"机制——把过去 30 天的所有低优先级告警 + 运维抱怨 + 新人提出的"为什么这样"问题集中拉一遍,挑出可能值得深挖的提前修。半年下来这个机制至少提前避免了 4 次类似量级的性能问题,投入产出比远超事后排查。希望读到这里的你也能在自己团队里建立类似的"小信号雷达",别再让一个看似无害的 Zod 写法把团队 3 年后的某个忙碌下午毁掉。

下次有人在 TS 项目里写 const schema = z.object({...}) 时,别只想着"类型推导真方便",顺手 profile 一下。说不定你也能在火焰图上找到一个让你"等等,这怎么这么慢"的色块。修完之后你会发现,同样的业务逻辑、同样的硬件配置,API 突然就能多扛 60% 的 QPS——其实代码没变,变的只是你终于看清了 Zod 的真实成本。这种"零业务改动却带来性能跃迁"的工程红利,在 TS 高并发服务里非常常见,值得每个团队投入一次彻底的复盘。如果你在自家服务上也做了类似的 Zod 优化,欢迎在评论区分享你的火焰图截图、最终的 P99 数据,以及踩到的其他 schema 性能反模式——TS 运行时校验工程化这块,中文社区沉淀的实战经验还很稀缺,每一份数据都是后来者的灯塔,愿我们的 5 天踩坑能换你 30 分钟就内化成自己团队的工程默认值,把每一个 Pod 的 CPU 周期都用在真正的业务价值上,而不是浪费在本可以避免的 schema 解释开销里。

—— 别看了 · 2026