🚀 快速安装

复制以下命令并运行，立即安装此 Skill：

npx @anthropic-ai/skills install wshobson/agents/typescript-advanced-types

💡 提示：需要 Node.js 和 NPM

TypeScript 高级类型

掌握 TypeScript 高级类型系统的综合指南，包括泛型、条件类型、映射类型、模板字面量类型和实用类型，用于构建健壮、类型安全的应用程序。

何时使用此技能

  • 构建类型安全的库或框架
  • 创建可重用的泛型组件
  • 实现复杂的类型推断逻辑
  • 设计类型安全的 API 客户端
  • 构建表单验证系统
  • 创建强类型的配置对象
  • 实现类型安全的状态管理
  • 将 JavaScript 代码库迁移到 TypeScript

核心概念

1. 泛型

目的：创建可重用、类型灵活的组件，同时保持类型安全。

基础泛型函数：

function identity<T>(value: T): T {
  return value;
}

const num = identity<number>(42); // 类型: number
const str = identity<string>("你好"); // 类型: string
const auto = identity(true); // 类型推断: boolean

泛型约束：

interface HasLength {
  length: number;
}

function logLength<T extends HasLength>(item: T): T {
  console.log(item.length);
  return item;
}

logLength("你好"); // 正确: 字符串有 length
logLength([1, 2, 3]); // 正确: 数组有 length
logLength({ length: 10 }); // 正确: 对象有 length
// logLength(42);             // 错误: 数字没有 length

多个类型参数：

function merge<T, U>(obj1: T, obj2: U): T & U {
  return { ...obj1, ...obj2 };
}

const merged = merge({ name: "张三" }, { age: 30 });
// 类型: { name: string } & { age: number }

2. 条件类型

目的：创建依赖于条件的类型，实现复杂的类型逻辑。

基础条件类型：

type IsString<T> = T extends string ? true : false;

type A = IsString<string>; // true
type B = IsString<number>; // false

提取返回类型：

type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;

function getUser() {
  return { id: 1, name: "张三" };
}

type User = ReturnType<typeof getUser>;
// 类型: { id: number; name: string; }

分布式条件类型：

type ToArray<T> = T extends any ? T[] : never;

type StrOrNumArray = ToArray<string | number>;
// 类型: string[] | number[]

嵌套条件：

type TypeName<T> = T extends string
  ? "string"
  : T extends number
    ? "number"
    : T extends boolean
      ? "boolean"
      : T extends undefined
        ? "undefined"
        : T extends Function
          ? "function"
          : "object";

type T1 = TypeName<string>; // "string"
type T2 = TypeName<() => void>; // "function"

3. 映射类型

目的：通过迭代现有类型的属性来转换它们。

基础映射类型：

type Readonly<T> = {
  readonly [P in keyof T]: T[P];
};

interface User {
  id: number;
  name: string;
}

type ReadonlyUser = Readonly<User>;
// 类型: { readonly id: number; readonly name: string; }

可选属性：

type Partial<T> = {
  [P in keyof T]?: T[P];
};

type PartialUser = Partial<User>;
// 类型: { id?: number; name?: string; }

键重映射：

type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

interface Person {
  name: string;
  age: number;
}

type PersonGetters = Getters<Person>;
// 类型: { getName: () => string; getAge: () => number; }

过滤属性：

type PickByType<T, U> = {
  [K in keyof T as T[K] extends U ? K : never]: T[K];
};

interface Mixed {
  id: number;
  name: string;
  age: number;
  active: boolean;
}

type OnlyNumbers = PickByType<Mixed, number>;
// 类型: { id: number; age: number; }

4. 模板字面量类型

目的：创建具有模式匹配和转换功能的基于字符串的类型。

基础模板字面量：

type EventName = "click" | "focus" | "blur";
type EventHandler = `on${Capitalize<EventName>}`;
// 类型: "onClick" | "onFocus" | "onBlur"

字符串操作：

type UppercaseGreeting = Uppercase<"hello">; // "HELLO"
type LowercaseGreeting = Lowercase<"HELLO">; // "hello"
type CapitalizedName = Capitalize<"john">; // "John"
type UncapitalizedName = Uncapitalize<"John">; // "john"

