TypeScript 装饰器：方法、类、字段与访问器装饰器

装饰器是一个用 @name 附加到类或类成员上的函数。它接收原始的方法（或类、字段）以及一个描述它的上下文对象，并且可以返回一个替代品。TypeScript 无需任何编译器开关就支持标准装饰器。

function logged<This, Args extends unknown[], Return>(
    method: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
    const name = String(context.name);
    return function (this: This, ...args: Args): Return {
        console.log(`-> ${name}(${args.join(", ")})`);
        const result = method.call(this, ...args);
        console.log(`<- ${name} = ${result}`);
        return result;
    };
}

class Calculator {
    @logged
    add(a: number, b: number): number {
        return a + b;
    }
}

new Calculator().add(2, 3);
// -> add(2, 3)
// <- add = 5

@logged 只在类定义时运行一次，用它返回的包装函数替换掉 add。之后每次调用都会经过这个包装函数。泛型参数保留了方法的 this、参数和返回值类型，所以 add 仍然接收两个数字并返回一个数字。

装饰器如何编译

标准装饰器来自 JavaScript 的一项 TC39 提案，TypeScript 从 5.0 版本起实现了它。这项提案还不是 JavaScript 标准的一部分，Node 24 也无法解析 @ 语法，所以当目标是 ES2022 时（本站页面就是如此），编译器会把每个被装饰的类改写成调用辅助函数的普通 JavaScript（辅助函数 __esDecorate 和 __runInitializers 会生成在文件顶部）。输出可以在任何支持 ES2022 的环境中运行。

由此带来一个后果：含有装饰器的文件无法在 Node 内置的类型剥离下运行（node file.ts），因为它只删除类型，会把 @ 原样留下。Node 会报 SyntaxError: Invalid or unexpected token 并停止。请先用 tsc 或打包工具编译。

装饰器的种类和签名

每个标准装饰器的形式都是 (value, context) => replacement | void。value 是什么、可以返回什么，取决于装饰的对象：

每个上下文对象都有 kind、name 和 addInitializer。类成员的上下文还有 static、private，以及一个用于从实例读取该成员的 access 对象。装饰器同样适用于静态成员和 #private 成员。

装饰器工厂

要传入选项，就写一个返回装饰器的函数，并在 @ 处调用它。这就是装饰器工厂：

function retry(times: number) {
    return function <This, Args extends unknown[], Return>(
        method: (this: This, ...args: Args) => Return,
        _context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
    ) {
        return function (this: This, ...args: Args): Return {
            for (let attempt = 1; ; attempt++) {
                try {
                    return method.call(this, ...args);
                } catch (e) {
                    if (attempt >= times) throw e;
                    console.log(`attempt ${attempt} failed, retrying`);
                }
            }
        };
    };
}

class Client {
    calls = 0;

    @retry(3)
    fetchData(): string {
        this.calls++;
        if (this.calls < 3) throw new Error("flaky");
        return `ok after ${this.calls} calls`;
    }
}

console.log(new Client().fetchData());

@retry(3) 会先调用 retry，它返回的函数才是真正的装饰器。多个装饰器可以叠加：在 @a @b method() 中，b 先被应用，a 再包装它的结果。

类装饰器与 addInitializer

类装饰器接收类本身。它可以返回一个子类来替换原来的类，也可以什么都不返回，只是在某处把它记录下来。context.addInitializer 注册一段在特定时刻运行的代码：对于类装饰器，是在类完全定义之后立即运行；对于方法装饰器，是在构造每个实例时运行。

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

function register(id: string) {
    return function <T extends new () => object>(target: T, context: ClassDecoratorContext<T>) {
        context.addInitializer(() => {
            registry.set(id, target);
        });
    };
}

// Binds a method to its instance, so it survives being passed as a callback.
function bound<This, Args extends unknown[], Return>(
    _method: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
    context.addInitializer(function (this: This) {
        const self = this as Record<string | symbol, unknown>;
        const fn = self[context.name] as (...a: unknown[]) => unknown;
        self[context.name] = fn.bind(this);
    });
}

@register("greeter")
class Greeter {
    name = "Ada";

