Надёжные REST API на NestJS: правила проектирования

Надёжный API ведёт себя предсказуемо, когда клиенты повторяют запросы, отправляют неверные данные, действуют одновременно, обновляются в разное время или сталкиваются с частичным отказом. Названия ресурсов — лишь видимая часть. Более глубокий контракт охватывает семантику методов, авторизацию, проверку данных, порядок, представление времени и денег, коды ошибок, поведение при повторной отправке, совместимость и операционные доказательства.

NestJS даёт командам согласованный способ выразить этот контракт через контроллеры, конвейеры преобразования, защитники маршрутов, перехватчики, фильтры исключений, модули и интеграцию с OpenAPI. Эти механизмы не определяют, где начинается транзакция, какая служба отвечает за факт, можно ли повторить команду и какое изменение нарушит работу потребителя. Надёжность возникает тогда, когда такие решения сформулированы явно и применяются последовательно.

Начинайте с путей потребителей и неизменных правил предметной области. Для каждой конечной точки назовите участника, ресурс или команду, допустимое состояние, проверку полномочий, ограничения входных данных, атомарное изменение, ответ, заметные побочные последствия, правило повтора и режимы отказа. Оставляйте вопросы передачи данных на границе, а деловые решения — в прикладных службах или службах предметной области. Наши услуги по разработке на NestJS используют это разделение, чтобы HTTP мог развиваться, не превращая каждый выпуск клиента в согласованную аварийную операцию.

Осознанно моделируйте ресурсы и семантику HTTP

Используйте для ресурсов устойчивые деловые существительные: /orders/{orderId}, /customers/{customerId}/addresses или /invoices/{invoiceId}/payments. Вкладывайте подресурс лишь тогда, когда связь с родительским ресурсом меняет его идентичность, авторизацию или жизненный цикл. Глубокие пути, повторяющие соединения таблиц базы данных, раскрывают способ хранения и становятся хрупкими после изменения ответственности.

Не каждое деловое действие является обновлением поля. Моделируйте отмену, согласование, импорт или создание отчёта как ресурс, если оно имеет собственное состояние, разрешения, результат или историю аудита: POST /orders/{orderId}/cancellations говорит больше, чем общий /execute. Сохраняйте контроллеры тонкими. Они разбирают транспортные данные, вызывают правила и сценарии использования, затем преобразуют результаты; они не должны координировать транзакции базы данных или дублировать правила предметной области в разных маршрутах.

Применяйте методы HTTP согласно их семантике. GET и HEAD должны быть безопасными. PUT заменяет состояние известного целевого представления и по определению является идемпотентным; PATCH применяет документированное частичное изменение; DELETE требует чётких правил повтора и обозначения удалённого ресурса; POST выполняет зависящую от ресурса обработку и не является идемпотентным по своей природе. Не используйте GET для действия лишь потому, что его удобно вызывать из браузера.

Выбирайте коды состояния как часть контракта. Синхронное создание обычно возвращает 201 с Location; принятая фоновая работа — 202 и ресурс состояния; 204 не содержит ответа; 400 описывает неправильно сформированные или недопустимые по правилам данные согласно вашему соглашению; 401 и 403 отделяют отсутствующую личность от нехватки полномочий; 404 может намеренно скрывать защищённый ресурс; 409 обозначает конфликт состояния; 412 соответствует невыполненному условию запроса; а 429 или 503 должны объяснять, целесообразен ли повтор. Единая последовательная политика важнее споров о соседних допустимых кодах для каждой конечной точки.

Проверяйте каждую внешнюю границу

Одни типы TypeScript не защищают API во время выполнения. Проверяйте каждое недоверенное тело, параметр пути, значение запроса, заголовок, файл, уведомление о событии и утверждение из декодированного токена до того, как оно повлияет на запрос к данным или деловое решение. NestJS поддерживает классы DTO, отмеченные декораторами через ValidationPipe и схемы времени выполнения с помощью средств, совместимых со Standard Schema. Выберите один понятный подход для каждой границы и оставляйте его правила времени выполнения видимыми.

