Javascript装饰器(stage 3)

October 3, 2023

stage3 装饰器在 typescript 5.0 得到正式支持了

它们在 typescript 中的差异，参见此处

Proposal: https://github.com/tc39/proposal-decorators

stage2 的装饰器基于 PropertyDescriptor，stage3 的装饰器则不同

最大的区别是 stage3 装饰器不允许改变类成员的类型（字段、访问器、方法）（出于性能考虑）

例子

function loggedMethod<This, Args extends any[], Return>(
    target: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
    const methodName = String(context.name);

    function replacementMethod(this: This, ...args: Args): Return {
        console.log(`LOG: Entering method '${methodName}'.`);
        const result = target.call(this, ...args);
        console.log(`LOG: Exiting method '${methodName}'.`);
        return result;
    }

    return replacementMethod;
}

function bound<This, Args extends any[], Return>(
    target: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
    const methodName = String(context.name);

    if (context.private) {
        throw new Error(`'bound' cannot decorate private properties like ${methodName}.`);
    }
    context.addInitializer(function (this: This) {
        Reflect.set(this as object, methodName, target.bind(this));
    });
}

class Person {
    name: string;
    constructor(name: string) {
        this.name = name;
    }

    @loggedMethod
    @bound
    greet() {
        console.log(`Hello, my name is ${this.name}.`);
    }
}

const { greet } = new Person("Ray");
greet();

定义

提案对装饰器函数的定义如下

type Decorator = (
    value: Input,
    context: {
        kind: string;
        name: string | symbol;
        access: {
            get?(): unknown;
            set?(value: unknown): void;
        };
        private?: boolean;
        static?: boolean;
        addInitializer?(initializer: () => void): void;
    },
) => Output | void;

注意：由于讨论的是 typescript 实现，具体以下面 typescript 的定义为准

可以发现 stage3 的装饰器的形式更固定，其第一个参数接收被装饰的值，第二个参数是对应的 context，context 描述了值的形状，
addInitializer 添加的函数将在实例化之前执行（具体参见下文），函数内部 this 被绑定为对应实例，
函数体可以返回一个新方法来替换原来的值，参见下表。 access 对象包含一组方法，它们的第一个参数都是任意对象，这些方法会去操作该对象上与当被装饰的键名相同的值

kind	Input	Output
class	`Class`	`Callable`
method	`Method`	`Method`
setter	`(T):void`	`(T):void`
getter	`():T`	`():T`
accessor	`{ get():T, set(T):void }`	`{ get():T, set(T):void, init(T):T }`
field	`undefined`	`(T) => T`

lib.decorators.d.ts

装饰器只能修饰类或类的成员（相比于 stage2 删除了参数装饰器，但 proposal 的扩展部分描述了参数装饰器）
一共有六种装饰器，对应 kind 的值为 class method getter setter field accessor

type DecoratorContext =
    | ClassDecoratorContext // 类
    | ClassMemberDecoratorContext; // 类的成员

type ClassMemberDecoratorContext =
    | ClassMethodDecoratorContext
    | ClassGetterDecoratorContext
    | ClassSetterDecoratorContext
    | ClassFieldDecoratorContext
    | ClassAccessorDecoratorContext;

具体声明如下（删去了 metadata）
注意：typescript 实现是 proposal 描述的超集，其添加了一些内容

interface ClassDecoratorContext<Class extends abstract new (...args: any) => any = abstract new (...args: any) => any> {
    readonly kind: "class";
    readonly name: string | undefined;
    addInitializer(initializer: (this: Class) => void): void;
}

interface ClassMethodDecoratorContext<
    This = unknown,
    Value extends (this: This, ...args: any) => any = (this: This, ...args: any) => any,
> {
    readonly kind: "method";
    readonly name: string | symbol;
    readonly static: boolean;
    readonly private: boolean;
    readonly access: {
        has(object: This): boolean;
        get(object: This): Value;
    };
    addInitializer(initializer: (this: This) => void): void;
}

interface ClassGetterDecoratorContext<This = unknown, Value = unknown> {
    readonly kind: "getter";
    readonly name: string | symbol;
    readonly static: boolean;
    readonly private: boolean;
    readonly access: {
        has(object: This): boolean;
        get(object: This): Value;
    };
    addInitializer(initializer: (this: This) => void): void;
}

