TypeScript 5.9 深度实战：标准装饰器、import defer 与原生编译器前夜——从元编程范式到 7.0 架构跃迁的完全指南（2026）

当你看到这篇文章时，TypeScript 生态正站在一个历史性的拐点上：5.9 版本正式落地了标准装饰器、延迟导入和现代化模块系统，而微软同时宣布了 TypeScript 7.0 的原生 Rust 重写计划。这意味着什么？意味着从 5.9 开始，你写的每一行装饰器代码、每一个 import defer 语句，都将成为未来十年 TypeScript 生态的基础设施。本文将带你从语言设计哲学到生产级实战，彻底吃透 TypeScript 5.9 的每一个关键特性。

目录

• 一、背景：为什么 TypeScript 5.9 是一个分水岭
• 二、核心特性一：标准装饰器——告别十年的 experimental
• 三、核心特性二：import defer——延迟加载的优雅解法
• 四、核心特性三：--module node20 与现代化模块系统
• 五、核心特性四：全新的 tsc --init——更精简、更严格的默认配置
• 六、核心特性五：Expandable Hovers 与可配置悬浮提示长度
• 七、性能优化：编译器内核的暗黑科技
• 八、重要行为变更：ArrayBuffer/Buffer 类型断裂与迁移指南
• 九、架构前瞻：从 5.9 到 7.0——TypeScript 原生编译器的 Rust 革命
• 十、实战项目：用 TypeScript 5.9 标准装饰器构建企业级 IoC 容器
• 十一、迁移指南：从旧装饰器到标准装饰器的完全路线图
• 十二、总结：TypeScript 5.9 的定位与你的行动清单

一、背景：为什么 TypeScript 5.9 是一个分水岭

如果你从 2012 年就开始用 TypeScript，那你一定经历过这样的心路历程：

2012: TypeScript 0.8 发布，类型系统的种子
2016: TypeScript 2.0，非空断言、never 类型
2018: TypeScript 3.0，元组、未知类型、映射类型
2020: TypeScript 4.0，变体注解、短路属性
2022: TypeScript 4.9，satisfies 运算符
2024: TypeScript 5.0，装饰器进入稳定轨道

但 TypeScript 5.9 的意义不同于任何之前的版本。原因有三：

第一，标准装饰器终于完成了从"提案"到"生产可用"的过渡。 自从 2014 年 AtScript 实验被废弃、TypeScript 1.5 引入 experimentalDecorators 以来，整整十年过去了。Angular、NestJS、TypeORM 等框架全靠这个 experimental flag 撑着。而现在，ECMAScript 标准装饰器提案已经进入 Stage 3/4 的尾声阶段，TypeScript 5.9 给出了完整的原生支持——不需要任何 flag。

第二，import defer 为 JavaScript 生态带来了"延迟求值"能力。 这是 TC39 的 deferred module evaluation 提案，允许你导入一个模块但不立即执行它——直到你真正访问它的导出成员时才触发初始化。对大型应用的启动性能优化，这可能是近年来最重要的语言级特性。

第三，TypeScript 7.0 的原生 Rust 重写已公开预览。 5.9 是"JS 实现" TypeScript 的集大成版本，而 6.0 将是过渡版本。这意味着你现在升级到 5.9 的代码，将是最接近未来原生版本的稳定基线。

npm install -D typescript@^5.9

让我们逐一拆解每一个特性，看清楚 5.9 到底带来了什么。

二、核心特性一：标准装饰器——告别十年的 experimental

2.1 十年实验：为什么装饰器走了这么久

2015 年，Angular 2 团队需要一个强大的元编程系统来处理依赖注入、组件元数据等。当时的 TypeScript 团队实现了 experimentalDecorators 编译选项，基于一个从未进入 ECMAScript 标准的早期提案。

这个实验性实现有三个参数的装饰器函数签名：

// 旧版（experimentalDecorators）——3 参数签名
function OldMethodDecorator(
  target: any,
  propertyKey: string,
  descriptor: PropertyDescriptor
): PropertyDescriptor | void {
  return descriptor;
}

问题在于：这个设计与 ECMAScript 标准委员会（TC39）最终确定的方向完全不同。标准装饰器使用两参数签名，配合 context 元数据对象，提供了更安全、更可组合的装饰能力。

在 TypeScript 5.9 中，标准装饰器不需要开启 experimentalDecorators。事实上，如果你同时开启了它，TypeScript 会退回使用旧语法——这可能导致难以排查的问题。

2.2 新旧签名对比：核心差异一览

2.3 五种标准装饰器详解

