TypeScript类型检查实战：提升代码健壮性的关键技巧

为什么我又在折腾类型检查？

最近重构一个老项目，代码里全是 any 和隐式转换，调个接口传错字段都能跑通，直到上线才报错。我忍不了了，决定把类型检查搞起来。但选型时又犯难了：TypeScript、JSDoc + VS Code、运行时校验（比如 Zod），到底用哪个？

别被“安全”这个分类吓到——类型检查不是银弹，但它能拦住 80% 的低级错误。我试过这三种方案，踩过坑，也省过事，今天就掏心窝子聊聊。

谁更灵活？谁更省事？

先说结论：中小型项目我直接上 TypeScript，大型项目混合用 TS + Zod。JSDoc 方案我基本不用了，除非是维护遗留 JS 项目没法改构建流程。

来看具体代码。假设我们要处理一个用户数据接口：

// 假设这是从 https://jztheme.com/api/user 拿到的数据
const userData = {
  id: 123,
  name: "张三",
  email: "zhangsan@example.com",
  isActive: true
};

TypeScript 写法：

interface User {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
}

function processUser(user: User) {
  // 编译时就能检查类型
  console.log(user.name.toUpperCase());
}

优点很明显：开发时写错字段，VS Code 立刻标红；重构时重命名属性，全项目自动更新。但缺点也很痛：一旦用了 any 或 as 断言，类型防护就形同虚设。我见过太多人为了“快速上线”疯狂加 as any，最后类型系统成了摆设。

JSDoc + VS Code 方案：

/**
 * @typedef {Object} User
 * @property {number} id
 * @property {string} name
 * @property {string} email
 * @property {boolean} isActive
 */

/**
 * @param {User} user
 */
function processUser(user) {
  console.log(user.name.toUpperCase()); // VS Code 能提示
}

这个方案对纯 JS 项目友好，不用改构建配置。但体验差一截：类型提示偶尔抽风，泛型支持弱，而且只能在编辑器里检查，运行时照样崩。我之前在一个 React 项目里用它，结果因为对象嵌套太深，VS Code 直接放弃类型推导，最后还是切回了 TS。

运行时校验（Zod）：

import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  isActive: z.boolean()
});

function processUser(data) {
  const user = UserSchema.parse(data); // 运行时校验，失败抛错
  console.log(user.name.toUpperCase());
}

Zod 的优势在于：**数据来源不可信时（比如 API 返回、用户输入），它能真正在运行时兜底**。而且它还能生成 TypeScript 类型：

type User = z.infer<typeof UserSchema>; // 自动推导出和上面一样的 interface

但问题也很明显：要写两套校验逻辑（TS 编译时 + Zod 运行时），性能有开销（虽然通常可忽略）。另外，Zod 的学习曲线比 TS 原生类型陡一点，特别是处理复杂嵌套结构时。

我的选型逻辑

我一般按这几个原则来：

• 新项目无脑 TS：现在 Vite、Next.js 对 TS 支持都很好，开箱即用。写起来爽，团队协作也规范。
• 老 JS 项目能不动就不动：如果只是小修小补，用 JSDoc 临时加点类型提示就够了。别为了类型检查把整个构建流程重写，得不偿失。
• 涉及外部数据源，必须加运行时校验：API 返回、localStorage 读取、URL 参数——这些地方 TS 是防不住的。我现在的做法是：TS 定义接口 + Zod 校验数据，双重保险。

举个实际例子：我有个表单提交功能，前端用 TS 定义了 FormData 类型，但后端可能返回不符合预期的字段（比如把数字写成字符串）。这时候只靠 TS 会漏掉问题，加一行 Zod 校验就稳了：

const formData = UserSchema.parse(await response.json());

这里注意我踩过好几次坑：Zod 默认严格模式，如果 API 多返回了字段会直接报错。解决方法是加 .strict() 或 .passthrough()，按需选择：

// 允许额外字段
const UserSchema = z.object({ /* ... */ }).passthrough();

性能对比：差距比我想象的大

有人担心 Zod 运行时校验会影响性能。我实测过：校验一个 10 个字段的对象，Zod 耗时约 0.02ms，而 TS 编译后的代码几乎为零开销。但在 99% 的场景下，这点开销可以忽略——除非你每秒校验上万次数据（那可能是架构问题了）。

真正影响性能的是开发效率。TS 虽然编译慢一点，但减少的调试时间远超等待编译的时间。而 JSDoc 方案看似“零成本”，但类型提示不稳定反而让我多花时间查文档。

结尾：没有银弹，只有权衡

总结一下我的偏好：

• 首选 TypeScript：开发体验好，生态成熟，适合绝大多数场景。
• 关键数据入口加 Zod：防御外部不可信数据，避免运行时崩溃。
• JSDoc 当备胎：仅用于无法引入 TS 的遗留项目。

改完后仍有一两个小问题：比如 Zod 和 TS 类型要维护两份（虽然可以用 z.infer 减少重复），但无大碍。毕竟类型检查的目标不是 100% 安全，而是减少低级错误带来的加班。

以上是我个人对类型检查方案的完整讲解，有更优的实现方式欢迎评论区交流。最近还在研究如何用 Zod 自动生成 API 文档，后续会继续分享这类博客。