Декоратори в JavaScript: Разгръщане на силата на програмирането с метаданни

Декораторите в JavaScript, въведени като стандартна функция в ES2022, предоставят мощен и елегантен начин за добавяне на метаданни и промяна на поведението на класове, методи, свойства и параметри. Те предлагат декларативен синтаксис за прилагане на междусекторни проблеми, което води до по-поддържаем, преизползваем и изразителен код. Тази публикация в блога ще се задълбочи в света на JavaScript декораторите, изследвайки техните основни концепции, практически приложения и основните механизми, които ги карат да работят.

Какво представляват декораторите в JavaScript?

В основата си декораторите са функции, които променят или подобряват декорирания елемент. Те използват символа @, последван от името на функцията на декоратора. Мислете за тях като за анотации или модификатори, които добавят метаданни или променят основното поведение, без директно да променят основната логика на декорирания обект. Те ефективно обвиват декорирания елемент, инжектирайки персонализирана функционалност.

Например, декоратор може автоматично да регистрира извиквания на методи, да валидира входни параметри или да управлява контрола на достъпа. Декораторите насърчават разделението на отговорностите, като поддържат основната бизнес логика чиста и фокусирана, като същевременно ви позволяват да добавяте допълнителни поведения по модулен начин.

Синтаксисът на декораторите

Декораторите се прилагат с помощта на символа @ преди елемента, който декорират. Има различни типове декоратори, всеки насочен към конкретен елемент:

• Декоратори на класове: Прилагат се към класове.
• Декоратори на методи: Прилагат се към методи.
• Декоратори на свойства: Прилагат се към свойства.
• Декоратори на аксесори: Прилагат се към getter и setter методи.
• Декоратори на параметри: Прилагат се към параметри на методи.

Ето един основен пример за декоратор на клас:

            @logClass
class MyClass {
  constructor() {
    // ...
  }
}

function logClass(target) {
  console.log(`Class ${target.name} has been created.`);
}
            

              
                Copy
              
            
          

В този пример, logClass е функция-декоратор, която приема конструктора на класа (target) като аргумент. След това тя записва съобщение в конзолата всеки път, когато се създаде инстанция на MyClass.

Разбиране на програмирането с метаданни

Декораторите са тясно свързани с концепцията за програмиране с метаданни. Метаданните са "данни за данни". В контекста на програмирането, метаданните описват характеристиките и свойствата на елементи от кода, като класове, методи и свойства. Декораторите ви позволяват да асоциирате метаданни с тези елементи, позволявайки интроспекция по време на изпълнение и модификация на поведението въз основа на тези метаданни.

API-то Reflect Metadata (част от спецификацията на ECMAScript) предоставя стандартен начин за дефиниране и извличане на метаданни, асоциирани с обекти и техните свойства. Въпреки че не е строго задължително за всички случаи на употреба на декоратори, то е мощен инструмент за напреднали сценарии, където трябва динамично да осъществявате достъп и да манипулирате метаданни по време на изпълнение.

Например, можете да използвате Reflect Metadata, за да съхранявате информация за типа данни на свойство, правила за валидиране или изисквания за оторизация. След това тези метаданни могат да бъдат използвани от декораторите за извършване на действия като валидиране на вход, сериализация на данни или налагане на политики за сигурност.

Видове декоратори с примери

1. Декоратори на класове

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

Пример: Имплементиране на Singleton шаблон

Шаблонът Singleton гарантира, че се създава само една инстанция на даден клас. Ето как можете да го имплементирате с помощта на декоратор на клас:

            function Singleton(target) {
  let instance = null;

  return function (...args) {
    if (!instance) {
      instance = new target(...args);
    }
    return instance;
  };
}

@Singleton
class DatabaseConnection {
  constructor(connectionString) {
    this.connectionString = connectionString;
    console.log(`Connecting to ${connectionString}`);
  }

  query(sql) {
    console.log(`Executing query: ${sql}`);
  }
}

const db1 = new DatabaseConnection('mongodb://localhost:27017');
const db2 = new DatabaseConnection('mongodb://localhost:27017');

console.log(db1 === db2); // Output: true

            

              
                Copy
              
            
          

В този пример, декораторът Singleton обвива класа DatabaseConnection. Той гарантира, че се създава само една инстанция на класа, независимо колко пъти е извикан конструкторът.

2. Декоратори на методи

Декораторите на методи се прилагат към методи в рамките на клас. Те могат да се използват за промяна на поведението на метода, добавяне на логване, имплементиране на кеширане или прилагане на контрол на достъпа.

