TypeScript: декораторы

Декораторы — экспериментальная возможность TypeScript.

Они позволяют разработчикам добавлять дополнительную функциональность классам, методам, свойствам или параметрам без изменения исходного класса.

Декоратор — это по сути функция, которую можно вызвать во время выполнения, чтобы изменить поведение целевого объекта.

Диаграмма SVG: Типы декораторов Background Title Decorator Types and Application Locations Center: Class @ClassDecorator Class Decorator Arrows to all directions Top: Property Decorator Property Decorator @propertyDecorator Right: Method Decorator Method Decorator @methodDecorator Bottom: Parameter Decorator Parameter Decorator @paramDecorator Lower Right: Accessor Decorator Accessor Decorator @getterDecorator Decorator Factory Explanation Decorator Factory A decorator factory is a function that returns a decorator function, enabling configuration through parameters. Example: function color(code: string) { return function(target) { ... }; } → @color("34") Arrow marker

Введение в декораторы

Декораторы используют символ `@` как синтаксический сахар и могут применяться к классам, методам, аксессорам, свойствам или параметрам.

Этот паттерн обычно используется при разработке фреймворков; например, Angular, TypeORM и т. д. широко используют декораторы для реализации внедрения зависимостей, валидации данных и других возможностей.

Примечание:В настоящее время декораторы являются экспериментальной функцией, и их необходимо явно включить в tsconfig.json. При использовании их в продакшене, пожалуйста, убедитесь в уровне поддержки экспериментальных функций в проекте.


Настройка для включения декораторов

Перед использованием декораторов необходимо включить соответствующие параметры компилятора в конфигурационном файле TypeScript tsconfig.json.

Конфигурация tsconfig.json

{
    "compilerOptions": {
        // Включить синтаксис декораторов
        "experimentalDecorators": true,

        // Включить метаданные декораторов (используются для фреймворков внедрения зависимостей)
        "emitDecoratorMetadata": true
    }
}

Описание параметра:

  • experimentalDecorators:Включает поддержку синтаксиса декораторов; это обязательное условие для использования декораторов.
  • emitDecoratorMetadata:Генерирует метаданные декораторов в скомпилированном JavaScript для использования фреймворками внедрения зависимостей.

Декораторы классов

Декораторы класса применяются к конструктору класса и могут изменять определение класса или добавлять дополнительную логику обработки.

Декоратор класса получает один параметр: конструктор целевого класса.

Базовое использование декораторов класса

// Определить функцию декоратора класса
// Параметр target — конструктор декорируемого класса
function sealed(target: Function) {
    // Вывести имя класса, к которому применён декоратор
    console.log("Декоратор применён к: " + target.name);

    // Использовать Object.seal, чтобы заблокировать конструктор и прототип
    // Запретить добавление или удаление свойств во время выполнения
    Object.seal(target);
    Object.seal(target.prototype);
}

// Использовать синтаксис @ для применения декоратора к классу
@sealed
class Person {
    name: string;

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

// Создать экземпляр для тестирования
var person = new Person("EXAMPLE");
console.log("Created: " + person.name);

// Попробуйте добавить новое свойство (будет запрещено, так как класс запечатан)
// person.age = 25; // молча не срабатывает

Вывод:

装饰器 applied to: Person
创建: EXAMPLE

Пояснение:

Декораторы классов выполняются во время определения класса и обычно используются для изменения поведения класса, добавления метаданных или реализации AOP (аспектно-ориентированного программирования).


Декораторы методов

Декораторы методов применяются к методам класса и могут изменять дескриптор свойства метода.

Декоратор метода получает три параметра: целевой объект, имя свойства и дескриптор свойства.

Основы использования декораторов методов

// Определяем фабрику декораторов методов
// Возвращаем функцию декоратора
function enumerable(value: boolean) {
    // Вернуть функцию-декоратор, принимающую три параметра
    return function (
        target: any,           // Объект-прототип содержащего класса
        propertyKey: string,    // Имя метода
        descriptor: PropertyDescriptor // Дескриптор свойства
    ) {
        // Изменить атрибут enumerable свойства
        // false означает, что метод не является перечисляемым
        descriptor.enumerable = value;
    };
}

class Greeter {
    greeting: string;

    constructor(message: string) {
        this.greeting = message;
    }

