JavaScript Decorators 终于来了：Stage 3 装饰器完全指南

前言#

装饰器（Decorators）是 JavaScript 社区期待已久的特性。从最初的 Stage 0 提案到如今的 Stage 3，装饰器经历了多次重大改版。随着 TypeScript 5.0+ 原生支持 Stage 3 装饰器语法，以及各大打包工具的跟进，现在终于是全面拥抱装饰器的时候了。

本文将深入讲解 Stage 3 装饰器的完整语法、运行机制和实战用法，涵盖类装饰器、方法装饰器、访问器装饰器以及 metadata 元数据 API。

注意：本文讨论的是 TC39 Stage 3 提案的装饰器，与旧版实验性装饰器（TypeScript experimentalDecorators）有本质区别。

装饰器的本质：函数即变换#

装饰器的核心思想非常简单——它是一个函数，接收被装饰的目标，返回一个替换或增强后的版本。

1
// 最简单的装饰器：一个函数
2
function logged(value, context) {
3
  // value: 被装饰的值（类、方法、访问器等）
4
  // context: 包含装饰器上下文信息的对象
5
}

Stage 3 装饰器统一使用 (value, context) 双参数签名，其中 context 对象包含：

1
interface DecoratorContext {
2
  kind: 'class' | 'method' | 'getter' | 'setter' | 'field' | 'accessor';
3
  name: string | symbol;
4
  access?: { get?: () => unknown; set?: (value: unknown) => void };
5
  isStatic: boolean;
6
  isPrivate: boolean;
7
  addInitializer(initializer: () => void): void;
8
  metadata: Record<string | symbol, unknown>;
9
}

kind 字段决定了当前装饰的是什么类型的成员，不同类型的装饰器在返回值上有不同的语义。

类装饰器#

类装饰器是最直观的装饰器形式。它接收整个类作为参数，可以返回一个新的类来替换原始类。

基础用法#

1
function sealed(value, context) {
2
  if (context.kind === 'class') {
3
    Object.seal(value);
4
    Object.seal(value.prototype);
5
  }
6
}
7

8
@sealed
9
class User {
10
  name = 'default';
11
  greet() {
12
    return `Hello, ${this.name}`;
13
  }
14
}
15

16
// User 类及其原型现在被 seal 了
17
// User.newProp = 1; // TypeError in strict mode

类装饰器替换类#

类装饰器可以返回一个新类来替换原始类，这在需要注入额外逻辑时非常有用：

1
function withTimestamp(value, context) {
2
  if (context.kind !== 'class') return;
3

4
  return class extends value {
5
    createdAt = new Date();
6

7
    getAge() {
8
      return Date.now() - this.createdAt.getTime();
9
    }
10
  };
11
}
12

13
@withTimestamp
14
class Article {
15
  constructor(title) {
16
    this.title = title;
17
  }
18
}
19

20
const article = new Article('Decorators Guide');
21
console.log(article.createdAt); // 2026-04-05T...
22
console.log(article.title);     // "Decorators Guide"

使用 addInitializer 注册初始化逻辑#

addInitializer 允许你在类被定义后执行额外的初始化逻辑，而不需要替换整个类：

1
const registry = new Map();
2

3
function register(value, context) {
4
  if (context.kind === 'class') {
5
    context.addInitializer(function () {
6
      registry.set(context.name, value);
7
    });
8
  }
9
}
10

11
@register
12
class UserService {}
13

14
@register
15
class OrderService {}
16

17
console.log(registry.get('UserService'));  // [class UserService]
18
console.log(registry.get('OrderService')); // [class OrderService]

方法装饰器#

方法装饰器接收原始方法函数，可以返回一个新函数来替换它。这是装饰器最常用的场景之一。

日志装饰器#

1
function log(value, context) {
2
  if (context.kind !== 'method') return;
3

4
  return function (...args) {
5
    console.log(`[LOG] ${context.name}(${args.map(a => JSON.stringify(a)).join(', ')})`);
6
    const result = value.call(this, ...args);
7
    console.log(`[LOG] ${context.name} => ${JSON.stringify(result)}`);
8
    return result;
9
  };
10
}
11