Пример: Логване на извиквания на методиТози декоратор логва името на метода и неговите аргументи всеки път, когато методът бъде извикан.

            function logMethod(target, propertyKey, descriptor) {
  const originalMethod = descriptor.value;

  descriptor.value = function (...args) {
    console.log(`Calling method: ${propertyKey} with arguments: ${JSON.stringify(args)}`);
    const result = originalMethod.apply(this, args);
    console.log(`Method ${propertyKey} returned: ${result}`);
    return result;
  };
  return descriptor;
}

class Calculator {
  @logMethod
  add(x, y) {
    return x + y;
  }

  @logMethod
  subtract(x, y) {
    return x - y;
  }
}

const calc = new Calculator();
calc.add(5, 3); // Logs: Calling method: add with arguments: [5,3]
                //       Method add returned: 8
calc.subtract(10, 4); // Logs: Calling method: subtract with arguments: [10,4]
                  //       Method subtract returned: 6

            

              
                Copy
              
            
          

Тук декораторът logMethod обвива оригиналния метод. Преди да изпълни оригиналния метод, той записва името на метода и неговите аргументи. След изпълнението, той записва върнатата стойност.

3. Декоратори на свойства

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

Пример: Валидиране на стойности на свойства

            function validate(target, propertyKey) {
  let value;

  const getter = function () {
    return value;
  };

  const setter = function (newValue) {
    if (typeof newValue !== 'string' || newValue.length < 3) {
      throw new Error(`Property ${propertyKey} must be a string with at least 3 characters.`);
    }
    value = newValue;
  };

  Object.defineProperty(target, propertyKey, {
    get: getter,
    set: setter,
    enumerable: true,
    configurable: true,
  });
}

class User {
  @validate
  name;
}

const user = new User();

try {
  user.name = 'Jo'; // Throws an error
} catch (error) {
  console.error(error.message);
}

user.name = 'John Doe'; // Works fine
console.log(user.name);

            

              
                Copy
              
            
          

В този пример, декораторът validate прихваща достъпа до свойството name. Когато се присвои нова стойност, той проверява дали стойността е низ и дали дължината й е поне 3 символа. Ако не, хвърля грешка.

4. Декоратори на аксесори

Декораторите на аксесори се прилагат към getter и setter методи. Те са подобни на декораторите на методи, но конкретно таргетират аксесори (getters и setters).

Пример: Кеширане на резултати от гетъри

            function cached(target, propertyKey, descriptor) {
  const originalGetter = descriptor.get;
  let cacheValue;
  let cacheSet = false;

  descriptor.get = function () {
    if (cacheSet) {
      console.log(`Returning cached value for ${propertyKey}`);
      return cacheValue;
    } else {
      console.log(`Calculating and caching value for ${propertyKey}`);
      cacheValue = originalGetter.call(this);
      cacheSet = true;
      return cacheValue;
    }
  };
  return descriptor;
}

class Circle {
  constructor(radius) {
    this.radius = radius;
  }

  @cached
  get area() {
    console.log('Calculating area...');
    return Math.PI * this.radius * this.radius;
  }
}

const circle = new Circle(5);
console.log(circle.area); // Calculates and caches the area
console.log(circle.area); // Returns the cached area

            

              
                Copy
              
            
          

Декораторът cached обвива гетъра за свойството area. Първият път, когато area бъде достъпено, гетърът се изпълнява и резултатът се кешира. Последващите достъпи връщат кешираната стойност, без да се преизчислява.

5. Декоратори на параметри

Декораторите на параметри се прилагат към параметри на методи. Те могат да се използват за добавяне на метаданни за параметрите, валидиране на вход или модифициране на стойностите на параметрите.

Пример: Валидиране на параметър за имейл

            const requiredMetadataKey = Symbol("required");

function required(target: Object, propertyKey: string | symbol, parameterIndex: number) {
    let existingRequiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyKey) || [];
    existingRequiredParameters.push(parameterIndex);
    Reflect.defineMetadata(requiredMetadataKey, existingRequiredParameters, target, propertyKey);
}

function validateEmail(email: string) {
  const emailRegex = /^[\w-\.]{2,}@([\w-]+\.)+[\w-]{2,4}$/g;
  return emailRegex.test(email);
}

function validate(target: any, propertyName: string, descriptor: TypedPropertyDescriptor) {
  let method = descriptor.value!;

  descriptor.value = function () {
    let requiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyName);
    if (requiredParameters) {
      for (let parameterIndex of requiredParameters) {
          if(arguments.length <= parameterIndex){
             throw new Error("Missing required argument.");
          }

          const email = arguments[parameterIndex];
          if (!validateEmail(email)) {
              throw new Error(`Invalid email format for argument #${parameterIndex + 1}.`);
          }
      }
    }

    return method.apply(this, arguments);
  }
}

class EmailService {
  @validate
  sendEmail(@required to: string, subject: string, body: string) {
    console.log(`Sending email to ${to} with subject: ${subject}`);
  }
}

const emailService = new EmailService();