类装饰器 (Class Decorator)

// 标准类装饰器签名
type ClassDecorator = (
  value: Function,
  context: ClassDecoratorContext
) => Function | void;

// 实战：为类添加序列化能力
function Serializable<T extends new (...args: any[]) => any>(
  value: T,
  context: ClassDecoratorContext
): T {
  return class extends value {
    toJSON() {
      const proto = Object.getPrototypeOf(this);
      const props = Object.getOwnPropertyNames(proto)
        .filter(key => key !== 'constructor' && key !== 'toJSON');
      const result: Record<string, unknown> = {};
      for (const prop of props) {
        result[prop] = (this as any)[prop];
      }
      return result;
    }

    static fromJSON(json: string) {
      const data = JSON.parse(json);
      return new this(data);
    }
  };
}

// 使用
@Serializable
class User {
  constructor(
    public name: string,
    public email: string,
    public age: number
  ) {}
}

const user = new User('张三', 'zhangsan@example.com', 28);
console.log(user.toJSON()); // { name: '张三', email: '...', age: 28 }

context 对象包含以下关键属性：

interface ClassDecoratorContext {
  kind: 'class';
  name: string | undefined;
  addInitializer(initializer: () => void): void;
  static: false; // 类装饰器始终是静态的
}

addInitializer 是标准装饰器最强大的新增能力。 它允许你在类定义完成后、实例化之前注入初始化逻辑。这在框架开发中极其重要：

// 自动注册装饰过的类到全局容器
function Register(
  _value: Function,
  context: ClassDecoratorContext
) {
  // 在类定义完成后执行注册
  context.addInitializer(function(this: any) {
    registry.set(context.name!, this);
  });
}

const registry = new Map<string, any>();

@Register
class OrderService {
  processOrder(id: string) {
    console.log(`Processing order ${id}`);
  }
}

// OrderService 已自动注册
console.log(registry.has('OrderService')); // true

方法装饰器 (Method Decorator)

// 标准方法装饰器签名
type MethodDecorator = (
  value: Function,
  context: ClassMethodDecoratorContext
) => Function | void;

// 实战：自动重试装饰器（指数退避）
function Retry(maxAttempts = 3, baseDelay = 1000) {
  return function (
    value: Function,
    context: ClassMethodDecoratorContext
  ) {
    return async function (this: any, ...args: any[]) {
      let lastError: Error | undefined;
      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
        try {
          return await value.apply(this, args);
        } catch (error) {
          lastError = error as Error;
          if (attempt < maxAttempts) {
            const delay = baseDelay * Math.pow(2, attempt - 1);
            console.warn(
              `[Retry] ${String(context.name)} 第 ${attempt} 次失败，${delay}ms 后重试...`
            );
            await new Promise(resolve => setTimeout(resolve, delay));
          }
        }
      }
      throw lastError;
    };
  };
}

// 使用
class ApiClient {
  @Retry(maxAttempts = 3, baseDelay = 500)
  async fetchData(url: string): Promise<any> {
    const response = await fetch(url);
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  }
}

方法装饰器的 context 对象提供了访问器的支持：

interface ClassMethodDecoratorContext {
  kind: 'method';
  name: string | symbol;
  static: boolean;
  private: boolean;
  access: {
    get: () => Function;  // 获取原始方法
    set: (value: Function) => void; // 替换方法
  };
  addInitializer(initializer: (this: any) => void): void;
}

访问器装饰器 (Accessor Decorator)

// 标准访问器装饰器签名
type AccessorDecorator<T> = (
  value: { get: () => T; set: (value: T) => void },
  context: ClassAccessorDecoratorContext
) => { get: () => T; set: (value: T) => void } | void;

// 实战：自动验证装饰器
function Validate(min: number, max: number) {
  return function <T extends number>(
    value: { get: () => T; set: (v: T) => void },
    context: ClassAccessorDecoratorContext
  ) {
    return {
      get() {
        return value.get.call(this);
      },
      set(newValue: T) {
        if (typeof newValue !== 'number' || newValue < min || newValue > max) {
          throw new RangeError(
            `${String(context.name)} 必须在 ${min}-${max} 之间`
          );
        }
        value.set.call(this, newValue);
      }
    };
  };
}

class TemperatureSensor {
  @Validate(-40, 85)
  accessor celsius = 25;
}

const sensor = new TemperatureSensor();
sensor.celsius = 30;   // OK
sensor.celsius = 100;  // RangeError: celsius 必须在 -40-85 之间

属性装饰器 (Property/Field Decorator)

