TypeScript 5.x实用技巧完全指南：装饰器、类型体操与性能优化（2026最新）

1
// 传统experimental装饰器（TS 4.x）
2
function logged(originalMethod: any, context: any) {
3
  // 实验性实现，不符合ECMAScript规范
4
  // 需要启用 experimentalDecorators
5
}
6

7
class Example {
8
  @logged
9
  method() {}
10
}

1
// TS 5.x：符合ECMAScript规范的装饰器
2
function logged(
3
  value: Function,
4
  context: ClassMethodDecoratorContext
5
) {
6
  const name = context.name;
7

8
  return function(this: any, ...args: any[]) {
9
    console.log(`Calling ${String(name)} with args: ${args}`);
10
    return value.apply(this, args);
11
  };
12
}
13

14
class Example {
15
  @logged
16
  method(arg: string) {
17
    return `processed: ${arg}`;
18
  }
19
}
20

21
const example = new Example();
22
example.method('test');
23
// Calling method with args: test
24
// processed: test

1
// 类装饰器
2
type ClassDecorator = (
3
  value: Class,
4
  context: ClassDecoratorContext
5
) => Class | void;
6

7
// 方法装饰器
8
type ClassMethodDecorator = (
9
  value: Function,
10
  context: ClassMethodDecoratorContext
11
) => Function | void;
12

13
// 属性装饰器
14
type ClassFieldDecorator = (
15
  value: undefined,
16
  context: ClassFieldDecoratorContext
17
) => (initialValue: unknown) => unknown | void;
18

19
// getter/setter装饰器
20
type ClassGetterDecorator = (
21
  value: Function,
22
  context: ClassGetterDecoratorContext
23
) => Function | void;
24

25
type ClassSetterDecorator = (
26
  value: Function,
27
  context: ClassSetterDecoratorContext
28
) => Function | void;

1
interface ClassMethodDecoratorContext {
2
  kind: 'method';           // 装饰器类型
3
  name: string | symbol;    // 方法名
4
  static: boolean;          // 是否静态方法
5
  private: boolean;         // 是否私有方法
6
  access: {                 // 访问器
7
    has?(obj: object): boolean;
8
    get?(obj: object): unknown;
9
    set?(obj: object, value: unknown): void;
10
  };
11
  addInitializer?(initializer: () => void): void; // 初始化钩子
12
}

1
// 传统：as 类型断言
2
const colors = {
3
  red: '#ff0000',
4
  green: '#00ff00',
5
  blue: '#0000ff'
6
} as Record<string, string>;
7

8
// 问题：类型推断丢失
9
colors.red; // 类型为 string，而非 '#ff0000'
10
// 可以赋值为任意字符串
11
colors.red = 'invalid'; // 允许！

1
// TS 5.x：satisfies 运算符
2
const colors = {
3
  red: '#ff0000',
4
  green: '#00ff00',
5
  blue: '#0000ff'
6
} satisfies Record<string, string>;
7

8
// 优点：类型检查 + 保留具体类型
9
colors.red; // 类型为 '#ff0000'（字面量类型）
10
// 只能赋值为 '#ff0000'
11
colors.red = 'invalid'; // Error!
12
colors.red = '#ff0000'; // OK

1
// 提取Promise返回类型
2
type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;
3

4
type Result1 = Awaited<Promise<string>>; // string
5
type Result2 = Awaited<Promise<Promise<number>>>; // number
6

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

10
type Args = Parameters<(a: string, b: number) => void>;
11
// [string, number]
12

13
// 提取函数返回类型
14
type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
15

16
type Return = ReturnType<() => string>; // string
17

18
// 提取数组元素类型
19
type Element<T> = T extends (infer E)[] ? E : never;
20

21
type Item = Element<string[]>; // string

1
// 递归类型：深度Required
2
type DeepRequired<T> = {
3
  [K in keyof T]: T[K] extends object ? DeepRequired<T[K]> : Required<T[K]>
4
};
5

6
type Obj = { a?: { b?: string } };
7
type RequiredObj = DeepRequired<Obj>;
8
// { a: { b: string } }
9

10
// 递归类型：深度Partial
11
type DeepPartial<T> = {
12
  [K in keyof T]: T[K] extends object ? DeepPartial<T[K]> : T[K] | undefined
13
};
14

15
// 递归类型：深度Readonly
16
type DeepReadonly<T> = {
17
  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K]
18
};

1
// 字符串模板
2
type EventName = `on${Capitalize<string>}`;
3

4
type MouseEvents = EventName; // 'onClick' | 'onMouseover' | ...
5

6
// 路径模板
7
type Path<S extends string> = `/${S}`;
8

9
type ApiPath = Path<'api/users'>; // '/api/users'
10

11
// 组合模板
12
type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
13
type Endpoint = `${HTTPMethod} ${string}`;
14

15
type Route = Endpoint; // 'GET /api' | 'POST /users' | ...
16

17
// 类型推断
18
type Split<S extends string, D extends string> =
19
  S extends `${infer Head}${D}${infer Tail}`
20
    ? [Head, ...Split<Tail, D>]
21
    : [S];
22

23
type Parts = Split<'a/b/c', '/'>; // ['a', 'b', 'c']

1
// 提取对象值类型
2
type ValueOf<T> = T[keyof T];
3

4
type Obj = { a: string; b: number };
5
type Values = ValueOf<Obj>; // string | number
6

