TypeScript 类型系统实战：从基础到高级工具类型

为什么工具站需要 TypeScript？

工具库有 200+ 工具页、4 语言 i18n、复杂的工具客户端配置。纯 JavaScript 在以下场景容易出错：

• 工具配置对象的字段拼写错误
• i18n key 不存在但未报错
• API 响应结构与预期不符
• 重构时遗漏更新引用

TypeScript 在编译期捕获这些错误，而非运行时。

---

核心类型技巧

1. 类型推断 vs 显式标注

// ✅ 让 TS 推断（简洁）
const tools = [{ href: '/pdf/merge', name: 'PDF合并' }] as const;

// ✅ 需要约束时显式标注
function getTool(href: string): ToolItem | undefined {
  return ALL_TOOLS.find(t => t.href === href);
}

2. 泛型约束

function encode<T extends string | ArrayBuffer>(
  input: T
): T extends string ? string : ArrayBuffer {
  // 根据输入类型返回不同结果
}

3. 联合类型与类型守卫

type ProcessResult =
  | { status: 'success'; data: Blob }
  | { status: 'error'; message: string };

function handleResult(result: ProcessResult) {
  if (result.status === 'success') {
    downloadBlob(result.data); // TS 知道 data 存在
  }
}

---

高级工具类型

Partial、Required、Pick、Omit

type ToolConfig = {
  href: string;
  name: string;
  blurb: string;
  i18nKey?: string;
};

type ToolUpdate = Partial<ToolConfig>;        // 所有字段可选
type ToolRequired = Required<ToolConfig>;      // 所有字段必填
type ToolPreview = Pick<ToolConfig, 'name' | 'blurb'>; // 只取部分

条件类型

type IsString<T> = T extends string ? true : false;
type A = IsString<'hello'>;  // true
type B = IsString<42>;       // false

映射类型

type Readonly<T> = { readonly [K in keyof T]: T[K] };
type Nullable<T> = { [K in keyof T]: T[K] | null };

---

JSON → TypeScript 生成

工具库 JSON 转 TypeScript 工具的实现逻辑：

function jsonToTypeScript(json: unknown, name = 'Root'): string {
  if (Array.isArray(json)) {
    return `${name}[]`;
  }
  if (typeof json === 'object' && json !== null) {
    const fields = Object.entries(json).map(([key, value]) => {
      const type = jsonToTypeScript(value, capitalize(key));
      return `  ${key}: ${type};`;
    });
    return `interface ${name} {\n${fields.join('\n')}\n}`;
  }
  return typeof json; // string | number | boolean
}

输入 API 响应 JSON，一键生成 TypeScript interface——减少手动编写类型的工作量。

---

实用模式

satisfies 运算符（TS 4.9+）

const config = {
  locales: ['zh-CN', 'en'],
  defaultLocale: 'zh-CN',
} satisfies RoutingConfig; // 保留字面量类型，同时校验结构

const 类型参数（TS 5.0+）

function createTool<const T extends string>(href: T) {
  return { href } as const;
}
const tool = createTool('/pdf/merge'); // href 类型为 '/pdf/merge'，非 string

---

总结

TypeScript 的类型系统不仅是「加类型注解」，更是一套编译期编程语言。掌握泛型、条件类型和工具类型，可以构建自文档化、重构安全的代码库。工具库的 JSON 转 TypeScript 工具则是类型驱动开发的实用起点。