try {
  emailService.sendEmail('invalid-email', 'Hello', 'This is a test email.'); // Throws an error
} catch (error) {
  console.error(error.message);
}

emailService.sendEmail('valid@email.com', 'Hello', 'This is a test email.'); // Works fine

            

              
                Copy
              
            
          

В този пример, декораторът @required маркира параметъра to като задължителен и указва, че той трябва да бъде във валиден имейл формат. Декораторът validate след това използва Reflect Metadata, за да извлече тази информация и да валидира параметъра по време на изпълнение.

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

• Подобрена четимост и поддържаемост на кода: Декораторите предоставят декларативен синтаксис, който прави кода по-лесен за разбиране и поддръжка.
• Повишена преизползваемост на кода: Декораторите могат да бъдат преизползвани в множество класове и методи, намалявайки дублирането на кода.
• Разделение на отговорностите: Декораторите насърчават разделението на отговорностите, като ви позволяват да добавяте допълнителни поведения, без да променяте основната логика.
• Повишена гъвкавост: Декораторите осигуряват гъвкав начин за промяна на поведението на елементи от кода по време на изпълнение.
• AOP (Аспектно-ориентирано програмиране): Декораторите позволяват принципите на AOP, позволявайки ви да модулирате междусекторни проблеми.

Случаи на употреба на декоратори

Декораторите могат да се използват в широк спектър от сценарии, включително:

• Логване: Логване на извиквания на методи, показатели за производителност или съобщения за грешки.
• Валидиране: Валидиране на входни параметри или стойности на свойства.
• Кеширане: Кеширане на резултати от методи за подобряване на производителността.
• Оторизация: Прилагане на политики за контрол на достъпа.
• Инжектиране на зависимости: Управление на зависимостите между обекти.
• Сериализация/Десериализация: Преобразуване на обекти до и от различни формати.
• Обвързване на данни (Data Binding): Автоматично актуализиране на елементи на потребителския интерфейс при промяна на данните.
• Управление на състоянието (State Management): Имплементиране на шаблони за управление на състоянието в приложения като React или Angular.
• Версиониране на API: Маркиране на методи или класове като принадлежащи към конкретна версия на API.
• Флагове за функции (Feature Flags): Активиране или деактивиране на функции въз основа на настройки за конфигурация.

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

Фабрика за декоратори е функция, която връща декоратор. Това ви позволява да персонализирате поведението на декоратора, като подавате аргументи на фабричната функция.

Пример: Параметризиран логер

            function logMethodWithPrefix(prefix: string) {
  return function (target, propertyKey, descriptor) {
    const originalMethod = descriptor.value;

    descriptor.value = function (...args) {
      console.log(`${prefix}: Calling method: ${propertyKey} with arguments: ${JSON.stringify(args)}`);
      const result = originalMethod.apply(this, args);
      console.log(`${prefix}: Method ${propertyKey} returned: ${result}`);
      return result;
    };
    return descriptor;
  };
}

class Calculator {
  @logMethodWithPrefix('[CALCULATION]')
  add(x, y) {
    return x + y;
  }

  @logMethodWithPrefix('[CALCULATION]')
  subtract(x, y) {
    return x - y;
  }
}

const calc = new Calculator();
calc.add(5, 3); // Logs: [CALCULATION]: Calling method: add with arguments: [5,3]
                //       [CALCULATION]: Method add returned: 8
calc.subtract(10, 4); // Logs: [CALCULATION]: Calling method: subtract with arguments: [10,4]
                  //       [CALCULATION]: Method subtract returned: 6

            

              
                Copy
              
            
          

Функцията logMethodWithPrefix е фабрика за декоратори. Тя приема аргумент prefix и връща функция-декоратор. След това функцията-декоратор логва извикванията на методи с указания префикс.

Примери от реалния свят и казуси

Разгледайте глобална платформа за електронна търговия. Те биха могли да използват декоратори за:

• Интернационализация (i18n): Декораторите могат автоматично да превеждат текст въз основа на езиковите настройки на потребителя. Декоратор @translate може да маркира свойства или методи, които трябва да бъдат преведени. Декораторът след това ще извлече подходящия превод от ресурсен пакет въз основа на избрания от потребителя език.
• Конвертиране на валута: При показване на цени, декоратор @currency може автоматично да преобразува цената в местната валута на потребителя. Този декоратор ще трябва да осъществява достъп до външен API за конвертиране на валута и да съхранява обменните курсове.
• Изчисляване на данъци: Данъчните правила варират значително между държави и региони. Декораторите могат да се използват за прилагане на правилната данъчна ставка въз основа на местоположението на потребителя и закупения продукт. Декоратор @tax може да използва информация за геолокация, за да определи подходящата данъчна ставка.
• Откриване на измами: Декоратор @fraudCheck при чувствителни операции (като плащане) може да задейства алгоритми за откриване на измами.

