TypeScript 工程实践：从类型系统到项目架构的落地方法

先说结论：TypeScript 的优势不在”类型”，而在”可维护性”

很多团队用 TypeScript 只是因为”大家都在用”，但实际项目中 any 满天飞，类型定义和实际代码不一致，TypeScript 变成了”加了类型检查的 JavaScript”——该出的 bug 一个没少。

本文从四个层面展开：类型系统、错误处理、项目结构、配置策略。

---

1. 类型系统：用好 discriminated union 和类型收窄

1.1 用 discriminated union 替代可选字段

这是最常见的反模式：用一个对象类型，里面全是可选字段，运行时判断字段是否存在。

// ❌ 反模式
type ApiResponse = {
  success?: boolean;
  data?: any;
  error?: string;
};

// ✅ 推荐：discriminated union
type ApiResponse<T> = 
  | { success: true; data: T }
  | { success: false; error: string };

discriminated union 的好处是：TypeScript 会在类型收窄后自动推断出可用的字段，不需要手动判断。

const res: ApiResponse<User> = await fetchUser();
if (res.success) {
  console.log(res.data.name); // ✅ TypeScript 知道 data 存在
} else {
  console.log(res.error);     // ✅ TypeScript 知道 error 存在
}

1.2 类型收窄的几种方式

// typeof 收窄（原始类型）
if (typeof x === 'string') { /* x: string */ }

// instanceof 收窄（类实例）
if (x instanceof Error) { /* x: Error */ }

// in 操作符收窄（对象属性）
if ('error' in x) { /* x: 有 error 属性的类型 */ }

// 自定义类型守卫
function isUser(x: any): x is User {
  return x && typeof x.id === 'number' && typeof x.name === 'string';
}

---

2. 错误处理：用 Result 模式替代 throw

2.1 为什么不用 throw

throw 的问题在于：TypeScript 不强制调用方处理异常。一个函数 throws 了，但调用方可能忘了写 try-catch，程序会在运行时崩溃。

2.2 Result 模式实现

type Result<T, E = Error> = 
  | { ok: true; value: T }
  | { ok: false; error: E };

function parseJSON(json: string): Result<unknown> {
  try {
    return { ok: true, value: JSON.parse(json) };
  } catch (e) {
    return { ok: false, error: e as Error };
  }
}

// 调用方必须处理两种情况
const result = parseJSON('{"name":"test"}');
if (result.ok) {
  console.log(result.value); // ✅ 类型安全
} else {
  console.error(result.error.message); // ✅ 必须处理错误
}

2.3 顶层统一处理

在 API 路由或事件处理函数的顶层，将 Result 统一转换为响应：

app.get('/users', async (req, res) => {
  const result = await getUsers();
  if (!result.ok) {
    return res.status(500).json({ error: result.error.message });
  }
  res.json(result.value);
});

---

3. 项目结构：分层清晰的类型定义

3.1 推荐目录结构

src/
  types/           # 全局共享类型
    user.ts
    api.ts
    common.ts
  api/             # API 调用层
    types.ts       # 接口对应的类型（自动生成）
    client.ts
  utils/           # 工具函数
    result.ts      # Result 类型定义
  components/      # 组件
    UserCard.tsx

3.2 类型文件只放类型

不要在类型文件中写实现代码，哪怕只是一个简单的函数。类型文件和实现文件分离，职责清晰。

---

4. 配置策略

{
  "compilerOptions": {
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

---

总结

层面	核心原则	常见错误
类型系统	用 discriminated union 替代可选字段	any 满天飞
错误处理	Result 模式替代 throw	漏掉 try-catch
项目结构	类型和实现分离	类型文件中写实现代码
配置	strict: true	逐项关闭严格检查

TypeScript 的价值不在于”写了类型”，而在于”类型帮你发现了你没想到的 bug”。 如果配置了 strict 模式、用了 discriminated union 和 Result 模式，TypeScript 的收益会远远大于它的学习成本。

需要 TypeScript 项目搭建或技术咨询？联系我们，说清你的项目规模与团队情况，24 小时内回可行性。

相关阅读

• 技术方案评审怎么做：选型、架构评审与可行性报告的方法 —— TypeScript 选型的技术决策方法
• 前端性能优化实战：从 Lighthouse 50 到 100 —— TypeScript 项目的性能优化实践