Как построить рабочую архитектуру на Angular и NestJS

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

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

Отделите взаимодействие в браузере от полномочий сервера

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

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

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

Пусть явный контракт API порождает клиентский код

Выберите источник контракта, который независимые потребители могут проверить. OpenAPI хорошо подходит для API с парами запрос-ответ; GraphQL и схемы событий имеют другие средства, но одинаковую обязанность: описывать обмен данными по сети, а не внутренние классы TypeScript. Укажите обязательные поля и поля, допускающие пустое значение, форматы, перечни значений, разбиение на страницы, формы ошибок и примеры. Спецификацию можно получить из декораторов NestJS, но границу системы определяет именно опубликованный материал.

Создавайте узкоспециализированный клиент Angular или типы передачи данных во время CI и останавливайте проверку совместимости, если изменение удаляет или переосмысливает действующее поведение. Создание типов не заменяет проверки во время выполнения: сервер должен отклонять неверные входные данные, а клиенты — обрабатывать ответы от разных версий в период постепенного выпуска. Не публикуйте сущности базы данных или объекты предметной области как модели сетевого обмена: они меняются по другим причинам.

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

Охватите аутентификацией весь путь сеанса

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

Защитники маршрутов Angular улучшают навигацию, но не дают права на данные. NestJS обязан аутентифицировать каждый защищенный запрос и проверять разрешения на уровне ресурса и действия. Различайте ответ для неаутентифицированного пользователя и аутентифицированного пользователя без нужных прав, предотвращайте перенаправление на произвольный адрес, защищайте изменения состояния через файлы сеанса от CSRF и ограничивайте одновременное обновление, чтобы несколько неудачных запросов не вызвали лавину маркеров.

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

Придайте ошибкам устойчивый смысл и понятное восстановление

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

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

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

Согласуйте состояние клиента с достоверными данными сервера

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

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

Явно описывайте длительные операции. Возвращайте идентификатор задания, предоставляйте состояние и результат и определяйте отмену, устранение повторов и срок действия вместо того, чтобы держать запрос браузера открытым. Для обновлений в реальном времени выбирайте периодические запросы, события от сервера или WebSockets в соответствии с требованиями к скорости и масштабу. После восстановления связи продолжайте с известной позиции и сверяйте пропущенные события: сам по себе живой канал не является источником истины.

Установите четкую и безопасную границу SSR

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

На сервере используйте узкоспециализированный клиент API с явно заданными учетными данными и сроками ожидания. Никогда не пересылайте входящий файл сеанса или заголовок авторизации на произвольные адреса. Разделяйте ключи хранения для общедоступных данных, организаций и пользователей; не сохраняйте персонализированный HTML в общем слое. Передавайте браузеру только безопасные данные, необходимые для подключения логики, защищайте сериализованное состояние и не заставляйте Angular без необходимости повторять тот же запрос.

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

Прослеживайте весь путь от браузера до зависимой службы

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

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

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

Развертывайте Angular и NestJS как совместимые версии

Angular и NestJS можно развертывать независимо лишь тогда, когда их контракты остаются совместимыми в период одновременной работы разных версий. Сначала добавляйте поля, а уже потом используйте их; сохраняйте старое поведение в течение определенного срока и удаляйте после того, как использование снизится до нуля. Изменения базы данных проходят этапы расширения, переноса и сокращения: разверните совместимую схему, заполните новые данные и переключите чтение или запись, прежде чем удалять старое представление.

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

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

• Полномочия: Angular управляет взаимодействием и представлением; NestJS проверяет удостоверение, разрешения и ход процесса и сохраняет достоверное состояние.
• Контракты: публикуйте схему сетевого обмена, создавайте узкие клиенты и проверяйте совместимость, пока одновременно работают разные версии.
• Удостоверение: опишите весь путь входа, обновления, отказа, отзыва и выхода; сервер должен проверять права на каждый ресурс.
• Отказы: возвращайте устойчивые деловые коды и идентификаторы связи, а в интерфейсе предоставляйте доступное восстановление в соответствии с процессом.
• Состояние: определите идентичность и свежесть сохраненных данных, правила отмены, конфликты версий, безопасное повторение команд и сверку с достоверным источником.
• Эксплуатация: классифицируйте маршруты SSR, передавайте контекст отслеживания и выпускайте с возможностью возврата совместимые изменения API и базы данных.