Генериране на код в TypeScript: Овладяване на създаването на типове, базирано на шаблони

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

Защо генериране на код в TypeScript?

Генерирането на код е автоматизираното създаване на код от шаблон, конфигурация или друг източник. В контекста на TypeScript този процес е изключително ценен по няколко причини:

• Намален шаблонен код: Автоматизира създаването на повтарящи се кодови модели, спестявайки време и усилия на разработчиците. Представете си генериране на интерфейси или класове от JSON схема или спецификации на OpenAPI, елиминирайки ръчното кодиране.
• Подобрена консистентност: Налага стандартизиран подход към дефинициите на типове и структурата на кода, водещ до по-голяма консистентност в проектите, което е от решаващо значение за екипи, работещи в различни региони и часови зони.
• Подобрена поддръжка: Улеснява актуализирането на кода, когато основните модели на данни или API се променят. Когато изходният шаблон е актуализиран, целият генериран код се актуализира автоматично, минимизирайки риска от грешки и спестявайки ценно време за отстраняване на грешки.
• Повишена повторна използваемост: Насърчава повторното използване на код, като ви позволява да създавате общи типове и функции, които могат да бъдат приложени към различни структури от данни. Това е особено полезно в международни проекти, където може да се наложи да работите с формати на данни и структури от различни местоположения.
• По-бързи цикли на разработка: Ускорява разработката чрез автоматизиране на досадни задачи, освобождавайки разработчиците да се съсредоточат върху по-стратегическа работа. Това е жизненоважно за поддържане на проектите по график, особено когато става въпрос за сложни проекти, които включват големи, разпръснати екипи.

Създаване на типове, базирано на шаблони: Основната концепция

Създаването на типове, базирано на шаблони, включва използването на шаблон (обикновено написан на език за шаблони като Handlebars, EJS или дори обикновен JavaScript) за генериране на код на TypeScript. Тези шаблони съдържат заместители, които се заменят с динамични стойности по време на компилация или по време на изпълнение на генерирането на код. Това позволява гъвкав, мощен начин за генериране на типове, интерфейси и други кодови конструкции на TypeScript. Нека да разгледаме как работи това и кои са често срещаните библиотеки за използване.

Езици и инструменти за шаблони

Няколко езика за шаблони се интегрират добре с генерирането на код в TypeScript:

• Handlebars: Опростен и широко използван механизъм за шаблони, известен със своята четимост и лекота на използване.
• EJS (Embedded JavaScript): Позволява ви да вграждате JavaScript директно във вашите шаблони, осигурявайки мощен контрол върху генерирания код.
• Nunjucks: Друг популярен механизъм за шаблони, който поддържа функции като наследяване и включвания.
• Библиотеки за шаблони във вашата система за изграждане (напр. използване на `fs` и шаблонни литерали): Не винаги се нуждаете от специализиран механизъм за шаблони. Шаблонните литерали и модулът `fs` на Node.js могат да бъдат изненадващо ефективни.

Помислете за тези инструменти, за да управлявате процеса на генериране:

• TypeScript Compiler API: Предоставя програмен достъп до компилатора на TypeScript, позволявайки ви да интегрирате генерирането на код директно във вашия конвейер за изграждане.
• Инструменти за генериране на код (напр. Plop, Yeoman, Hygen): Тези инструменти опростяват процеса на генериране на код и управление на шаблони. Те предоставят функции като подкани, управление на файлова система и рендиране на шаблони.

Практически примери: Изграждане на типове TypeScript с шаблони

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

1. Генериране на интерфейси от JSON схема

Разгледайте сценарий, в който получавате данни от REST API, който отговаря на определена JSON схема. Вместо ръчно да пишете съответния интерфейс на TypeScript, можете да използвате шаблон, за да го генерирате автоматично.

JSON схема (пример):

            {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Product",
  "description": "A product from an e-commerce platform",
  "type": "object",
  "properties": {
    "productId": {
      "type": "integer",
      "description": "Unique identifier for the product"
    },
    "productName": {
      "type": "string",
      "description": "Name of the product"
    },
    "price": {
      "type": "number",
      "description": "Price of the product"
    },
    "currency": {
      "type": "string",
      "description": "Currency of the price",
      "enum": ["USD", "EUR", "GBP", "JPY", "CAD", "AUD"]
    },
    "inStock": {
      "type": "boolean",
      "description": "Indicates if the product is in stock"
    },
    "imageUrl": {
      "type": "string",
      "format": "uri",
      "description": "URL of the product image"
    }
  },
  "required": ["productId", "productName", "price", "currency"]
}

            

              
                Copy
              
            
          

