TypeScript: декораторы
Декораторы — экспериментальная возможность TypeScript.
Они позволяют разработчикам добавлять дополнительную функциональность классам, методам, свойствам или параметрам без изменения исходного класса.
Декоратор — это по сути функция, которую можно вызвать во время выполнения, чтобы изменить поведение целевого объекта.
Диаграмма SVG: Типы декораторовВведение в декораторы
Декораторы используют символ `@` как синтаксический сахар и могут применяться к классам, методам, аксессорам, свойствам или параметрам.
Этот паттерн обычно используется при разработке фреймворков; например, 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, управляют конфигурируемостью свойств
- Декораторы свойств:Добавляют метаданные к свойствам
- Декораторы параметров:Помечают или проверяют параметры методов
- Декоратор:Добиться большей настраиваемости декоратора с помощью параметризации
Другие расширения