7
// 提取对象键类型
8
type KeysOf<T> = keyof T;
9

10
// 限制键类型
11
type StringKeys<T> = Extract<keyof T, string>;
12

13
// 排除特定键
14
type ExcludeKeys<T, K extends keyof T> = Omit<T, K>;
15

16
// 合并类型
17
type Merge<A, B> = Omit<A, keyof B> & B;

1
// 自定义类型守卫
2
function isString(value: unknown): value is string {
3
  return typeof value === 'string';
4
}
5

6
// 数组类型守卫
7
function isArrayOf<T>(value: unknown, guard: (v: unknown) => v is T): value is T[] {
8
  return Array.isArray(value) && value.every(guard);
9
}
10

11
// 对象类型守卫
12
function hasProperty<K extends string>(obj: unknown, key: K): obj is Record<K, unknown> {
13
  return typeof obj === 'object' && obj !== null && key in obj;
14
}
15

16
// 断言函数（TS 5.5+）
17
function assertIsString(value: unknown): asserts value is string {
18
  if (typeof value !== 'string') {
19
    throw new TypeError('Expected string');
20
  }
21
}

1
{
2
  "compilerOptions": {
3
    "strict": true,
4
    "strictNullChecks": true,
5
    "strictFunctionTypes": true,
6
    "strictBindCallApply": true,
7
    "strictPropertyInitialization": true,
8
    "noImplicitAny": true,
9
    "noImplicitThis": true,
10
    "alwaysStrict": true,
11
    "noUnusedLocals": true,
12
    "noUnusedParameters": true,
13
    "noImplicitReturns": true,
14
    "noFallthroughCasesInSwitch": true,
15
    "noUncheckedIndexedAccess": true,
16
    "exactOptionalPropertyTypes": true
17
  }
18
}

1
{
2
  "compilerOptions": {
3
    "incremental": true,
4
    "skipLibCheck": true,
5
    "assumeChangesOnlyAffectDirectDependencies": true,
6
    "tsBuildInfoFile": ".tsbuildinfo"
7
  }
8
}

1
{
2
  "compilerOptions": {
3
    "module": "NodeNext",
4
    "moduleResolution": "NodeNext",
5
    "esModuleInterop": true,
6
    "allowSyntheticDefaultImports": true,
7
    "resolveJsonModule": true
8
  }
9
}

1
// 根目录 tsconfig.json
2
{
3
  "references": [
4
    { "path": "./src/shared" },
5
    { "path": "./src/backend" },
6
    { "path": "./src/frontend" }
7
  ],
8
  "compilerOptions": {
9
    "composite": true
10
  }
11
}
12

13
// src/shared/tsconfig.json
14
{
15
  "compilerOptions": {
16
    "composite": true,
17
    "declaration": true,
18
    "declarationMap": true,
19
    "sourceMap": true,
20
    "outDir": "./dist"
21
  }
22
}

1
{
2
  "compilerOptions": {
3
    "incremental": true,
4
    "tsBuildInfoFile": "./.tsbuildinfo",
5
    "assumeChangesOnlyAffectDirectDependencies": true
6
  },
7
  "watchOptions": {
8
    "watchFile": "useFsEvents",
9
    "watchDirectory": "useFsEvents",
10
    "synchronousWatchDirectory": true,
11
    "excludeDirectories": ["**/node_modules", "**/dist"],
12
    "excludeFiles": ["*.js", "*.d.ts"]
13
  }
14
}

1
{
2
  "compilerOptions": {
3
    "include": ["src/**/*"],
4
    "exclude": [
5
      "node_modules",
6
      "dist",
7
      "**/*.test.ts",
8
      "**/*.spec.ts"
9
    ]
10
  }
11
}

1
{
2
  "compilerOptions": {
3
    "isolatedModules": true,
4
    "verbatimModuleSyntax": true
5
  }
6
}

1
// 避免：过度复杂的类型推断
2
type DeepNested = {
3
  a: {
4
    b: {
5
      c: {
6
        d: {
7
          e: string
8
        }
9
      }
10
    }
11
  }
12
};
13

14
// 推荐：在合理位置使用 any
15
type DeepNested = {
16
  a: {
17
    b: {
18
      c: any // 编译器停止推断
19
    }
20
  }
21
};

1
// 避免：重复计算复杂类型
2
type Compute1 = ComplexType<Param1>;
3
type Compute2 = ComplexType<Param1>; // 重复计算
4

5
// 推荐：使用中间类型
6
type Intermediate = ComplexType<Param1>;
7
type Use1 = Intermediate;
8
type Use2 = Intermediate;

1
{
2
  "compilerOptions": {
3
    "experimentalDecorators": false  // TS 5.x不需要
4
  }
5
}

1
// 检查类型兼容性
2
const obj = {
3
  a: 1,
4
  b: 'string'
5
} satisfies Record<string, string>; // Error: number不兼容string
6

7
// 修改目标类型或表达式
8
const obj2 = {
9
  a: '1',
10
  b: 'string'
11
} satisfies Record<string, string>; // OK

1
// 使用satisfies保留具体类型
2
const config = {
3
  timeout: 5000
4
} satisfies { timeout: number };
5

6
config.timeout; // 5000而非number

1
function decorator(value: any, context: any) {
2
  if (context.access.has) {
3
    // 通过access访问
4
  }
5
}