Handlebars шаблон (пример):

            
interface {{ title }} {
  {{#each properties}}
    /**
     * {{ description }}
     */
    {{ @key }}: {{#switch type}}
      {{#case 'integer'}}number{{/case}}
      {{#case 'string'}}string{{/case}}
      {{#case 'number'}}number{{/case}}
      {{#case 'boolean'}}boolean{{/case}}
      {{else}}any{{/else}}
    {{/switch}};
  {{/each}}
}

            

              
                Copy
              
            
          

Генериран TypeScript интерфейс:

            
interface Product {
  /**
   * Unique identifier for the product
   */
  productId: number;
  /**
   * Name of the product
   */
  productName: string;
  /**
   * Price of the product
   */
  price: number;
  /**
   * Currency of the price
   */
  currency: string;
  /**
   * Indicates if the product is in stock
   */
  inStock: boolean;
  /**
   * URL of the product image
   */
  imageUrl: string;
}

            

              
                Copy
              
            
          

Този пример автоматизира създаването на интерфейса `Product`, осигурявайки безопасност на типовете и намалявайки вероятността от грешки. Циклите `{{#each properties}}` и `{{/each}}` итерират през свойствата на JSON схемата, а `{{#switch type}}` позволява преобразуване на типовете на JSON схемата в правилни типове Typescript.

2. Генериране на изброявания от списък със стойности

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

Списък с методи на плащане (пример):

            
const paymentMethods = [
  "credit_card",
  "paypal",
  "apple_pay",
  "google_pay",
  "bank_transfer"
];

            

              
                Copy
              
            
          

EJS шаблон (пример):

            
export enum PaymentMethod {
  <% paymentMethods.forEach(method => { %>
    <%= method.toUpperCase().replace(/ /g, '_') %> = '<%= method %>',
  <% }); %>
}

            

              
                Copy
              
            
          

Генериран TypeScript изброяване:

            
export enum PaymentMethod {
  CREDIT_CARD = 'credit_card',
  PAYPAL = 'paypal',
  APPLE_PAY = 'apple_pay',
  GOOGLE_PAY = 'google_pay',
  BANK_TRANSFER = 'bank_transfer',
}

            

              
                Copy
              
            
          

Този пример динамично генерира изброяването `PaymentMethod` от масива `paymentMethods`. Използването на EJS позволява вграждане на Javascript, осигурявайки гъвкав контрол. Екипът в Индия вече има същите стандарти за внедряване на методи на плащане като екипа в Бразилия.

3. Генериране на типове API клиент от спецификации на OpenAPI

За проекти, взаимодействащи с REST API, генерирането на дефиниции на типове за API заявки и отговори въз основа на спецификации на OpenAPI е мощна техника. Това значително намалява риска от грешки, свързани с типове, и опростява работата с API. Много инструменти автоматизират този процес.

OpenAPI спецификация (пример):

OpenAPI (по-рано Swagger) спецификация е машинно четим документ, който описва структурата на API. Примерна структура за GET заявка за подробности за продукта:

            
openapi: 3.0.0
info:
  title: Product API
  version: 1.0.0
paths:
  /products/{productId}:
    get:
      summary: Get product by ID
      parameters:
        - in: path
          name: productId
          schema:
            type: integer
          required: true
          description: ID of the product to retrieve
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
components:
  schemas:
    Product:
      type: object
      properties:
        productId:
          type: integer
          description: Unique identifier for the product
        productName:
          type: string
          description: Name of the product
        price:
          type: number
          description: Price of the product

            

              
                Copy
              
            
          

Инструмент за генериране на код (напр. OpenAPI Generator):

Инструменти като OpenAPI Generator (по-рано Swagger Codegen) могат автоматично да генерират код на TypeScript (интерфейси, класове, код на API клиент) от OpenAPI спецификация. Генерираният код обработва API повиквания, валидиране на типове и сериализация/десериализация на данни, значително опростявайки интеграцията на API. Резултатът е типово безопасни API клиенти за всички ваши екипи.

Генериран фрагмент от код (пример - концептуален):

            
interface Product {
  productId: number;
  productName: string;
  price: number;
}

async function getProduct(productId: number): Promise {
  const response = await fetch(`/products/${productId}`);
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  return await response.json() as Product;
}

            

              
                Copy
              
            
          

Този генериран код предоставя типово безопасна функция `getProduct`, която опростява API взаимодействията. Типовете се извличат автоматично от вашата OpenAPI дефиниция. Това поддържа проекта мащабируем и намалява когнитивното натоварване на разработчиците. Това намалява риска от грешки при промяна на API договора.

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

За да увеличите максимално ползите от създаването на типове, базирано на шаблони, помислете за тези най-добри практики:

• Проектирайте чисти и поддържани шаблони: Пишете шаблони, които са лесни за четене, разбиране и поддръжка. Използвайте коментари и правилно форматиране.
• Използвайте модулни шаблони: Разделете сложните шаблони на по-малки, многократно използваеми компоненти или части.
• Тествайте генерирания си код: Напишете модулни тестове за генерирания код, за да сте сигурни, че се държи според очакванията. Тестването е от решаващо значение за поддържане на качеството на кода.
• Управлявайте версиите на вашите шаблони: Управлявайте вашите шаблони под контрол на версиите (напр. Git), за да проследявате промените, да си сътрудничите ефективно и да се връщате към предишни версии, когато е необходимо. Това е особено важно в глобално разпределени екипи.
• Интегрирайте с процеса на изграждане: Автоматизирайте генерирането на код като част от вашия процес на изграждане, за да сте сигурни, че генерираният код е винаги актуален.
• Документирайте процеса си на генериране на код: Документирайте как работят вашите шаблони, данните, които използват, и изхода, който генерират.
• Помислете за обхвата: Определете кои части от вашето приложение се възползват най-много от генерирането на код. Не прекалявайте с проектирането и се съсредоточете върху областите, където то ще осигури най-голяма стойност.
• Обработвайте грешките грациозно: Внедрете обработка на грешки във вашите скриптове за генериране на код, за да улавяте неочаквани проблеми. Предоставяйте информативни съобщения за грешки.
• Преглеждайте и рефакторирайте: Редовно преглеждайте вашите шаблони и генериран код. Рефакторирайте, ако е необходимо, за да подобрите четимостта и поддръжката.
• Помислете за инструменти за генериране на код: Използвайте съществуващи инструменти за генериране на код, като Plop, Hygen или Yeoman, за да опростите работния си процес и да предоставите стабилни функции на инструментите, които са жизненоважни, когато работите в големи, разпределени екипи.

Ползи за международна разработка на софтуер

Генерирането на код в TypeScript, базирано на шаблони, е особено ценно в международни среди за разработка на софтуер:

• Стандартизирани модели на данни: Гарантира, че всички екипи по света работят със същите модели на данни, минимизирайки проблемите с интеграцията.
• Опростени API интеграции: Автоматизираното генериране на API клиент въз основа на спецификации на OpenAPI гарантира консистентност и намалява риска от грешки при интегриране с API от различни региони или доставчици.
• Подобрено сътрудничество: Централизираните шаблони насърчават по-добро сътрудничество, тъй като разработчиците на различни места могат лесно да разберат и променят процеса на генериране на код.
• Намалени грешки при локализация: Помага за предотвратяване на грешки, свързани с локализацията (напр. формати на дати, символи на валути), като предоставя консистентни структури от данни.
• По-бързо включване: Новите членове на екипа могат бързо да разберат структурата на проекта, като разгледат шаблоните и генерирания код.
• Консистентен стил на код: Автоматизираното генериране на код може да наложи консистентен стил на код във всички проекти, независимо от местоположението на екипа за разработка.

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

Въпреки че генерирането на код предлага много предимства, има и някои предизвикателства и съображения:

• Сложност: Проектирането и поддържането на шаблони може да бъде сложно, особено за сложни задачи за генериране на код. Прекалено сложните шаблони могат да бъдат трудни за отстраняване на грешки.
• Крива на обучение: Разработчиците трябва да научат езика за шаблони и инструментите, използвани за генериране на код, което изисква първоначална инвестиция на време и усилия.
• Зависимости на шаблони: Шаблоните могат да станат зависими от конкретни версии на формати на данни или API спецификации. Управлявайте старателно версиите на входните си данни.
• Свръхгенериране: Избягвайте свръхгенерирането на код. Генерирайте само код, който наистина е повтарящ се и се възползва от автоматизацията.
• Тестване на генериран код: Тествайте старателно генерирания код, за да осигурите неговото качество и да предотвратите регресии.
• Отстраняване на грешки в генериран код: Отстраняването на грешки в генериран код понякога може да бъде по-трудно от отстраняването на грешки в ръчно написан код. Уверете се, че имате ясни стратегии за отстраняване на грешки.

Заключение

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