При использовании классов DTO помните, что интерфейсы, обобщённые типы и импорты только для типов исчезают во время выполнения. Глобальный ValidationPipe может преобразовывать значения, удалять необъявленные свойства или отклонять их с помощью forbidNonWhitelisted. Проверка по схеме может вывести типы TypeScript из схемы времени выполнения и определить строгое, очищающее или разрешительное поведение объектов. В каждой модели преобразование типов должно быть осознанным: значения строки запроса приходят как строки, а пустая строка, неверная дата или "false" никогда не должны неожиданно становиться истинным флагом.

Разделяйте модели создания, полной замены, частичного изменения, запроса и ответа. Отсутствующее значение и null должны иметь разные документированные значения. Представляйте деньги целым числом наименьших единиц или по чётким правилам десятичных чисел и всегда указывайте валюту; для времени установите соглашение о часовом поясе; проверяйте перечисления и идентификаторы без догадок. Ограничивайте длину строк, массивы, глубину объектов, размер файлов и страниц, диапазоны дат и пакетные команды, чтобы структурно правильные данные не могли потребовать неограниченных ресурсов процессора, памяти или базы данных.

Проверка данных отвечает на вопрос, имеют ли они ожидаемую форму. Авторизация определяет, может ли это лицо действовать с конкретным объектом; неизменные правила предметной области — допустим ли переход именно сейчас. Никогда не привязывайте данные запроса непосредственно к сущности ORM и не переносите все их поля без разбора в операцию обновления. Перенесите разрешённые поля в команду, загрузите достоверное состояние, примените правила доступа к объекту и неизменные правила, затем верните явный DTO ответа или модель чтения.

Сделайте разбиение на страницы и фильтрацию однозначными

Каждой коллекции нужны ограниченный типовой и максимальный размер страницы и полный порядок. Разбиение со смещением просто, поддерживает номера страниц и может быть уместным для умеренных, относительно стабильных административных наборов данных. Большие смещения могут вызвать ресурсоёмкое сканирование, а одновременное добавление или удаление — переместить строки между страницами и создать повторы либо пропуски.

Курсорное разбиение подходит для длинных или меняющихся потоков, если курсор содержит все ключи сортировки и уникальный дополнительный ключ, например (createdAt, id). Следующий запрос должен воспроизводить те же фильтры и лексикографическое сравнение. Считайте курсор непрозрачным, управляйте версиями его содержимого, защищайте целостность и определяйте направление. Курсор, кодирующий только неуникальную временную отметку, со временем начнёт пропускать или повторять записи.

Разрешайте только определённые параметры фильтрации, поиска, присоединения, выбора полей и сортировки. Документируйте операторы, поведение регистра и ударений, границы часовых поясов, порядок значений null и то, означают ли повторные фильтры AND или OR. Преобразуйте параметры через явную модель запроса вместо приёма названий столбцов или произвольных фрагментов SQL. Добавляйте индексы для измеренных способов доступа и ограничивайте дорогие диапазоны дат, развёртывание связей, поиск с произвольными подстановочными знаками и размер выгруженных результатов.

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

Проектируйте идемпотентность и одновременные изменения вместе

Сеть может отказать после того, как сервер зафиксировал изменение, но до получения ответа клиентом. Клиент не знает, существует ли платёж, заказ, бронирование или задание, поэтому обоснованный повтор способен создать дубликат. Для чувствительных к повтору команд POST принимайте ключ идемпотентности, ограниченный аутентифицированным лицом, операцией и часто клиентской организацией.

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

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

Идемпотентность предотвращает повторное выполнение одной и той же команды, но не разрешает соперничество двух разных допустимых команд за изменение одного ресурса. Предотвращайте потерянные обновления с помощью поля версии, сильного ETag вместе с If-Match, команды с ожидаемым состоянием или условия базы данных при обновлении. Возвращайте 412 при невыполнении условия HTTP или документированный конфликт 409, после чего клиент должен повторно загрузить состояние и принять решение. Ограничения уникальности предметной области по-прежнему защищают такие факты, как одна активная подписка или одна внешняя ссылка.

Сохраняйте ошибки полезными, устойчивыми и безопасными