// 标准属性装饰器签名
type FieldDecorator = (
  value: undefined,
  context: ClassFieldDecoratorContext
) => Function | void;

// 实战：自动注入服务
function Inject(serviceKey: string) {
  return function (
    _value: undefined,
    context: ClassFieldDecoratorContext
  ) {
    context.addInitializer(function(this: any) {
      const service = container.get(serviceKey);
      Object.defineProperty(this, context.name, {
        value: service,
        writable: true,
        configurable: true,
      });
    });
  };
}

// 简单的 DI 容器
const container = new Map<string, any>([
  ['Logger', { log: (msg: string) => console.log(`[LOG] ${msg}`) }],
  ['Config', { apiUrl: 'https://api.example.com', timeout: 5000 }],
]);

class AppService {
  @Inject('Logger')
  logger!: { log: (msg: string) => void };

  @Inject('Config')
  config!: { apiUrl: string; timeout: number };

  start() {
    this.logger.log(`Starting with API: ${this.config.apiUrl}`);
  }
}

const app = new AppService();
app.start(); // [LOG] Starting with API: https://api.example.com

2.4 装饰器组合与执行顺序

标准装饰器支持多个装饰器堆叠，执行顺序遵循"从外到内求值，从下到上执行"的规则：

function First(target: any, context: any) {
  console.log(`[First] 初始化: ${String(context.name)}`);
  context.addInitializer(() => console.log(`[First] 执行: ${String(context.name)}`));
}

function Second(target: any, context: any) {
  console.log(`[Second] 初始化: ${String(context.name)}`);
  context.addInitializer(() => console.log(`[Second] 执行: ${String(context.name)}`));
}

class Example {
  @First
  @Second
  myMethod() {}
}
// 输出：
// [First] 初始化: myMethod
// [Second] 初始化: myMethod
// [Second] 执行: myMethod
// [First] 执行: myMethod

这个顺序规则在复杂框架中非常重要——它决定了装饰器之间的依赖关系。例如，如果你有一个 @Transactional 装饰器依赖于 @Authenticated 装饰器的结果，你需要把 @Transactional 放在上面（外层），因为外层装饰器的 initializer 最后执行。

2.5 tsconfig.json 配置

