Decorator trong TypeScript: method, class, field, accessor

Decorator là một hàm bạn gắn vào class hoặc thành viên của class bằng @name. Nó nhận phương thức gốc (hoặc class, hoặc thuộc tính) cùng một đối tượng context mô tả thứ đó, và có thể trả về một thứ thay thế. TypeScript hỗ trợ decorator chuẩn mà không cần cờ biên dịch nào.

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 chạy một lần, khi class được định nghĩa, và thay add bằng hàm bao mà nó trả về. Mọi lời gọi đều đi qua hàm bao đó. Các tham số generic giữ nguyên kiểu của this, của đối số và của giá trị trả về, nên add vẫn nhận hai số và trả về một số.

Decorator được biên dịch thế nào

Decorator chuẩn đến từ một đề xuất TC39 cho JavaScript, và TypeScript đã hiện thực chúng từ TypeScript 5.0. Đề xuất này chưa thuộc chuẩn JavaScript, và Node 24 không phân tích được cú pháp @, nên khi target là ES2022 (như trên các trang này), trình biên dịch viết lại mỗi class có decorator thành JavaScript thuần gọi đến các hàm helper (__esDecorate và __runInitializers, được sinh ra ở đầu tệp). Kết quả chạy được ở mọi nơi chạy được ES2022.

Một hệ quả: tệp có decorator không chạy được với cơ chế bỏ kiểu có sẵn của Node (node file.ts), vì cơ chế này chỉ xóa kiểu và để nguyên @. Node dừng lại với SyntaxError: Invalid or unexpected token. Hãy biên dịch bằng tsc hoặc một bundler trước.

Các loại decorator và chữ ký của chúng

Mọi decorator chuẩn đều có dạng (value, context) => replacement | void. value là gì và bạn được trả về gì phụ thuộc vào thứ được trang trí:

Mọi đối tượng context đều có kind, name và addInitializer. Context của thành viên class còn có static, private và một đối tượng access để đọc thành viên đó từ một instance. Decorator cũng dùng được cho thành viên static và #private.

Decorator factory

Để truyền tùy chọn, hãy viết một hàm trả về decorator và gọi nó ngay tại chỗ @. Đây là một decorator factory:

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) gọi retry trước, và hàm mà nó trả về mới là decorator thật sự. Nhiều decorator có thể chồng lên nhau: trong @a @b method(), b được áp dụng trước và a bao kết quả đó.

Class decorator và addInitializer

Class decorator nhận chính class đó. Nó có thể trả về một class con để thay thế, hoặc không trả về gì và chỉ ghi nhận class ở đâu đó. context.addInitializer đăng ký code chạy vào một thời điểm cụ thể: với class decorator, ngay sau khi class được định nghĩa xong; với method decorator, mỗi khi một instance được tạo.

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

Class decorator đặt phía trên class (hoặc sau export). Không có @bound, gọi loose() sẽ ném lỗi, vì this sẽ là undefined.

Decorator cho thuộc tính và accessor

Decorator cho thuộc tính không thấy và không chặn được các phép gán về sau: value của nó là undefined, và thứ duy nhất nó có thể trả về là một hàm biến đổi giá trị ban đầu của thuộc tính. Để chặn việc đọc và ghi, hãy khai báo thuộc tính với từ khóa accessor, biến nó thành một cặp getter và setter dựa trên một vùng lưu trữ private, rồi trang trí nó:

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 thuộc cùng đề xuất đó. Nó sinh ra getter và setter thật trên một thuộc tính #private, đó là lý do p.price = -5 đi qua set của decorator.

Decorator chuẩn và experimentalDecorators kiểu cũ

Trước TypeScript 5.0, decorator duy nhất mà TypeScript có là một phiên bản sớm của đề xuất, được bật bằng experimentalDecorators. Cờ đó vẫn còn, và nó chuyển trình biên dịch sang mô hình cũ, với chữ ký và ngữ nghĩa khác:

Decorator viết cho mô hình này không qua được bước kiểm tra kiểu ở mô hình kia. Đây là một decorator kiểu cũ trong dự án không bật cờ:

// 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.

Cách sửa là viết lại nó theo dạng chuẩn (value, context), như ví dụ đầu tiên trên trang này, hoặc bật mô hình cũ cho toàn bộ dự án:

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

Angular, NestJS và TypeORM vẫn đặt experimentalDecorators trong các cấu hình mà công cụ của chúng sinh ra và tài liệu của chúng yêu cầu. NestJS và TypeORM còn cần emitDecoratorMetadata, vì chúng đọc kiểu lúc chạy: NestJS để inject tham số của hàm khởi tạo, TypeORM để ánh xạ thuộc tính sang cột:

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

Nếu bạn dùng một trong các framework đó, hãy viết decorator theo kiểu cũ và làm theo tài liệu của framework. Với code mới không dùng framework nào như vậy, hãy dùng decorator chuẩn.

Khi nào nên dùng decorator

Decorator phù hợp với những hành vi xuyên suốt mà nếu không có nó sẽ phải lặp lại ở nhiều phương thức: ghi log, đo thời gian, cache, thử lại, kiểm tra quyền truy cập, kiểm tra dữ liệu, và đăng ký class với một container hoặc router. Chúng cũng che giấu luồng điều khiển, vì người đọc phải tra xem @retry làm gì rồi mới biết phương thức làm gì. Với một hai chỗ dùng, một hàm bậc cao bình thường (const fetchData = retry(3, rawFetch)) đơn giản hơn và dùng được cả bên ngoài class.