Безопасные 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 и обработчиками.

Каково его текущее состояние

В текущей ситуации необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Проводите верификацию на границах с использованием схем, которые также генерируют документацию. Единый источник правды предотвращает расхождения между OpenAPI и обработчиками. В текущей ситуации необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину, а не на запутанную структуру обработки данных.

Вам понравится обратная связь от разработчиков

Чтобы вам понравилась обратная связь от разработчиков, определите входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия результатам работы, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение. Возвращайте структурированные ошибки, на основе которых клиенты могут принимать решения. Строгая типизация сбоев приводит к необходимости догадок.

Чек-лист операций

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

Документируйте одновременно путь успешной работы и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не последующими улучшениями.

Возвращайте структурированные ошибки, на основе которых клиенты могут принимать решения. Строгая типизация сбоев вынуждает к догадкам.

Даёте предпочтение простой надёжности перед креативными одноразовыми демонстрациями.

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

Возвращайте структурированные ошибки, на основе которых клиенты могут принимать решения. Строгая типизация сбоев вынуждает к догадкам.

Перед внедрением стека заморозьте версии, сохраните эталонный отчёт для критического пути и убедитесь в наличии шагов отката. В совместных средах необходимы ограничения по частоте запросов, проверки аренды ресурсов и чёткий ответственный за обновление секретов. Даёте предпочтение простой надёжности перед креативными одноразовыми демонстрациями.