12
class Calculator {
13
  @log
14
  add(a, b) {
15
    return a + b;
16
  }
17

18
  @log
19
  multiply(a, b) {
20
    return a * b;
21
  }
22
}
23

24
const calc = new Calculator();
25
calc.add(2, 3);
26
// [LOG] add(2, 3)
27
// [LOG] add => 5

防抖装饰器#

1
function debounce(delay) {
2
  return function (value, context) {
3
    if (context.kind !== 'method') return;
4

5
    let timer;
6
    return function (...args) {
7
      clearTimeout(timer);
8
      timer = setTimeout(() => {
9
        value.call(this, ...args);
10
      }, delay);
11
    };
12
  };
13
}
14

15
class SearchBox {
16
  @debounce(300)
17
  onInput(query) {
18
    console.log('Searching for:', query);
19
    // 实际的搜索逻辑
20
  }
21
}

注意这里使用了装饰器工厂模式——debounce(300) 返回真正的装饰器函数。这是参数化装饰器的标准写法。

缓存/记忆化装饰器#

1
function memoize(value, context) {
2
  if (context.kind !== 'method') return;
3

4
  const cache = new Map();
5

6
  return function (...args) {
7
    const key = JSON.stringify(args);
8
    if (cache.has(key)) {
9
      console.log(`[CACHE HIT] ${context.name}(${key})`);
10
      return cache.get(key);
11
    }
12
    const result = value.call(this, ...args);
13
    cache.set(key, result);
14
    return result;
15
  };
16
}
17

18
class MathUtils {
19
  @memoize
20
  fibonacci(n) {
21
    if (n <= 1) return n;
22
    return this.fibonacci(n - 1) + this.fibonacci(n - 2);
23
  }
24
}
25

26
const math = new MathUtils();
27
console.log(math.fibonacci(40)); // 快速返回，因为有缓存

权限校验装饰器#

1
function requireRole(role) {
2
  return function (value, context) {
3
    if (context.kind !== 'method') return;
4

5
    return function (...args) {
6
      // 假设 this.currentUser 包含当前用户信息
7
      if (!this.currentUser || !this.currentUser.roles.includes(role)) {
8
        throw new Error(`Access denied: requires role "${role}"`);
9
      }
10
      return value.call(this, ...args);
11
    };
12
  };
13
}
14

15
class AdminPanel {
16
  currentUser = { name: 'Alice', roles: ['admin', 'user'] };
17

18
  @requireRole('admin')
19
  deleteUser(userId) {
20
    console.log(`Deleting user ${userId}`);
21
  }
22

23
  @requireRole('superadmin')
24
  resetDatabase() {
25
    console.log('Resetting database...');
26
  }
27
}
28

29
const panel = new AdminPanel();
30
panel.deleteUser(42);       // OK
31
panel.resetDatabase();      // Error: Access denied: requires role "superadmin"

访问器装饰器（accessor）#

Stage 3 引入了全新的 accessor 关键字，它会自动为字段生成 getter/setter 对，并允许装饰器拦截读写操作。

accessor 基础#

1
class Person {
2
  accessor name = 'anonymous';
3
}
4

