Англійська для розробників ts-rest

ts-rest дозволяє командам визначити форму REST API один раз, як контракт TypeScript, і отримати тип-безпечний клієнт, тип-безпечні серверні обробники, і специфікацію OpenAPI, все створене з цього єдиного джерела — без відмови від REST конвенцій для RPC. Оскільки він навмисно зберігає семантику REST (реальні HTTP дієслова, реальні коди стану), додаючи безпеку типу, перегляд розмов змішує лексику REST з контрактною лексикою. Вот английский, который тебе нужен.

---

Contracts

Contract — єдине визначення TypeScript маршрутів, методів, тіл запитів і відповідей REST API, з яких генерується або перевіряється як серверний, так і клієнтський код.

“Не змінюйте тип повернення обробника маршрутів безпосередньо — спочатку оновіть контракт, і дозвольте типу помилки вести вас до кожного місця, яке потрібно змінити.”

** Визначення маршруту ** — один запис у контракті, що описує одну кінцеву точку: її шлях, метод HTTP, параметри шляху/ запиту, схему тіла і можливі форми відповіді за кодом стану.

• “Додати нове визначення маршруту для кінцевої точки експорту замість перевантаження існуючого маршруту GET /reports прапорцем запиту.” *

** Суворий режим ** — параметр контракту, який відкидає будь- який код стану відповіді або форму, які не було явно оголошено, захоплюючи недокументовану поведінку під час компіляції або виконання.

• “Ввімкнути строгий режим для цього контракту — зараз обробник може беззвучно повернути недокументовану форму 500 і нічого не захопить її.” *

---

Клієнти і сервери

** Клієнт безпечного типу ** — клієнт API, який автоматично створюється з контракту, отже виклик кінцевої точки з неправильною формою аргумента або читання поля відповіді, якого не існує, є помилкою TypeScript під час компіляції.

• “Вам не потрібно перевіряти документацію на наявність форми відповіді — клієнт безпечного типу вже повідомляє вашому редактору, які поля існують.” *

** Реалізація маршрутизатора ** — об’ єкт на стороні сервера, який відображає визначення кожного маршруту у контракті у функцію обробки, з ts- rest, що забезпечує реалізацію кожного маршруту у контракті.

“Збирання зазнало невдачі, оскільки контракт додав новий маршрут, а реалізація маршрутизатора ще не наздоганяє — це очікувано, а не помилка.”

** Форма відповіді на код стану ** — шаблон декларування окремої схеми відповіді для кожного можливого коду стану HTTP (200, 404, 422), який може повернути маршрут, замість одного вільного типу « відповіді ».

“Не згортати випадки 404 і 200 в одне додаткове поле — декларуйте їх як окремі форми відповіді, щоб клієнт міг звузити код стану.”

---

Інтерфейс OpenAPI

** OpenAPI generation ** — автоматичне створення стандартної специфікації OpenAPI/Swagger з контракту, тому зовнішні команди або інструменти, які не використовують TypeScript, все ще можуть використовувати точні документи API.

“Ми припинили писати файл Swagger від руки — він створений з того ж контракту, який використовує клієнт TypeScript, тому вони не можуть розходитися.”

** Перевірка схеми ** — перевірка під час виконання (зазвичай за допомогою Zod), що вхідні запити і вихідні відповіді відповідають формам, оголошеним у контракті, а не тільки під час компіляції.

“Цей помилково сформований запит не був виявлений до виробництва, оскільки перевірка схеми не була вбудована в обробник — контракт гарантував лише безпеку під час компіляції, а не під час виконання.”

Поширені помилки

• Сказати « типи не збігаються » без вказівки, чи не збігається це в контракті, реалізації маршрутизатора, або створеному клієнті — кожен вказує на інший файл.
• Припускаючи безпеку типу під час компіляції з контракту також гарантується перевірка під час виконання, коли перевірка схеми повинна бути явно впроваджена в сервер.
• Забув, що створення OpenAPI і клієнт TypeScript походять з одного і того ж контракту, а потім вручну редагував створену специфікацію і беззвучно її перезаписав.

Практичні вправи