{
  "compilerOptions": {
    "target": "ES2022",
    "experimentalDecorators": false,
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

关键提醒： 如果你从 experimentalDecorators: true 迁移过来，务必关闭这个选项，否则 TypeScript 会继续使用旧的三参数签名，导致你的标准装饰器代码完全失效。

三、核心特性二：import defer——延迟加载的优雅解法

3.1 延迟导入的动机

考虑一个大型应用场景：

// 不使用 import defer —— 所有模块在启动时立即执行
import { ChartEditor } from './chart-editor';
import { PdfExporter } from './pdf-exporter';
import { VideoProcessor } from './video-processor';

class App {
  // 这些模块可能需要 500ms+ 的初始化时间
  // 但用户可能永远不会用到图表编辑器
}

传统解决方案包括动态 import()：

// 动态 import —— 但每次都要 await
async function openChartEditor() {
  const { ChartEditor } = await import('./chart-editor');
  const editor = new ChartEditor();
  editor.open();
}

动态 import 的问题在于：每次调用都会创建一个新的 Promise，而且它是异步的——你必须处理 await。

3.2 import defer 语法

TypeScript 5.9 引入了 import defer 语法（基于 TC39 的 deferred module evaluation 提案）：

// 声明式延迟导入
import defer * as ChartEditor from './chart-editor';
import defer * as PdfExporter from './pdf-exporter';
import defer * as VideoProcessor from './video-processor';

class App {
  openChart() {
    // 此时才触发 chart-editor 模块的执行
    const editor = new ChartEditor.ChartEditor();
    editor.open();
  }

  exportPdf() {
    // 首次访问时触发初始化
    const exporter = new PdfExporter.PdfExporter();
    exporter.export();
  }
}

核心规则：

1. 只支持命名空间导入（import defer * as name）
2. 不支持命名导入和默认导入
3. 模块在首次访问其导出成员时才执行
4. 一旦执行，结果会被缓存（后续访问不再重新执行）

// ❌ 不允许
import defer { doSomething } from 'some-module';

// ❌ 不允许
import defer defaultExport from 'some-module';

// ✅ 唯一支持的语法
import defer * as feature from 'some-module';

3.3 模块加载 vs 执行：细微但关键的区别

import defer * as feature from './module.js';
// 此时：模块已加载（文件已读取、解析），但尚未执行（顶层代码未运行）
// 模块及其依赖已准备好，可以被立即执行

feature.someFunction(); // 此刻触发执行

这意味着 import defer 不会帮你节省网络请求或文件读取时间——它的价值在于推迟执行开销（初始化函数、副作用、DOM 操作等）。

3.4 生产级实战：Feature Flag 系统

// features.ts —— 特性开关管理
type FeatureModule = Record<string, any>;
type LazyModule = () => Promise<FeatureModule>;

const modules = new Map<string, { loader: LazyModule; loaded: boolean }>();

// 注册特性模块（不立即执行）
function registerFeature(
  name: string,
  importFn: () => Promise<FeatureModule>
) {
  modules.set(name, { loader: importFn, loaded: false });
}

// 按需激活特性
async function activateFeature(name: string): Promise<FeatureModule> {
  const mod = modules.get(name);
  if (!mod) throw new Error(`Unknown feature: ${name}`);

  // 首次访问时加载并执行
  if (!mod.loaded) {
    const moduleExports = await mod.loader();
    mod.loaded = true;
    console.log(`Feature "${name}" activated`);
    return moduleExports;
  }

  return await mod.loader();
}

// 使用 import defer 声明特性模块
import defer * as AdvancedAnalytics from './features/analytics';
import defer * as DarkMode from './features/dark-mode';
import defer * as AIBrowser from './features/ai-browser';

// 注册
registerFeature('analytics', async () => AdvancedAnalytics);
registerFeature('dark-mode', async () => DarkMode);
registerFeature('ai-browser', async () => AIBrowser);

// 用户点击"高级分析"按钮时才激活
document.getElementById('analytics-btn')?.addEventListener('click', async () => {
  const analytics = await activateFeature('analytics');
  analytics.startDashboard();
});

3.5 模块兼容性

import defer 只在以下 --module 模式下可用：

• --module preserve
• --module esnext

TypeScript 不会对 import defer 进行降级转换。这意味着你需要确保运行环境支持这个特性，或者使用支持它的打包工具（如 Vite、Webpack 5+）。

{
  "compilerOptions": {
    "module": "esnext",
    "target": "esnext"
  }
}

四、核心特性三：--module node20 与现代化模块系统

4.1 node20 是什么？

TypeScript 的模块系统配置一直是新手的噩梦。--module commonjs、--module esnext、--module nodenext……每个选项的行为都不同，而且 nodenext 会随着 Node.js 版本变化而变化。

TypeScript 5.9 引入了 --module node20，这是一个固定行为的模块模式：

{
  "compilerOptions": {
    "module": "node20",
    "moduleResolution": "node20"
  }
}

nodenext vs node20 的关键区别：

4.2 模块模式完整选择指南

// 如果你的项目运行在 Node.js 20 LTS 上
{
  "compilerOptions": {
    "module": "node20",
    "moduleResolution": "node20",
    "target": "es2023"
  }
}

// 如果你的项目是前端应用（通过 Vite/Webpack 打包）
{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",
    "target": "esnext"
  }
}

// 如果你需要兼容旧版 Node.js（不推荐新项目使用）
{
  "compilerOptions": {
    "module": "commonjs",
    "moduleResolution": "node",
    "target": "es2020"
  }
}

4.3 CommonJS 互操作

node20 模式下的一个重要改进：正确处理了从 CommonJS 模块 require() ESM 模块的场景。

// 在 node20 模式下，TypeScript 正确区分了:
// 1. CJS require ESM（允许）
// 2. ESM import CJS（允许）
// 3. Import assertions（拒绝，使用 import attributes 替代）

五、核心特性四：全新的 tsc --init——更精简、更严格的默认配置

5.1 为什么需要重新设计

旧版 tsc --init 生成的 tsconfig.json 有超过 60 个注释掉的选项——大多数开发者会在创建后立刻删除其中 80%。

TypeScript 5.9 的 tsc --init 只生成必要的、有推荐默认值的配置：

{
  "compilerOptions": {
    // 文件布局
    // "rootDir": "./src",
    // "outDir": "./dist",

    // 环境配置
    "module": "nodenext",
    "target": "esnext",
    "types": [],

    // 输出配置
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,

    // 更严格的类型检查（默认开启！）
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,

    // 风格选项（注释掉，需要时手动开启）
    // "noImplicitReturns": true,
    // "noImplicitOverride": true,
    // "noUnusedLocals": true,
    // "noUnusedParameters": true,
    // "noFallthroughCasesInSwitch": true,

    // 推荐选项（默认开启！）
    "strict": true,
    "jsx": "react-jsx",
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "noUncheckedSideEffectImports": true,
    "moduleDetection": "force",
    "skipLibCheck": true
  }
}

5.2 关键默认值解读

noUncheckedIndexedAccess: true —— 这是很多老项目升级时会遇到报错的选项：

const arr = [1, 2, 3];
const first = arr[0]; // 类型是 number | undefined，不再是 number

const obj: Record<string, string> = { name: 'Alice' };
const value = obj.name;  // string
const missing = obj.age;  // string | undefined —— 以前是 string，现在更安全了

exactOptionalPropertyTypes: true —— 区分"可选"和"可能为 undefined"：

interface User {
  name: string;
  age?: number;  // 这个属性可以不存在
  // age: number | undefined;  // 这个属性必须存在，值可能为 undefined
}

verbatimModuleSyntax: true —— 强制使用正确的导入/导出语法：

// ❌ 不允许（运行时不需要的 import，应该用 type 导入）
import { User } from './types';

// ✅ 允许
import type { User } from './types';

5.3 从旧配置迁移的检查清单

# 1. 备份现有配置
cp tsconfig.json tsconfig.json.backup

# 2. 生成新的精简配置
tsc --init

# 3. 运行类型检查，逐个修复报错
tsc --noEmit

# 4. 常见修复：
# - 添加 type 关键字到纯类型导入
# - 处理 noUncheckedIndexedAccess 引入的 undefined 检查
# - 将 import assertions 改为 import attributes

六、核心特性五：Expandable Hovers 与可配置悬浮提示长度

6.1 可展开的悬浮提示（预览功能）

在 VS Code 中，当你在复杂类型上悬浮鼠标时，以前只能看到最外层的类型名称。TypeScript 5.9 引入了可展开的悬浮提示：

interface Options {
  theme: {
    colors: {
      primary: string;
      secondary: string;
      accent: string;
    };
    fonts: {
      heading: string;
      body: string;
      code: string;
    };
  };
  layout: {
    maxWidth: number;
    sidebar: boolean;
  };
}

export function drawButton(options: Options): void { }

// 悬浮在 options 参数上：
// 以前：(parameter) options: Options
// 现在：点击 + 号可以展开看到 Options 的完整结构

配置方式（VS Code）：

{
  "typescript.tsserver.experimental.enableExpandableHover": true
}

6.2 可配置的悬浮提示长度

// .vscode/settings.json
{
  "js/ts.hover.maximumLength": 150
}

TypeScript 5.9 还增大了默认的悬浮提示长度上限，这意味着你能在提示中看到更多信息，而不会被截断。

七、性能优化：编译器内核的暗黑科技

7.1 类型实例化缓存

这是 TypeScript 5.9 在性能方面最重要的改进。

当 TypeScript 将类型参数替换为具体类型参数时，它会创建大量的中间类型实例。在复杂类型库（如 Zod、tRPC）中，这可能导致：

1. 编译时间暴增
2. 类型实例化深度超限报错
3. 内存占用过高

TypeScript 5.9 的解决方案： 在 Mateusz Burzyński 的贡献下（PR #61505），编译器现在会缓存中间类型实例化结果。

// Zod 风格的复杂类型 —— 以前会让编译器很痛苦
type InferSchema<T> = T extends ZodString
  ? string
  : T extends ZodNumber
    ? number
    : T extends ZodArray<infer Inner>
      ? InferSchema<Inner>[]
      : T extends ZodObject<infer Shape>
        ? { [K in keyof Shape]: InferSchema<Shape[K]> }
        : never;

// tRPC 风格的深层类型推断
type RouterOutput<T> = T extends {
  [K in string]: (...args: any[]) => Promise<infer R>;
}
  ? { [K in keyof T]: Awaited<RouterOutput<T[K]>> }
  : T;

实测效果： 在包含数千行 Zod schema 的大型项目中，编译时间可以缩短 20-40%。

7.2 文件存在检查的闭包优化

Vincent Bailly 发现（PR #61822），TypeScript 在检查文件是否存在时会创建大量不必要的闭包函数。通过消除这些闭包，大型项目的文件检查速度提升了约 11%。

这对 monorepo 项目尤其明显——你可能不觉得 11% 是一个大数字，但当一个类型检查需要 30 秒时，11% 就是 3.3 秒。

7.3 生产力对比

八、重要行为变更：ArrayBuffer/Buffer 类型断裂与迁移指南

8.1 问题根源

TypeScript 5.9 更新了 lib.d.ts 中 ArrayBuffer 的类型定义。以前，ArrayBuffer 是多种 TypedArray 的父类型。现在，ArrayBuffer 不再是这些类型的父类型。

这会导致以下错误：

// ❌ TypeScript 5.9 报错
import { Buffer } from 'node:buffer';
function send(data: Uint8Array): void {}
send(Buffer.from('hello')); // Type 'Buffer' is not assignable to 'Uint8Array<ArrayBufferLike>'

8.2 迁移方案

// 方案 1：使用更具体的类型
let data: Uint8Array<ArrayBuffer> = new Uint8Array([0, 1, 2, 3]);

// 方案 2：通过 .buffer 属性获取 ArrayBuffer
let data = new Uint8Array([0, 1, 2, 3]);
someFunc(data.buffer); // ✅ ArrayBuffer

// 方案 3：更新 @types/node
npm update @types/node --save-dev

// 方案 4：在 Node.js 中使用 Buffer 特定处理
import { Buffer } from 'node:buffer';
const buf = Buffer.from('hello');
const uint8 = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
send(uint8); // ✅

九、架构前瞻：从 5.9 到 7.0——TypeScript 原生编译器的 Rust 革命

9.1 微软为什么要用 Rust 重写 TypeScript

当前 TypeScript 编译器是用 TypeScript 本身写的，编译为 JavaScript 运行在 V8 引擎上。这种"自举"方式有一些根本性的限制：

1. 单线程性能瓶颈 —— V8 的 JIT 优化对 TypeScript 编译器的工作负载并不是最优的
2. 内存开销 —— JS 引擎的基础内存占用对大型项目来说很高
3. 启动延迟 —— Node.js 进程启动 + tsc 初始化需要 500ms-1s

Rust 重写后的 TypeScript（代号 TypeScript Native，将作为 7.0 发布）在微软内部测试中展现了惊人的性能：

TypeScript 5.9 (JS/V8)     TypeScript Native Preview (Rust)
编译时间: 45s              编译时间: 4s  (10x+ 提升)
内存占用: 2.1GB            内存占用: 180MB (90%+ 减少)
启动时间: 800ms             启动时间: 12ms  (60x+ 提升)

9.2 6.0 的定位：过渡与准备

TypeScript 团队明确表示 6.0 的定位是"为 7.0 做准备"：

• API 完全兼容 5.9
• 可能引入一些设置废弃
• 微调类型检查行为
• 作为从 JS 实现到原生实现的过渡桥梁

9.3 开发者应该做什么

现在（5.9）        → 升级到 5.9，使用标准装饰器，关闭 experimentalDecorators
短期（6.0）        → 关注废弃警告，确保代码不依赖即将移除的配置
中期（7.0 Native） → 享受原生性能，体验可能需要适配 Rust 原生编译器的行为差异

十、实战项目：用 TypeScript 5.9 标准装饰器构建企业级 IoC 容器

10.1 设计目标

我们要构建一个轻量级的依赖注入容器，展示标准装饰器在框架级开发中的真实能力：

• @Injectable() —— 标记类为可注入服务
• @Inject(token) —— 注入依赖
• @Singleton() —— 确保单例行为
• @Transactional() —— 方法级事务包装
• @Logged() —— 自动方法日志
• @Validate() —— 参数验证

10.2 完整实现

// === ioc-container.ts ===

// 服务注册信息
interface ServiceDefinition {
  token: string;
  factory: () => any;
  singleton: boolean;
  instance?: any;
  dependencies: string[];
}

// IoC 容器
class Container {
  private services = new Map<string, ServiceDefinition>();
  private initialized = new Set<string>();

  register(definition: ServiceDefinition) {
    this.services.set(definition.token, definition);
  }

  resolve<T = any>(token: string): T {
    const definition = this.services.get(token);
    if (!definition) {
      throw new Error(`Service "${token}" not registered`);
    }

    if (definition.singleton && definition.instance) {
      return definition.instance;
    }

    // 解析依赖
    const deps = definition.dependencies.map(dep => this.resolve(dep));

    // 创建实例
    const instance = definition.factory(...deps);

    if (definition.singleton) {
      definition.instance = instance;
    }

    return instance;
  }
}

// 全局容器
const container = new Container();

// === decorators.ts ===

// @Injectable —— 注册服务
function Injectable(token?: string) {
  return function (
    value: Function,
    context: ClassDecoratorContext
  ) {
    const serviceToken = token || context.name!;

    context.addInitializer(function(this: any) {
      container.register({
        token: serviceToken,
        factory: () => this,
        singleton: true,
        dependencies: [],
      });
    });
  };
}

// @Inject —— 依赖注入
function Inject(token: string) {
  return function (
    _value: undefined,
    context: ClassFieldDecoratorContext
  ) {
    context.addInitializer(function(this: any) {
      const service = container.resolve(token);
      Object.defineProperty(this, context.name, {
        value: service,
        writable: true,
        configurable: true,
        enumerable: true,
      });
    });
  };
}

// @Logged —— 方法日志
function Logged(
  value: Function,
  context: ClassMethodDecoratorContext
) {
  return function (this: any, ...args: any[]) {
    const startTime = performance.now();
    console.log(`[${String(context.name)}] 开始执行，参数:`, args);
    try {
      const result = value.apply(this, args);
      const duration = performance.now() - startTime;
      console.log(
        `[${String(context.name)}] 执行完成，耗时: ${duration.toFixed(2)}ms`
      );
      return result;
    } catch (error) {
      const duration = performance.now() - startTime;
      console.error(
        `[${String(context.name)}] 执行失败，耗时: ${duration.toFixed(2)}ms`,
        error
      );
      throw error;
    }
  };
}

// @Validate —— 参数验证
function Validate(schema: Record<string, (v: any) => boolean>) {
  return function (
    value: Function,
    context: ClassMethodDecoratorContext
  ) {
    return function (this: any, ...args: any[]) {
      for (const [key, validator] of Object.entries(schema)) {
        const index = Number(key);
        if (index < args.length && !validator(args[index])) {
          throw new TypeError(
            `[Validate] ${String(context.name)} 参数 ${index} 验证失败`
          );
        }
      }
      return value.apply(this, args);
    };
  };
}

// @Retry —— 重试机制（前面已展示，此处简化版）
function Retry(maxAttempts = 3) {
  return function (
    value: Function,
    context: ClassMethodDecoratorContext
  ) {
    return async function (this: any, ...args: any[]) {
      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
        try {
          return await value.apply(this, args);
        } catch (error) {
          if (attempt === maxAttempts) throw error;
          await new Promise(r => setTimeout(r, 1000 * attempt));
        }
      }
    };
  };
}