    // Применить декоратор, чтобы сделать метод неперечисляемым
    @enumerable(false)
    greet() {
        return "Hello, " + this.greeting;
    }
}

var g = new Greeter("World");

// Проверить, является ли метод greet перечисляемым
console.log("Перечисляемость метода: " + g.propertyIsEnumerable("greet"));

// Перебрать свойства
for (key⟦⟧in key in g) {
    console.⟦⟧loglog("Свойства: " + key);
}

Вывод:

方法可枚举: false

Совет:PropertyDescriptor содержит такие атрибуты, как enumerable, configurable, writable и value, которые можно изменять, как описано выше.


Декораторы

Декораторы доступа применяются к методам getter и setter класса.

Подобно декораторам методов, декораторы доступа также могут изменять дескриптор свойства.

Использование декораторов аксессоров

// Фабрика декоратора аксессора
function configurable(value: boolean) {
    return function (
        target: any,
        propertyKey: string,
        descriptor: PropertyDescriptor
    ) {
        // Изменить атрибут configurable свойства
        // false означает, что аксессор нельзя перенастроить или удалить
        descriptor.configurable = value;
    };
}

class Point {
    private _x: number = 0;
    private _y: number = 0;

    // Использовать декоратор, чтобы заблокировать геттер
    @configurable(false)
    get x() {
        return this._x;
    }

    @configurable(false)
    get y() {
        return this._y;
    }

    set x(value: number) {
        this._x = value;
    }

    set y(value: number) {
        this._y = value;
    }
}

var point = new Point();
point.x = 10;
point.y = 20;
console.log("Coordinates: ( + point.x + ", " + point.y + ")");

Пояснение:

Декораторы доступа не могут быть применены одновременно и к геттеру, и к сеттеру одного и того же свойства; можно выбрать только один из них.


Декораторы свойств

Декораторы свойств применяются к определениям свойств класса.

Декоратор свойства принимает два параметра: целевой объект и имя свойства.

Использование декораторов свойств

// Фабрика декоратора свойства
function format(formatString: string) {
    return function (
        target: any,           // Объект-прототип класса
        propertyKey: string     // Имя свойства
    ) {
        // Сохранить метаданные на целевом объекте
        // Использовать propertyKey + "_format" в качестве имени ключа во избежание конфликтов
        Object.defineProperty(target, propertyKey + "_format", {
            value: formatString,
            writable: false,
            enumerable: false,
            configurable: true
        });
    };
}

class User {
    // Применить декоратор свойства, чтобы указать формат даты
    @format("YYYY-MM-DD")
    birthDate: string;

    constructor(birthDate: string) {
        this.birthDate = birthDate;
    }
}

var user = new User("1990-01-01");
console.log("Дата рождения: " + user.birthDate);

// Доступ к сохранённым метаданным
console.log("Формат даты: " + (user as any).birthDate_format);

Вывод:

出生日期: 1990-01-01
日期格式: YYYY-MM-DD

Декораторы параметров

Декораторы параметров применяются к параметрам методов класса и могут добавлять метаданные или маркеры к параметрам.

Декоратор параметра получает три параметра: целевой объект, имя метода и индекс параметра в функции.

Использование декораторов параметров

// Декоратор параметра
// Используется для записи информации о параметре или выполнения проверки
function logParameter(
    target: any,               // Объект-прототип класса
    propertyKey: string,       // Имя метода
    parameterIndex: number    // Позиция индекса параметра в функции (начиная с 0)
) {
    console.log("Декоратор параметра: " + propertyKey +
        " " + (parameterIndex + 1) + "-й параметр");
}

class Greeter {
    greeting: string;

    constructor(greeting: string) {
        this.greeting = greeting;
    }

    // Используйте синтаксис @ перед параметром, чтобы применить декоратор
    greet(@logParameter name: string) {
        return this.greeting + ", " + name;
    }
}

var greeter = new Greeter("Привет");
greeter.greet("ПРИМЕР");

Вывод:

参数装饰器: greet 第 1 个参数

Фабрика декораторов

Фабрика декораторов — это функция, которая возвращает функцию-декоратор.

С помощью фабрики декораторов можно передавать пользовательские параметры при применении декоратора, что обеспечивает более гибкую настройку.

Фабрика декораторов для цветных логов

// Фабрика декораторов: получает параметры конфигурации и возвращает функцию-декоратор
function color(colorCode: string) {
    // colorCode — это код цвета в escape-последовательностях ANSI
    // Например: 34 = синий, 31 = красный, 32 = зелёный
    return function (
        target: any,
        propertyKey: string,
        descriptor: PropertyDescriptor
    ) {
        // Сохранить исходный метод
        var originalMethod = descriptor.value;

        // Переопределить метод, чтобы добавить цвет
        descriptor.value = function (...args: any[]) {
            // Вызвать исходный метод, чтобы получить возвращаемое значение
            var result = originalMethod.apply(this, args);

            // Если мы находимся в терминальной среде, добавьте цвет к выводу
            // Формат escape-последовательности ANSI: \x1b[код цвета m содержимое \x1b[0m
            return "\x1b[" + colorCode + "m" + result + "\x1b[0m";
        };
    };
}

class Logger {
    // Используйте фабрику декораторов, передайте код синего цвета 34
    @color("34")
    log(message: string): string {
        return message;
    }