路径构建：

type Path<T> = T extends object
  ? {
      [K in keyof T]: K extends string ? `${K}` | `${K}.${Path<T[K]>}` : never;
    }[keyof T]
  : never;

interface Config {
  server: {
    host: string;
    port: number;
  };
  database: {
    url: string;
  };
}

type ConfigPath = Path<Config>;
// 类型: "server" | "database" | "server.host" | "server.port" | "database.url"

5. 实用类型

内置实用类型：

// Partial<T> - 使所有属性变为可选
type PartialUser = Partial<User>;

// Required<T> - 使所有属性变为必选
type RequiredUser = Required<PartialUser>;

// Readonly<T> - 使所有属性变为只读
type ReadonlyUser = Readonly<User>;

// Pick<T, K> - 选择特定属性
type UserName = Pick<User, "name" | "email">;

// Omit<T, K> - 移除特定属性
type UserWithoutPassword = Omit<User, "password">;

// Exclude<T, U> - 从联合类型中排除类型
type T1 = Exclude<"a" | "b" | "c", "a">; // "b" | "c"

// Extract<T, U> - 从联合类型中提取类型
type T2 = Extract<"a" | "b" | "c", "a" | "b">; // "a" | "b"

// NonNullable<T> - 排除 null 和 undefined
type T3 = NonNullable<string | null | undefined>; // string

// Record<K, T> - 创建键类型为 K，值类型为 T 的对象类型
type PageInfo = Record<"home" | "about", { title: string }>;

高级模式

模式 1：类型安全的事件发射器

type EventMap = {
  "user:created": { id: string; name: string };
  "user:updated": { id: string };
  "user:deleted": { id: string };
};

class TypedEventEmitter<T extends Record<string, any>> {
  private listeners: {
    [K in keyof T]?: Array<(data: T[K]) => void>;
  } = {};

  on<K extends keyof T>(event: K, callback: (data: T[K]) => void): void {
    if (!this.listeners[event]) {
      this.listeners[event] = [];
    }
    this.listeners[event]!.push(callback);
  }

  emit<K extends keyof T>(event: K, data: T[K]): void {
    const callbacks = this.listeners[event];
    if (callbacks) {
      callbacks.forEach((callback) => callback(data));
    }
  }
}

const emitter = new TypedEventEmitter<EventMap>();

emitter.on("user:created", (data) => {
  console.log(data.id, data.name); // 类型安全！
});

emitter.emit("user:created", { id: "1", name: "张三" });
// emitter.emit("user:created", { id: "1" });  // 错误: 缺少 'name'

模式 2：类型安全的 API 客户端

type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE";

type EndpointConfig = {
  "/users": {
    GET: { response: User[] };
    POST: { body: { name: string; email: string }; response: User };
  };
  "/users/:id": {
    GET: { params: { id: string }; response: User };
    PUT: { params: { id: string }; body: Partial<User>; response: User };
    DELETE: { params: { id: string }; response: void };
  };
};

type ExtractParams<T> = T extends { params: infer P } ? P : never;
type ExtractBody<T> = T extends { body: infer B } ? B : never;
type ExtractResponse<T> = T extends { response: infer R } ? R : never;

class APIClient<Config extends Record<string, Record<HTTPMethod, any>>> {
  async request<Path extends keyof Config, Method extends keyof Config[Path]>(
    path: Path,
    method: Method,
    ...[options]: ExtractParams<Config[Path][Method]> extends never
      ? ExtractBody<Config[Path][Method]> extends never
        ? []
        : [{ body: ExtractBody<Config[Path][Method]> }]
      : [
          {
            params: ExtractParams<Config[Path][Method]>;
            body?: ExtractBody<Config[Path][Method]>;
          },
        ]
  ): Promise<ExtractResponse<Config[Path][Method]>> {
    // 实现代码
    return {} as any;
  }
}

const api = new APIClient<EndpointConfig>();

// 类型安全的 API 调用
const users = await api.request("/users", "GET");
// 类型: User[]

const newUser = await api.request("/users", "POST", {
  body: { name: "张三", email: "zhangsan@example.com" },
});
// 类型: User