1. Поясніть у двох реченнях, чому ts- rest може створювати як типовий клієнт, так і специфікацію OpenAPI з одного контракту.
2. Написати короткий опис PR для додавання строгого режиму до існуючого контракту, який повертав недокументовані форми помилок.
3. Написати коментар перегляду коду, у якому буде пояснено, чому відповідь 404 має бути самостійною заявленою формою, а не додатковим полем у відповіді 200.

Зв’язані ресурси

• Англійська для розробників TypeScript
• Англійська мова для API Design Reviews
• Англійська для GraphQL з персистентними запитами

Національний склад населення: Перепис населення та проживання

Будьмо чесними - навіть досвідчені розробники з рідною англійською мовою борються з точною мовою, необхідною для ефективного спілкування про технічні деталі. Під час роботи над проектом з використанням ts-rest, чітке і коротке спілкування не просто ввічливе; це безпосередньо впливає на якість коду, зменшує непорозуміння і спрощує співпрацю. Недостатньо просто сказати «це не працює». Вам потрібно сформулювати * чому * це не працює, і запропонувати рішення таким чином, щоб воно було легко зрозумілим для всієї команди. Це особливо важливо при обговоренні контрактів і того, як вони пов’язані зі сформованим клієнтом кодом.

Поширений сценарій виникає під час перегляду коду. Уявіть, що ви отримали такий коментар щодо запитів на завантаження: « Ця кінцева точка не відповідає контракту; у ній відсутня перевірка minLength ». Тепер, менш лаконічною відповіддю може бути щось на зразок « Виправлено ». Але це не пояснює * чому * було внесено зміну або як вона збігається з дизайном. Кращий підхід буде таким: «Я додав перевірку minLength до схеми тіла запиту згідно з визначенням контракту для /users/{id}. Цей параметр забезпечує виконання кінцевою точкою вимог щодо вказаного типу даних і їх довжини, запобігаючи обробці некоректних даних. Я також оновив сформований клієнтський код, щоб відобразити цю зміну, забезпечивши послідовність у нашому API. ” Зауважте наголос на тому, * чому * зміна була необхідна і як вона пов’язана з початковим договором. Аналогічно, на каналі Slack, де обговорюються потенційні поліпшення визначення OpenAPI, ви можете почути, як хтось пропонує: «Давайте зробимо відповідь трохи більш детальною». Це неоднозначно. Корисним продовженням буде: “Чи можемо ми визначити поля, що повертаються за замовчуванням, і їхні типи даних явно? Це покращить документацію для наших споживачів API і зменшить потенційну неоднозначність»

Іншою критичною областю є створення чітких описів запитів на завантаження. Замість того, щоб просто сказати «Реалізована кінцева точка X», хороший опис пояснює що було реалізовано, чому і як це вписується в більш широку архітектуру. Наприклад: «Впроваджено кінцеву точку /products/{id}/reviews, щоб дозволити клієнтам створювати нові відгуки про продукти. Це відповідає контракту API, визначеному в product-review.yaml, забезпечуючи послідовну перевірку даних і генерацію клієнтського коду для створення перегляду. Кінечна точка використовує запит POST з тілом JSON, відповідним схемі, який автоматично генерується ts-rest на основі контракту.”

Ось приклад того, як ви можете використовувати ts-rest для створення базового визначення OpenAPI з контракту TypeScript:

import { Contract } from 'ts-rest';

const myContract = new Contract({
  path: '/users',
  methods: [
    {
      method: 'GET',
      description: 'Retrieves a user by ID.',
      params: [{ name: 'id', type: 'string' }],
      responses: {
        200: { description: 'User found.' },
        404: { description: 'User not found.' }
      }
    }
  ]
});

myContract.save('users.openapi.ts');

Цей приклад ілюструє, як контракт безпосередньо інформує визначення OpenAPI, демонструючи основний принцип використання ts-rest для покращення ясності і послідовності. Сфокусування на цих точних фразах - “як за договором”, “примушує типи даних”, “відображає дизайн” - значно поліпшить ваше спілкування і співпрацю при роботі з безпечними типами REST API.