Определите единую структуру ошибки с устойчивым машиночитаемым кодом, безопасным сообщением для человека, идентификатором запроса или трассировки и необязательными сведениями об ошибках в отдельных полях. Клиенты разветвляют поведение по состоянию и коду, а не по переведённому тексту. Сохраняйте коды на уровне решений, которые может принять потребитель: исправить данные, пройти аутентификацию, запросить доступ, повторно загрузить состояние, подождать, повторить действие или обратиться в поддержку.

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

Не раскрывайте стеки вызовов, SQL, названия таблиц, внутренние узлы, учётные данные, токены, необработанные данные поставщика или чувствительные значения проверки. Отказ авторизации не должен сообщать, принадлежит ли идентификатор другой клиентской организации. Записывайте безопасный код ошибки, операцию, длительность, выпуск, категорию зависимости и данные связи, необходимые для расследования; чувствительные поля удаляйте, а число значений меток показателей ограничивайте.

Контракт ошибок становится действенным лишь тогда, когда кто-то видит закономерности. Измеряйте частоту и задержку по конечной точке, классу кода состояния, устойчивому коду, зависимости, версии клиента и выпуску. Оповещайте о влиянии на клиентов и длительном отклонении, а не о каждой отдельной ошибке 4xx. Прослеживайте запрос между службами и асинхронной работой, сохраняя один и тот же безопасный идентификатор связи.

Развивайте контракт и проверяйте OpenAPI

Отдавайте предпочтение совместимому развитию: добавляйте необязательные поля ответа, вводите новые конечные точки, ослабляйте требования к входным данным только тогда, когда это остаётся безопасным, и расширяйте перечисления лишь при условии, что потребители обрабатывают неизвестные варианты. Изменение смысла может нарушить работу клиента, даже если форма JSON осталась прежней. Переименование, удаление, ужесточение требования, изменение допустимости null, значений по умолчанию, порядка результатов, видимости по правилам авторизации или назначения кода ошибки требуют проверки совместимости.

Вводите версию, когда обязательный контракт нужно нарушить и необходимо сосуществование. NestJS поддерживает версию в URI, заголовке, типе мультимедиа и собственный способ её определения. Выберите одну видимую политику, определите версию по умолчанию и поведение для неподдерживаемой, версионируйте наименьшую целостную часть контракта. Опубликуйте срок прекращения поддержки, рекомендации по замене, ответственного за поддержку и условие удаления. Наблюдайте за использованием аутентифицированными клиентами вместо предположения, что старый маршрут никому не нужен.

Где возможно, создавайте OpenAPI из тех же контроллеров и контракта времени выполнения, признавая ограничения отражения типов. Опишите аутентификацию, ожидания в отношении авторизации, форматы, ограничения, примеры, коды ошибок, разбиение на страницы, условные заголовки и идемпотентность. Сохраняйте DTO ответа явными, чтобы столбцы и связи хранилища незаметно не попали в спецификацию. Рассматривайте созданный документ как составляющую продукта, а не как украшение Swagger UI.

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

Перечень проверок REST API

• Семантика и ответственность: ресурсы, методы, коды состояния, авторизация, переходы состояний, границы транзакций и побочные последствия соответствуют документированному поведению предметной области.
• Ограниченные входные данные: тела, параметры, запросы, заголовки, файлы и уведомления о событиях проверяются во время выполнения; неизвестные поля и неоднозначное преобразование типов подчиняются явным правилам.
• Стабильные коллекции: порядок является полным, разбиение на страницы — ограниченным, курсоры — непрозрачными и правильными, фильтры — в перечне разрешённых, а индексы соответствуют измеренным способам доступа.
• Безопасный повтор: чувствительные к повтору команды используют надёжную идемпотентность; одновременные записи — предварительные условия, версии или ожидаемое состояние; уникальность предметной области по-прежнему обеспечивается.
• Проверенное развитие: ошибки и OpenAPI устойчивы и машиночитаемы; CI проверяет совместимость; проверки контрактов, телеметрия, прекращение поддержки и данные об использовании клиентами помогают управлять изменениями.