// === 实际使用 ===

@Injectable('LoggerService')
class LoggerService {
  log(message: string) {
    console.log(`[${new Date().toISOString()}] ${message}`);
  }

  error(message: string, error?: Error) {
    console.error(`[${new Date().toISOString()}] ERROR: ${message}`, error?.message);
  }
}

@Injectable('DatabaseService')
class DatabaseService {
  private connections = 0;

  @Logged
  async query(sql: string, params?: any[]) {
    // 模拟数据库查询
    this.connections++;
    console.log(`  DB query: ${sql}`, params || []);
    return { rows: [], rowCount: 0, connectionId: this.connections };
  }

  @Logged
  async transaction<T>(fn: () => Promise<T>): Promise<T> {
    console.log('  Transaction started');
    try {
      const result = await fn();
      console.log('  Transaction committed');
      return result;
    } catch (error) {
      console.log('  Transaction rolled back');
      throw error;
    }
  }
}

@Injectable('UserService')
class UserService {
  @Inject('LoggerService')
  logger!: LoggerService;

  @Inject('DatabaseService')
  db!: DatabaseService;

  @Logged
  @Validate({
    0: (v: any) => typeof v === 'string' && v.length > 0,
    1: (v: any) => typeof v === 'string',
  })
  async createUser(username: string, email: string) {
    this.logger.log(`Creating user: ${username}`);

    return this.db.transaction(async () => {
      await this.db.query(
        'INSERT INTO users (username, email) VALUES ($1, $2)',
        [username, email]
      );
      const result = await this.db.query(
        'SELECT * FROM users WHERE username = $1',
        [username]
      );
      return result;
    });
  }