    @color("31")
    error(message: string): string {
        return message;
    }

    @color("32")
    success(message: string): string {
        return message;
    }
}

var logger = new Logger();
console.log(logger.log("Это синий лог"));
console.log(logger.error("Это красная ошибка"));
console.log(logger.success("Это зелёное сообщение об успехе"));

Результат выполнения:

This is blue log (displayed as blue in terminal)
This is red error (displayed as red in terminal)
This is green success (displayed as green in terminal)

Explanation:Фабрика декораторов — наиболее часто используемая форма в реальной разработке. Она позволяет передавать параметры при применении декораторов, обеспечивая настройку.


Порядок выполнения декораторов

Когда у класса несколько декораторов, порядок выполнения следует определённым правилам.

  • Декораторы применяются снизу вверх
  • Несколько декораторов одного типа выполняются справа налево
  • Декораторы параметров выполняются перед декораторами методов

Пример порядка выполнения декораторов

// Наложение нескольких декораторов
function first() {
    console.log("first decorator");
    return function (target: any) {
        console.log("first decorator function");
    };
}

function second() {
    console.log("второй декоратор");
    return function (target: any) {
        console.log("вторая функция-декоратор");
    };
}

@first()
@second()
class MyClass {
    name: string;
}

var obj = new MyClass();

Результат выполнения:

second 装饰器
first 装饰器
second 装饰器函数
first 装饰器函数

Пояснение:

Определения функций-декораторов выполняются первыми (console.log), затем функции-декораторы выполняются в порядке снизу вверх.


Сценарии реального применения

Декораторы имеют широкий спектр сценариев применения в реальных проектах.

Логирование

Автоматически записывать логи вызовов методов.

Пример

// Декоратор логирования
function log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    var originalMethod = descriptor.value;

    descriptor.value = function (...args: any[]) {
        console.log("Вызов метода: " + propertyKey + ", параметры: " + JSON.stringify(args));
        var result = originalMethod.apply(this, args);
        console.log("Метод вернул: " + JSON.stringify(result));
        return result;
    };
}

class MathService {
    @log
    add(a: number, b: number): number {
        return a + b;
    }

    @log
    multiply(a: number, b: number): number {
        return a * b;
    }
}

var math = new MathService();
console.log("Результат вычисления: " + math.add(5, 3));

Результат выполнения:

调用方法: add,参数: [5,3]
方法返回: 8
计算结果: 8

Проверка разрешений

Реализуйте проверку разрешений на уровне методов.

Пример

// Имитация роли текущего пользователя
var currentUser = { role: "admin" };

// Декоратор разрешений
function requireRole(role: string) {
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
        var originalMethod = descriptor.value;

        descriptor.value = function (...args: any[]) {
            if (currentUser.role !== role) {
                console.log("Недостаточно прав, невозможно выполнить " + propertyKey);
                return null;
            }
            return originalMethod.apply(this, args);
        };
    };
}

class AdminService {
    @requireRole("admin")
    deleteUser(id: number): string {
        return "Удаление пользователя " + id + " выполнено успешно";
    }

    @requireRole("admin")
    viewUser(id: number): string {
        return "Просмотр пользователя " + id;
    }
}

var admin = new AdminService();
console.log(admin.viewUser(1));
console.log(admin.deleteUser(1));

// Имитировать обычного пользователя
currentUser = { role: "user" };
console.log(admin.deleteUser(2));

Результат выполнения:

查看用户 1
删除用户 1 成功
权限不足,无法执行 deleteUser

Примечания

  • Экспериментальная функция:Декораторы — это предложение _stage 3_ ECMAScript, и в настоящее время они всё ещё являются экспериментальной функцией
  • Параметры компилятора:Необходимо включить experimentalDecorators
  • Определения типов:Для полной поддержки типов требуется более новая версия TypeScript
  • Примечание по отладке:Декораторы выполняются во время компиляции, и некоторые инструменты отладки могут неправильно сопоставлять расположения в исходном коде

Рекомендация:При использовании декораторов в проекте рекомендуется создавать специализированные служебные классы декораторов или библиотеки функций для единообразного управления определением и использованием декораторов.


Итог

Декораторы TypeScript предоставляют мощную возможность метапрограммирования.

  • Декораторы класса:Изменяют сам класс, могут использоваться для добавления метаданных, блокировки классов и т. д.
  • Декораторы методов:Изменяют свойства методов, могут использоваться для логирования, валидации и т. д.
  • Декораторы аксессоров:Изменяют getter/setter, управляют конфигурируемостью свойств
  • Декораторы свойств:Добавляют метаданные к свойствам
  • Декораторы параметров:Помечают или проверяют параметры методов
  • Декоратор:Добиться большей настраиваемости декоратора с помощью параметризации

Другие расширения