Express API з типобезпекою за допомогою Zod та OpenAPI в одному контракті

У цьому посібнику створюється функціональний шлях для розробки безпечного за типами Express API за допомогою Zod та OpenAPI. Основна увага приділяється контрактам, перевіркам та коду, який можна просто додати до репозиторію, не здогадуючись про його призначення. Для загального огляду перед зміною коду необхідно визначити вхідні дані, виконавця кроку та критерії завершення. Виконавці мають мати можливість перезапустити крок з відомої точки контролю, не здогадуючись про прихований стан. Краще використовувати невеликі, тестирувані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру обробки даних.

Ідея

Для реалізації цієї ідеї необхідно перед зміною коду визначити вхідні дані, власника кроку та критерії завершення. Оператори мають мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Розглядайте цю стадію як контракт між вхідними даними та перевіреними результатами. Призначте назви елементів, визначте критерії успіху та не допускайте беззвучного часткового завершення. Перевіряйте дані на межах за допомогою схем, які також генерують документацію. Одне джерело істини уникне розбіжностей між OpenAPI та обробниками.

const CreateUserSchema = z.object({
  name: z.string(),
  email: z.string().email(),
});

api.post("/users", {
  body: CreateUserSchema,
  response: {
    201: UserSchema,
  },
  handler: async (req) => {
    const user = await createUser(req.body);
    return {
      status: 201,
      body: user,
    };
  },
});

Чому створювати ще одну бібліотеку Express?

У розділі «Чому створювати ще одну бібліотеку Express?» необхідно визначити вхідні дані, виконавця кроку та критерії завершення перед зміною коду. Оператори мають мати можливість перезапустити крок з відомої точки контролю, не намагаючись здогадатися про прихований стан. Записуйте час виконання та витрати поруч із функціональними результатами. Раннє відстеження допомагає уникнути несподіваних рахунків, коли процес переходить від демо-середовища до спільних. Перевіряйте дані на межах за допомогою схем, які також генерують документацію. Одне джерело істини краще, ніж розбіжності між OpenAPI та обробниками.

Як це працює зараз

У проекті «Where it is today» необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість знову запустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Конфігурацію слід тримати окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функціоналу мають знаходитися в одному місці, яке оператори можуть перевіряти, не читаючи весь код. Перевіряйте дані на межах за допомогою схем, які також генерують документацію. Єдине джерело істини уникне розбіжностей між OpenAPI та обробниками. У проекті «Where it is today» необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість знову запустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Віддавайте перевагу невеликим, тестованим одиницям коду перед об’ємними скриптами. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру обробки даних.

Вам буде корисна зворотність від розробників

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

Чек-лист для експлуатації

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

Документуйте одночасно шлях успішної роботи та шлях відновлення. Повторні спроби, людські контролі та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.

Повертайте структуровані помилки, на основі яких клієнти можуть приймати рішення. Недостатнє формалізування типів призводить до необхідності здогадок.

Віддавайте перевагу нудній надійності перед кмітливими одноразовими демонстраціями.

Віддавайте перевагу малим, тестованим одиницям коду перед величезними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій.

Повертайте структуровані помилки, на основі яких клієнти можуть приймати рішення. Недостатнє формалізування типів призводить до необхідності здогадок.

Перш ніж переходити на нову версію технологій, заморозьте існуючі версії, зафіксуйте ідеальний запис дій для критичного шляху та підтвердьте кроки для відкату. У спільних середовищах необхідні обмеження на частоту запитів, перевірки прав доступу та чіткий власник для зміни секретів. Віддавайте перевагу нудній надійності перед кмітливими одноразовими демонстраціями.