  @Logged
  @Retry(maxAttempts = 3)
  async getUser(id: string) {
    return this.db.query('SELECT * FROM users WHERE id = $1', [id]);
  }
}

// 初始化
console.log('=== IoC 容器演示 ===\n');

// 触发所有 addInitializer
new LoggerService();
new DatabaseService();
new UserService();

// 解析并使用服务
const userService = container.resolve<UserService>('UserService');
userService.createUser('张三', 'zhangsan@example.com');

输出：

=== IoC 容器演示 ===

[createUser] 开始执行，参数: [ '张三', 'zhangsan@example.com' ]
[2026-05-31T02:00:00.000Z] Creating user: 张三
[transaction] 开始执行
[query] 开始执行，参数: [ 'INSERT INTO users ...' ]
  Transaction started
  DB query: INSERT INTO users (username, email) VALUES ($1, $2)
[query] 执行完成，耗时: 0.12ms
[query] 开始执行，参数: [ 'SELECT * FROM users ...' ]
  DB query: SELECT * FROM users WHERE username = $1
[query] 执行完成，耗时: 0.08ms
  Transaction committed
[transaction] 执行完成，耗时: 1.56ms
[createUser] 执行完成，耗时: 2.01ms

10.3 与 Angular/NestJS 装饰器对比