interface ClassSetterDecoratorContext<This = unknown, Value = unknown> {
    readonly kind: "setter";
    readonly name: string | symbol;
    readonly static: boolean;
    readonly private: boolean;
    readonly access: {
        has(object: This): boolean;
        set(object: This, value: Value): void;
    };
    addInitializer(initializer: (this: This) => void): void;
}

// 即 getter 和 setter
interface ClassAccessorDecoratorContext<This = unknown, Value = unknown> {
    readonly kind: "accessor";
    readonly name: string | symbol;
    readonly static: boolean;
    readonly private: boolean;
    readonly access: {
        has(object: This): boolean;
        get(object: This): Value;
        set(object: This, value: Value): void;
    };
    addInitializer(initializer: (this: This) => void): void;
}

interface ClassFieldDecoratorContext<This = unknown, Value = unknown> {
    readonly kind: "field";
    readonly name: string | symbol;
    readonly static: boolean;
    readonly private: boolean;
    readonly access: {
        has(object: This): boolean;
        get(object: This): Value;
        set(object: This, value: Value): void;
    };
    addInitializer(initializer: (this: This) => void): void;
}

使用 `addInitializer` 添加初始化逻辑

装饰器 context 对象上的 addInitializer 方法可用于对类或类成员添加初始化函数。
该函数将在值已经定义完成后运行，具体执行时机如下：

类装饰器：在类完全定义之后运行，包括类的静态字段指定之后（即，在类的 prototype 属性和自身属性都确定之后）
类成员装饰器：在类被构造（即，被 new）的过程中执行，在类字段初始化之前执行
类静态成员装饰器：在类定义时执行，在静态字段定义之前，但在类成员定义之后执行

附：原文

需要注意的前置知识

装饰器用于修饰 class 语法创建的类
但是 class 语法无法在 prototype 属性上设置字段（只能设置方法和访问器）
设置字段的语法是将字段设置在被实例化的对象身上

类字段是这样初始化的：

对于基类，在构造函数调用前初始化
对于派生类，在 super() 后立刻初始化

这个初始化顺序其实和其它的语言没区别，比如 c++
在 constructor 中使用 this 和 java 是一样的，也相当于 c++ 使用 override

super 关键字仅允许在派生类和对象字面量中的方法使用
一个对象内部声明的方法（而不是声明一个字段。我们知道，字段可以是包括函数的任意值，但作为字段的函数并不绑定到对象上）
具有特殊内部属性 [[HomeObject]] 绑定到这个对象
这个函数的 super 则指向自身的 [[HomeObject]] 内部属性（与 this 不同，它是绑定的值）
但是只能在 super 上访问 super 指向的对象的 [[Prototype]] 上的属性，不能访问对象自身的属性

参见：此例子

let obj = {
    fn1() {
        // 对象方法，是一个具名函数。这个函数不能被 new，允许使用 super
        //（super 绑定到 obj，而 this 则始终指向被调用的对象）
        // obj.fn1.[[HomeObject]] == obj1
    },
    fn2: function () {
        // 对象字段，是一个匿名函数。这个函数可以被 new
        // 不允许使用 super
    },
};

new obj.fn1(); // TypeError: obj.fn1 is not a constructor
new obj.fn2(); // => fn2 {}

类方法只不过是设置在类的 prototype 属性上的对象方法而已

accessor 关键字

accessor 关键字的作用是将 field 自动变为 getter 和 setter
也就是 context.kind 会变成 accessor

显然，accessor 相当于 getter 和 setter，那就是设置在类的 prototype 上，而不是实例对象上
因此也可以将 accessor 看作是在 prototype 上设置字段（弥补了没有 accessor 关键字时只能在实例对象上设置字段的缺陷）

（虽然没什么用，但是这样还是不能在实例对象自身上设置具有 [[HomeObject]] 内部属性的对象方法）

class C {
    accessor x = 1;
}

// 相当于

class C {
    #x = 1;

    get x() {
        return this.#x;
    }

    set x(val) {
        this.#x = val;
    }
}

metadata

metadata 为 proposal 的扩展部分

待补充。。。

←Back to home