5
// 上面的代码等价于：
6
class Person {
7
  #name = 'anonymous';
8
  get name() { return this.#name; }
9
  set name(val) { this.#name = val; }
10
}

装饰 accessor#

访问器装饰器接收一个包含 get 和 set 的对象，返回新的 get/set 来替换：

1
function clamped(min, max) {
2
  return function (value, context) {
3
    if (context.kind !== 'accessor') return;
4

5
    const { get, set } = value;
6

7
    return {
8
      get() {
9
        return get.call(this);
10
      },
11
      set(val) {
12
        if (typeof val !== 'number') {
13
          throw new TypeError(`${context.name} must be a number`);
14
        }
15
        const clamped = Math.min(Math.max(val, min), max);
16
        set.call(this, clamped);
17
      },
18
      init(initialValue) {
19
        // init 可以转换初始值
20
        return Math.min(Math.max(initialValue, min), max);
21
      }
22
    };
23
  };
24
}
25

26
class ColorChannel {
27
  @clamped(0, 255) accessor red = 128;
28
  @clamped(0, 255) accessor green = 128;
29
  @clamped(0, 255) accessor blue = 128;
30
}
31

32
const color = new ColorChannel();
33
color.red = 300;
34
console.log(color.red); // 255（被 clamp 到上限）
35

36
color.green = -50;
37
console.log(color.green); // 0（被 clamp 到下限）

响应式 accessor#

1
function reactive(value, context) {
2
  if (context.kind !== 'accessor') return;
3

4
  const { get, set } = value;
5
  const listeners = new Set();
6

7
  return {
8
    get() {
9
      return get.call(this);
10
    },
11
    set(val) {
12
      const oldVal = get.call(this);
13
      set.call(this, val);
14
      if (oldVal !== val) {
15
        listeners.forEach(fn => fn(val, oldVal, context.name));
16
      }
17
    },
18
    init(initialValue) {
19
      // 将 onChange 方法注入到实例上
20
      context.addInitializer(function () {
21
        this.__listeners = this.__listeners || {};
22
        this.__listeners[context.name] = listeners;
23
        this.onChange = this.onChange || function (prop, fn) {
24
          if (this.__listeners[prop]) {
25
            this.__listeners[prop].add(fn);
26
          }
27
        };
28
      });
29
      return initialValue;
30
    }
31
  };
32
}
33

34
class FormModel {
35
  @reactive accessor username = '';
36
  @reactive accessor email = '';
37
}
38

39
const form = new FormModel();
40
form.onChange('username', (newVal, oldVal) => {
41
  console.log(`username changed: "${oldVal}" -> "${newVal}"`);
42
});
43

44
form.username = 'alice';
45
// username changed: "" -> "alice"

字段装饰器#

字段装饰器不能替换字段本身，但可以通过返回一个初始化函数来变换初始值：

1
function uppercase(value, context) {
2
  if (context.kind !== 'field') return;
3

4
  return function (initialValue) {
5
    if (typeof initialValue === 'string') {
6
      return initialValue.toUpperCase();
7
    }
8
    return initialValue;
9
  };
10
}
11

12
class Config {
13
  @uppercase env = 'production';
14
  @uppercase region = 'us-east';
15
}
16

17
const config = new Config();
18
console.log(config.env);    // "PRODUCTION"
19
console.log(config.region); // "US-EAST"

Decorator Metadata（装饰器元数据）#

Stage 3 装饰器最强大的特性之一是 metadata API。每个装饰器的 context 对象都包含一个共享的 metadata 对象，允许装饰器之间传递元信息。

1
const VALIDATORS = Symbol('validators');
2

3
function validate(validatorFn, message) {
4
  return function (value, context) {
5
    // 在 metadata 中注册验证器
6
    context.metadata[VALIDATORS] = context.metadata[VALIDATORS] || [];
7
    context.metadata[VALIDATORS].push({
8
      property: context.name,
9
      validate: validatorFn,
10
      message
11
    });
12
  };
13
}
14

15
function required(value, context) {
16
  return validate(v => v != null && v !== '', `${context.name} is required`)(value, context);
17
}
18

19
function minLength(len) {
20
  return function (value, context) {
21
    return validate(
22
      v => typeof v === 'string' && v.length >= len,
23
      `${context.name} must be at least ${len} characters`
24
    )(value, context);
25
  };
26
}
27

28
class UserForm {
29
  @required
30
  @minLength(3)
31
  accessor username = '';
32

33
  @required
34
  accessor email = '';
35
}
36

37
// 通过 Symbol.metadata 获取元数据
38
function validateInstance(instance) {
39
  const metadata = instance.constructor[Symbol.metadata];
40
  const validators = metadata?.[VALIDATORS] || [];
41
  const errors = [];
42

43
  for (const { property, validate: fn, message } of validators) {
44
    if (!fn(instance[property])) {
45
      errors.push(message);
46
    }
47
  }
48

49
  return errors;
50
}
51

52
const form = new UserForm();
53
form.username = 'ab';
54
form.email = '';
55

56
const errors = validateInstance(form);
57
console.log(errors);
58
// [
59
//   "username must be at least 3 characters",
60
//   "email is required"
61
// ]

用 Metadata 实现依赖注入#

1
const INJECT_KEY = Symbol('inject');
2

3
function injectable(value, context) {
4
  if (context.kind !== 'class') return;
5
  // 标记这个类可以被注入
6
  context.metadata[INJECT_KEY] = context.metadata[INJECT_KEY] || {};
7
  context.metadata[INJECT_KEY].injectable = true;
8
}
9

10
function inject(token) {
11
  return function (value, context) {
12
    if (context.kind !== 'field') return;
13

14
    context.metadata[INJECT_KEY] = context.metadata[INJECT_KEY] || {};
15
    context.metadata[INJECT_KEY].deps = context.metadata[INJECT_KEY].deps || [];
16
    context.metadata[INJECT_KEY].deps.push({
17
      property: context.name,
18
      token
19
    });
20

21
    return function () {
22
      // 初始值先设为 null，后续由容器注入
23
      return null;
24
    };
25
  };
26
}
27

28
// 简易 DI 容器
29
class Container {
30
  #bindings = new Map();
31

32
  bind(token, factory) {
33
    this.#bindings.set(token, factory);
34
    return this;
35
  }
36

37
  resolve(Class) {
38
    const instance = new Class();
39
    const metadata = Class[Symbol.metadata];
40
    const injectInfo = metadata?.[INJECT_KEY];
41

42
    if (injectInfo?.deps) {
43
      for (const { property, token } of injectInfo.deps) {
44
        const factory = this.#bindings.get(token);
45
        if (factory) {
46
          instance[property] = factory();
47
        }
48
      }
49
    }
50

51
    return instance;
52
  }
53
}
54

55
// 使用
56
@injectable
57
class App {
58
  @inject('logger') logger;
59
  @inject('config') config;
60

61
  run() {
62
    this.logger.log(`Running with env: ${this.config.env}`);
63
  }
64
}
65

66
const container = new Container();
67
container.bind('logger', () => ({ log: console.log }));
68
container.bind('config', () => ({ env: 'production', port: 3000 }));
69

70
const app = container.resolve(App);
71
app.run(); // "Running with env: production"

装饰器组合与执行顺序#

多个装饰器叠加时，执行顺序遵循**从下到上（从内到外）**的规则：

1
function first(value, context) {
2
  console.log('first evaluated');
3
  return function (...args) {
4
    console.log('first called');
5
    return value.call(this, ...args);
6
  };
7
}
8

9
function second(value, context) {
10
  console.log('second evaluated');
11
  return function (...args) {
12
    console.log('second called');
13
    return value.call(this, ...args);
14
  };
15
}
16

17
class Example {
18
  @first
19
  @second
20
  method() {
21
    console.log('method called');
22
  }
23
}
24

25
// 装饰器求值顺序: first evaluated -> second evaluated
26
// 调用时执行顺序: first called -> second called -> method called

装饰器表达式从上到下求值，但装饰器函数从下到上应用。这与函数组合 first(second(method)) 的语义一致。

TypeScript 5.0+ 实战#

TypeScript 5.0 开始原生支持 Stage 3 装饰器，不需要开启 experimentalDecorators。

1
// tsconfig.json 不需要任何额外配置，默认支持
2

3
// 类型安全的装饰器
4
function bound<This, Args extends unknown[], Return>(
5
  target: (this: This, ...args: Args) => Return,
6
  context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>
7
) {
8
  const methodName = context.name;
9
  context.addInitializer(function (this: This) {
10
    (this as any)[methodName] = (this as any)[methodName].bind(this);
11
  });
12
}
13

14
class Button {
15
  label = 'Click me';
16

17
  @bound
18
  handleClick() {
19
    console.log(`Button: ${this.label}`);
20
  }
21
}
22

23
const btn = new Button();
24
const { handleClick } = btn;
25
handleClick(); // "Button: Click me" — this 绑定正确

完整的类型安全验证框架#

1
type ValidatorFn = (value: unknown) => boolean;
2

3
interface ValidatorEntry {
4
  property: string | symbol;
5
  validate: ValidatorFn;
6
  message: string;
7
}
8

9
const VALIDATORS = Symbol('validators');
10

11
function createValidator(fn: ValidatorFn, message: string) {
12
  return function <This, Value>(
13
    _value: undefined,
14
    context: ClassFieldDecoratorContext<This, Value>
15
  ) {
16
    const meta = context.metadata as Record<symbol, ValidatorEntry[]>;
17
    meta[VALIDATORS] = meta[VALIDATORS] || [];
18
    meta[VALIDATORS].push({
19
      property: context.name,
20
      validate: fn,
21
      message
22
    });
23
  };
24
}
25

26
// 验证器工厂
27
const isString = createValidator(
28
  v => typeof v === 'string',
29
  'must be a string'
30
);
31

32
const isPositive = createValidator(
33
  v => typeof v === 'number' && v > 0,
34
  'must be a positive number'
35
);
36

37
function maxLength(n: number) {
38
  return createValidator(
39
    v => typeof v === 'string' && v.length <= n,
40
    `must not exceed ${n} characters`
41
  );
42
}
43

44
class Product {
45
  @isString @maxLength(100)
46
  name: string = '';
47

48
  @isPositive
49
  price: number = 0;
50
}
51

52
function validateObject<T extends object>(obj: T): string[] {
53
  const metadata = (obj.constructor as any)[Symbol.metadata] as Record<symbol, ValidatorEntry[]>;
54
  const validators = metadata?.[VALIDATORS] || [];
55
  const errors: string[] = [];
56

57
  for (const { property, validate, message } of validators) {
58
    if (!validate((obj as any)[property])) {
59
      errors.push(`${String(property)}: ${message}`);
60
    }
61
  }
62

63
  return errors;
64
}

与旧版装饰器的对比#

特性	旧版 (experimentalDecorators)	Stage 3
参数签名	`(target, name, descriptor)`	`(value, context)`
字段装饰器	不标准，各实现不同	统一规范
`accessor` 关键字	无	原生支持
Metadata	需要 `reflect-metadata`	内置 `Symbol.metadata`
私有成员	无法装饰	`context.isPrivate` 支持
参数装饰器	支持	暂不支持（未来可能加入）

迁移建议：如果你的项目大量使用了旧版装饰器（如 NestJS、TypeORM），不要急于迁移。等待这些框架官方适配 Stage 3 后再统一切换。新项目建议直接使用 Stage 3 装饰器。

最佳实践#

保持装饰器纯净：装饰器不应该产生副作用，尽量只做”增强”而不是”替换”
使用装饰器工厂传递参数：@decorator(options) 比修改全局状态更清晰
利用 metadata 而不是 WeakMap：Stage 3 的 metadata API 是官方推荐的元数据方案
注意 this 绑定：方法装饰器返回的函数通过 value.call(this, ...args) 保持正确的 this
类型安全优先：在 TypeScript 中充分利用泛型约束装饰器的类型

总结#

Stage 3 装饰器是 JavaScript 语言层面的一次重大进化。它提供了统一、标准、类型安全的元编程能力，让我们可以用声明式的方式增强类和类成员的行为。从日志、缓存、权限控制到依赖注入、表单验证，装饰器几乎无处不在。

现在就开始在你的项目中尝试 Stage 3 装饰器吧！

音乐

音乐

前言#