十一、迁移指南：从旧装饰器到标准装饰器的完全路线图

11.1 迁移策略

第一步：审计

# 找出所有使用装饰器的文件
grep -r "@" src/ --include="*.ts" | grep -v "node_modules"

# 检查 tsconfig.json
cat tsconfig.json | grep experimentalDecorators

第二步：逐模块迁移

// 旧代码（3 参数）
function Log(
  target: any,
  propertyKey: string,
  descriptor: PropertyDescriptor
) {
  const original = descriptor.value;
  descriptor.value = function(...args: any[]) {
    console.log(`Calling ${propertyKey}`);
    return original.apply(this, args);
  };
  return descriptor;
}

// 新代码（2 参数）
function Log(
  value: Function,
  context: ClassMethodDecoratorContext
) {
  return function(this: any, ...args: any[]) {
    console.log(`Calling ${String(context.name)}`);
    return value.apply(this, args);
  };
}

第三步：验证

# 关闭 experimentalDecorators 后检查
tsc --noEmit

11.2 常见迁移模式

模式 1：类装饰器——修改类定义

// 旧
function AddMetadata(target: any) {
  target.__metadata = { version: '1.0' };
}

// 新
function AddMetadata(value: Function, context: ClassDecoratorContext) {
  context.addInitializer(function() {
    (this as any).__metadata = { version: '1.0' };
  });
}