const user = await api.request("/users/:id", "GET", {
  params: { id: "123" },
});
// 类型: User

模式 3：类型安全的构建器模式

type BuilderState<T> = {
  [K in keyof T]: T[K] | undefined;
};

type RequiredKeys<T> = {
  [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
}[keyof T];

type OptionalKeys<T> = {
  [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
}[keyof T];

type IsComplete<T, S> =
  RequiredKeys<T> extends keyof S
    ? S[RequiredKeys<T>] extends undefined
      ? false
      : true
    : false;

class Builder<T, S extends BuilderState<T> = {}> {
  private state: S = {} as S;

  set<K extends keyof T>(key: K, value: T[K]): Builder<T, S & Record<K, T[K]>> {
    this.state[key] = value;
    return this as any;
  }

  build(this: IsComplete<T, S> extends true ? this : never): T {
    return this.state as T;
  }
}

interface User {
  id: string;
  name: string;
  email: string;
  age?: number;
}

const builder = new Builder<User>();

const user = builder
  .set("id", "1")
  .set("name", "张三")
  .set("email", "zhangsan@example.com")
  .build(); // 正确: 所有必填字段已设置

// const incomplete = builder
//   .set("id", "1")
//   .build();  // 错误: 缺少必填字段

模式 4：深层只读/部分类型

type DeepReadonly<T> = {
  readonly [P in keyof T]: T[P] extends object
    ? T[P] extends Function
      ? T[P]
      : DeepReadonly<T[P]>
    : T[P];
};

type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object
    ? T[P] extends Array<infer U>
      ? Array<DeepPartial<U>>
      : DeepPartial<T[P]>
    : T[P];
};

interface Config {
  server: {
    host: string;
    port: number;
    ssl: {
      enabled: boolean;
      cert: string;
    };
  };
  database: {
    url: string;
    pool: {
      min: number;
      max: number;
    };
  };
}

type ReadonlyConfig = DeepReadonly<Config>;
// 所有嵌套属性都是只读的

type PartialConfig = DeepPartial<Config>;
// 所有嵌套属性都是可选的

模式 5：类型安全的表单验证

type ValidationRule<T> = {
  validate: (value: T) => boolean;
  message: string;
};

type FieldValidation<T> = {
  [K in keyof T]?: ValidationRule<T[K]>[];
};

type ValidationErrors<T> = {
  [K in keyof T]?: string[];
};

class FormValidator<T extends Record<string, any>> {
  constructor(private rules: FieldValidation<T>) {}

  validate(data: T): ValidationErrors<T> | null {
    const errors: ValidationErrors<T> = {};
    let hasErrors = false;

    for (const key in this.rules) {
      const fieldRules = this.rules[key];
      const value = data[key];

      if (fieldRules) {
        const fieldErrors: string[] = [];

        for (const rule of fieldRules) {
          if (!rule.validate(value)) {
            fieldErrors.push(rule.message);
          }
        }

        if (fieldErrors.length > 0) {
          errors[key] = fieldErrors;
          hasErrors = true;
        }
      }
    }

    return hasErrors ? errors : null;
  }
}

interface LoginForm {
  email: string;
  password: string;
}

const validator = new FormValidator<LoginForm>({
  email: [
    {
      validate: (v) => v.includes("@"),
      message: "邮箱必须包含 @",
    },
    {
      validate: (v) => v.length > 0,
      message: "邮箱是必填项",
    },
  ],
  password: [
    {
      validate: (v) => v.length >= 8,
      message: "密码至少需要 8 个字符",
    },
  ],
});

const errors = validator.validate({
  email: "invalid",
  password: "short",
});
// 类型: { email?: string[]; password?: string[]; } | null

模式 6：可辨识联合类型

type Success<T> = {
  status: "success";
  data: T;
};

type Error = {
  status: "error";
  error: string;
};

type Loading = {
  status: "loading";
};

type AsyncState<T> = Success<T> | Error | Loading;

function handleState<T>(state: AsyncState<T>): void {
  switch (state.status) {
    case "success":
      console.log(state.data); // 类型: T
      break;
    case "error":
      console.log(state.error); // 类型: string
      break;
    case "loading":
      console.log("加载中...");
      break;
  }
}

// 类型安全的状态机
type State =
  | { type: "idle" }
  | { type: "fetching"; requestId: string }
  | { type: "success"; data: any }
  | { type: "error"; error: Error };

type Event =
  | { type: "FETCH"; requestId: string }
  | { type: "SUCCESS"; data: any }
  | { type: "ERROR"; error: Error }
  | { type: "RESET" };

function reducer(state: State, event: Event): State {
  switch (state.type) {
    case "idle":
      return event.type === "FETCH"
        ? { type: "fetching", requestId: event.requestId }
        : state;
    case "fetching":
      if (event.type === "SUCCESS") {
        return { type: "success", data: event.data };
      }
      if (event.type === "ERROR") {
        return { type: "error", error: event.error };
      }
      return state;
    case "success":
    case "error":
      return event.type === "RESET" ? { type: "idle" } : state;
  }
}

类型推断技术

1. Infer 关键字

// 提取数组元素类型
type ElementType<T> = T extends (infer U)[] ? U : never;

type NumArray = number[];
type Num = ElementType<NumArray>; // number

// 提取 Promise 类型
type PromiseType<T> = T extends Promise<infer U> ? U : never;

type AsyncNum = PromiseType<Promise<number>>; // number

// 提取函数参数
type Parameters<T> = T extends (...args: infer P) => any ? P : never;

function foo(a: string, b: number) {}
type FooParams = Parameters<typeof foo>; // [string, number]

2. 类型守卫

function isString(value: unknown): value is string {
  return typeof value === "string";
}

function isArrayOf<T>(
  value: unknown,
  guard: (item: unknown) => item is T,
): value is T[] {
  return Array.isArray(value) && value.every(guard);
}

const data: unknown = ["a", "b", "c"];

if (isArrayOf(data, isString)) {
  data.forEach((s) => s.toUpperCase()); // 类型: string[]
}

3. 断言函数

function assertIsString(value: unknown): asserts value is string {
  if (typeof value !== "string") {
    throw new Error("不是字符串");
  }
}

function processValue(value: unknown) {
  assertIsString(value);
  // value 现在被类型化为 string
  console.log(value.toUpperCase());
}

最佳实践

  1. 使用 unknown 而非 any：强制进行类型检查
  2. 对于对象形状，优先使用 interface：错误信息更好
  3. 对于联合类型和复杂类型，使用 type：更灵活
  4. 利用类型推断：尽可能让 TypeScript 自己推断
  5. 创建辅助类型：构建可重用的类型工具
  6. 使用 const 断言：保留字面量类型
  7. 避免类型断言：改用类型守卫
  8. 为复杂类型添加文档：使用 JSDoc 注释
  9. 使用严格模式：启用所有严格的编译器选项
  10. 测试你的类型：使用类型测试来验证类型行为

类型测试

// 类型断言测试
type AssertEqual<T, U> = [T] extends [U]
  ? [U] extends [T]
    ? true
    : false
  : false;

type Test1 = AssertEqual<string, string>; // true
type Test2 = AssertEqual<string, number>; // false
type Test3 = AssertEqual<string | number, string>; // false

// 期望错误的辅助类型
type ExpectError<T extends never> = T;

// 使用示例
type ShouldError = ExpectError<AssertEqual<string, number>>;

常见陷阱

  1. 过度使用 any：违背了 TypeScript 的初衷
  2. 忽略严格的空值检查：可能导致运行时错误
  3. 类型过于复杂：可能减慢编译速度
  4. 不使用可辨识联合类型：错过了类型收窄的机会
  5. 忘记 readonly 修饰符：可能导致意外的修改
  6. 循环类型引用：可能导致编译器错误
  7. 未处理边缘情况：例如空数组或 null 值

性能考虑

  • 避免深度嵌套的条件类型
  • 尽可能使用简单类型
  • 缓存复杂的类型计算结果
  • 限制递归类型的递归深度
  • 在生产环境中使用构建工具跳过类型检查

📄 原始文档

完整文档（英文）：

https://skills.sh/wshobson/agents/typescript-advanced-types

💡 提示：点击上方链接查看 skills.sh 原始英文文档，方便对照翻译。

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。