Друг пример е глобална логистична компания:

• Геолокационно проследяване: Декораторите могат да подобрят методите, които се занимават с данни за местоположение, като записват точността на GPS показанията или валидират форматите на местоположение (географска ширина/дължина) за различни региони. Декоратор @validateLocation може да гарантира, че координатите отговарят на конкретен стандарт (напр. ISO 6709) преди обработка.
• Работа с часови зони: При планиране на доставки, декораторите могат автоматично да преобразуват часовете в местната часова зона на потребителя. Декоратор @timeZone би използвал база данни за часови зони, за да извърши преобразуването, гарантирайки, че графиците за доставка са точни, независимо от местоположението на потребителя.
• Оптимизация на маршрути: Декораторите могат да се използват за анализ на адресите на произход и дестинация на заявките за доставка. Декоратор @routeOptimize може да извика външен API за оптимизация на маршрути, за да намери най-ефективния маршрут, като вземе предвид фактори като условията на трафика и затворени пътища в различни държави.

Декоратори и TypeScript

TypeScript има отлична поддръжка за декоратори. За да използвате декоратори в TypeScript, трябва да активирате опцията за компилатор experimentalDecorators във вашия файл tsconfig.json:

            {
  "compilerOptions": {
    "target": "es6",
    "experimentalDecorators": true,
    // ... other options
  }
}
            

              
                Copy
              
            
          

TypeScript предоставя информация за типовете на декораторите, което ги прави по-лесни за писане и поддръжка. TypeScript също така налага типова безопасност при използване на декоратори, помагайки ви да избягвате грешки по време на изпълнение. Примерите с код в тази публикация в блога са написани предимно на TypeScript за по-добра типова безопасност и четимост.

Бъдещето на декораторите

Декораторите са сравнително нова функция в JavaScript, но имат потенциала значително да повлияят на начина, по който пишем и структурираме кода. Тъй като екосистемата на JavaScript продължава да се развива, можем да очакваме да видим повече библиотеки и фреймуъркове, които използват декоратори, за да предоставят нови и иновативни функции. Стандартизацията на декораторите в ES2022 гарантира тяхната дългосрочна жизнеспособност и широко разпространение.

Предизвикателства и съображения

• Сложност: Прекомерното използване на декоратори може да доведе до сложен код, който е труден за разбиране. От решаващо значение е да ги използвате разумно и да ги документирате обстойно.
• Производителност: Декораторите могат да въведат допълнителни разходи (overhead), особено ако извършват сложни операции по време на изпълнение. Важно е да се вземат предвид последиците за производителността от използването на декоратори.
• Отстраняване на грешки (Debugging): Отстраняването на грешки в код, който използва декоратори, може да бъде предизвикателство, тъй като потокът на изпълнение може да бъде по-малко ясен. Добрите практики за логване и инструменти за отстраняване на грешки са от съществено значение.
• Крива на обучение: Разработчиците, които не са запознати с декораторите, може да се наложи да инвестират време в изучаване на начина им на работа.

Най-добри практики за използване на декоратори

• Използвайте декоратори пестеливо: Използвайте декоратори само когато предоставят ясна полза по отношение на четимостта, преизползваемостта или поддържаемостта на кода.
• Документирайте вашите декоратори: Ясно документирайте предназначението и поведението на всеки декоратор.
• Поддържайте декораторите прости: Избягвайте сложна логика в декораторите. Ако е необходимо, делегирайте сложни операции на отделни функции.
• Тествайте вашите декоратори: Тествайте вашите декоратори обстойно, за да сте сигурни, че работят правилно.
• Следвайте конвенциите за именуване: Използвайте последователна конвенция за именуване на декоратори (напр. @LogMethod, @ValidateInput).
• Обмислете производителността: Имайте предвид последиците за производителността от използването на декоратори, особено в критичен за производителността код.

Заключение

Декораторите в JavaScript предлагат мощен и гъвкав начин за подобряване на преизползваемостта на кода, подобряване на поддържаемостта и имплементиране на междусекторни проблеми. Като разбирате основните концепции на декораторите и API-то Reflect Metadata, можете да ги използвате, за да създадете по-изразителни и модулни приложения. Въпреки че има предизвикателства, които трябва да се вземат предвид, ползите от използването на декоратори често надвишават недостатъците, особено в големи и сложни проекти. С развитието на екосистемата на JavaScript, декораторите вероятно ще играят все по-важна роля в оформянето на начина, по който пишем и структурираме кода. Експериментирайте с предоставените примери и проучете как декораторите могат да решат конкретни проблеми във вашите проекти. Възприемането на тази мощна функция може да доведе до по-елегантни, поддържаеми и надеждни JavaScript приложения в разнообразни международни контексти.