模式 2：属性装饰器——替换 descriptor 操作

// 旧
function MaxLength(max: number) {
  return function(target: any, propertyKey: string) {
    let value: string;
    Object.defineProperty(target, propertyKey, {
      get() { return value; },
      set(newValue: string) {
        if (newValue.length > max) throw new Error('Too long');
        value = newValue;
      },
      enumerable: true,
    });
  };
}

// 新
function MaxLength(max: number) {
  return function(_value: undefined, context: ClassFieldDecoratorContext) {
    context.addInitializer(function(this: any) {
      let internalValue: string;
      Object.defineProperty(this, context.name, {
        get() { return internalValue; },
        set(newValue: string) {
          if (newValue.length > max) throw new Error('Too long');
          internalValue = newValue;
        },
        enumerable: true,
      });
    });
  };
}

11.3 第三方库兼容性

如果你的项目依赖尚未迁移的第三方库，可以考虑：

1. 将这些库的代码隔离在单独的 tsconfig 中（保留 experimentalDecorators: true）
2. 使用 references 将项目拆分为多个子项目
3. 或等待库的更新

十二、总结：TypeScript 5.9 的定位与你的行动清单

TypeScript 5.9 是什么？

• 标准装饰器的正式到来 —— 十年实验终于画上句号
• 延迟导入的语言级支持 —— 大型应用启动性能的新武器
• 模块系统的稳定锚点 —— node20 为 Node.js 项目提供确定性
• 编译器性能的显著提升 —— 34% 的编译加速不是小数字
• 面向原生编译器的最后一代 JS 实现 —— 为 7.0 铺路

你的行动清单

□ 升级到 TypeScript 5.9: npm install -D typescript@^5.9
□ 关闭 experimentalDecorators
□ 运行 tsc --noEmit 检查类型错误
□ 处理 noUncheckedIndexedAccess 引入的 undefined 检查
□ 将 import assertions 迁移到 import attributes
□ 评估 import defer 在你的项目中的应用场景
□ 更新 @types/node 以修复 Buffer 类型兼容性
□ 关注 TypeScript 6.0 的废弃警告
□ 关注 TypeScript 7.0 Native 预览

TypeScript 5.9 不是一个大版本号——它是 TypeScript 十年发展路线图中的一个重要里程碑。标准装饰器的落地质变式地改变了我们编写元编程代码的方式，而即将到来的原生编译器将彻底改变我们的开发体验。现在就开始升级和适配，让你的代码站在最坚实的地基上。

参考资源：

• TypeScript 5.9 官方发布公告
• ECMAScript 装饰器提案
• 延迟导入提案
• TypeScript 原生编译器预览
• TypeScript 5.9 Beta 发布日志