    @bound
    greet(): string {
        return `Hello, ${this.name}`;
    }
}

const g = new Greeter();
const loose = g.greet; // detached from g
console.log(loose());  // Hello, Ada
console.log([...registry.keys()], registry.get("greeter") === Greeter); // [ 'greeter' ] true

类装饰器写在类的上方（或 export 之后）。如果没有 @bound，调用 loose() 会抛出错误，因为 this 会是 undefined。

字段装饰器与访问器装饰器

字段装饰器无法看到或拦截之后的赋值：它的 value 是 undefined，唯一能返回的是一个转换字段初始值的函数。要拦截读写，就用 accessor 关键字声明字段，它会把字段变成一对由私有存储支撑的 getter 和 setter，然后再装饰它：

function trimmed(_value: undefined, _context: ClassFieldDecoratorContext<unknown, string>) {
    return (initial: string) => initial.trim();
}

function positive<This>(
    target: ClassAccessorDecoratorTarget<This, number>,
    context: ClassAccessorDecoratorContext<This, number>,
): ClassAccessorDecoratorResult<This, number> {
    const check = (v: number) => {
        if (v <= 0) throw new RangeError(`${String(context.name)} must be positive, got ${v}`);
        return v;
    };
    return {
        init: check, // runs on the initial value
        set(v) {
            target.set.call(this, check(v));
        },
    };
}

class Product {
    @trimmed title = "  Lamp  ";
    @positive accessor price = 30;
}

const p = new Product();
console.log(`[${p.title}]`, p.price); // [Lamp] 30
p.price = 45;
console.log(p.price); // 45
try {
    p.price = -5;
} catch (e) {
    if (e instanceof Error) console.log(e.message); // price must be positive, got -5
}

accessor 属于同一项提案。它会在一个 #private 字段之上生成真正的 getter 和 setter，所以 p.price = -5 会经过装饰器的 set。

标准装饰器与旧版 experimentalDecorators

在 TypeScript 5.0 之前，TypeScript 唯一的装饰器是这项提案的早期版本，需要用 experimentalDecorators 开启。这个开关至今仍然存在，它会把编译器切换到旧版模型，签名和语义都不同：

为一种模型编写的装饰器在另一种模型下无法通过类型检查。下面是在没有开启该开关的项目中使用旧版风格的装饰器：

// This does not compile: a legacy decorator used as a standard one.
function log(target: object, key: string, descriptor: PropertyDescriptor) {
    const original = descriptor.value;
    descriptor.value = function (this: unknown, ...args: unknown[]) {
        console.log("calling", key);
        return original.apply(this, args);
    };
}

class Service {
    @log
    run(): string {
        return "done";
    }
}

console.log(new Service().run());

index.ts(11,5): error TS1241: Unable to resolve signature of method decorator when called as an expression.
  The runtime will invoke the decorator with 2 arguments, but the decorator expects 3.

修复方法有两种：一是像本页第一个示例那样，用标准的 (value, context) 形式重写它；二是为整个项目开启旧版模型：

{
    "compilerOptions": {
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true
    }
}

Angular、NestJS 和 TypeORM 生成的配置中仍然设置了 experimentalDecorators，它们的文档也要求这样做。NestJS 和 TypeORM 还需要 emitDecoratorMetadata，因为它们在运行时读取类型：NestJS 用它来注入构造函数参数，TypeORM 用它把属性映射到列：

// Legacy model: needs experimentalDecorators (and emitDecoratorMetadata for DI).
@Injectable()
class UsersService {
    constructor(@Inject(DB) private db: Database) {}
}

如果你在使用这些框架之一，就按旧版方式编写装饰器，并遵循框架的文档。对于不依赖这类框架的新代码，请使用标准装饰器。

何时使用装饰器

装饰器适合那些否则会在许多方法中重复出现的横切行为：日志、计时、缓存、重试、权限检查、校验，以及把类注册到容器或路由中。它们也会隐藏控制流，因为读代码的人得先查清 @retry 做了什么，才能知道这个方法做了什么。如果只用一两次，普通的高阶函数（const fetchData = retry(3, rawFetch)）更简单，而且在类之外也能用。