Интеграция frontend с backend API¶
Требования этого документа применяются к вызовам backend API из browser, SSR,
SSG и edge-точек входа frontend-приложений по
frontend/rendering-profiles.md. Требование, явно называющее browser или
пользовательский экран, применяется только к browser-части. Уровни
обязательности определены в корневом README.md.
FE-API-001. Объявленный контракт и версия backend API¶
Уровень: MUST
Применяется к: каждой интеграции с backend API
Проект должен фиксировать версию и источник потребляемого API-контракта. Клиент API должен генерироваться или проверяться по версионируемому контракту, а CI — проверять соответствие клиента контракту. Изменение ожидаемого контракта должно быть явным и проверяемым.
Обоснование¶
Явный контракт делает рассогласование клиента и API обнаружимым до поставки.
Проверка¶
- review источника контракта и версии;
- contract-тест клиента против контракта;
- проверка gate на изменение контракта в CI.
Исключения¶
Контракт без опубликованной схемы требует утверждённого ADR и эквивалентной автоматической проверки.
FE-API-002. Толерантный потребитель API¶
Уровень: MUST
Применяется к: обработке ответа backend API
Клиент должен игнорировать неизвестные поля ответа, если они не меняют смысл известных полей. Неизвестное значение enum должно обрабатываться определённым fallback только для enum, объявленного контрактом расширяемым. Для закрытого enum добавление значения является несовместимым изменением и должно обнаруживаться проверкой контракта.
Сужение допустимых значений или изменение смысла существующего поля обрабатывается
как несовместимое изменение контракта в согласии с BE-COMP-001.
Обоснование¶
Независимая поставка frontend и backend требует устойчивости клиента к обратной
совместимости API по BE-COMP-001.
Проверка¶
- тест клиента с неизвестным полем и расширяемым значением enum;
- тест отклонения необъявленного значения закрытого enum;
- contract-тест совместимости с предыдущей версией ответа;
- review обработки ошибок декодирования.
Исключения¶
Не допускаются для tolerance к добавлению полей, не меняющих известную семантику.
FE-API-003. Конечные тайм-ауты вызовов¶
Уровень: MUST
Применяется к: каждому вызову backend API
Каждый ограниченный вызов должен иметь конечный timeout, заданный через поддерживаемый целевым runtime механизм отмены. Timeout должен учитывать бюджет вызывающей операции и быть обоснованным для неё. Превышение timeout должно приводить к отмене запроса и определённому результату для вызывающего кода, а для пользовательской операции — к определённому результату для пользователя.
Обоснование¶
Неограниченное ожидание оставляет пользователя без обратной связи и удерживает ресурсы.
Проверка¶
- unit-тест timeout и отмены запроса;
- тест поведения при зависшем ответе;
- review значений timeout по типам операций.
Исключения¶
Намеренно долгоживущий поток MAY не иметь общего timeout, если контракт определяет конечные timeout установления и отсутствия прогресса, а также условие завершения.
FE-API-004. Ограниченные повторы¶
Уровень: MUST
Применяется к: автоматическим retry вызова backend API
Retry допускается только для идемпотентной операции и явно классифицированной временной ошибки. Число попыток и общее время должны быть конечными, между попытками должны применяться backoff и jitter.
Ошибка валидации, аутентификации, авторизации, бизнес-правила и иной постоянный
отказ не должны повторяться. HTTP 408 Request Timeout и
429 Too Many Requests могут классифицироваться как временные; retry должен
учитывать Retry-After, если backend его передал. Другой 4xx не должен
повторяться без явного контрактного основания.
Обоснование¶
Неограниченные повторы усиливают перегрузку backend и дублируют эффекты; это
клиентский аналог BE-RES-002.
Проверка¶
- unit-тест классификации ошибок и числа попыток;
- integration-тест retry с временной и постоянной ошибкой;
- тест неидемпотентной операции при неопределённом результате.
Исключения¶
Retry неидемпотентной операции требует наличия ключа идемпотентности на стороне
backend по BE-HTTP-003.
FE-API-005. Сопоставление ошибок для пользователя¶
Уровень: MUST
Применяется к: неуспешному результату вызова backend API
Приложение должно сопоставлять технический исход вызова с определённым пользовательским результатом. Должны различаться валидация, отсутствие аутентификации, недостаточные права, отсутствие ресурса, конфликт, rate limit и технический отказ, если эти исходы применимы.
Приложение не должно раскрывать пользователю внутренние детали реализации, адреса зависимостей или текст ошибки backend. Ожидаемый бизнес-отказ не должен сообщаться как техническая ошибка.
Обоснование¶
Единое сопоставление соответствует классам ошибок по BE-HTTP-002 и не раскрывает
реализацию.
Проверка¶
- unit-тест матрицы сопоставления ошибок;
- integration-тест каждого класса исхода;
- review текстов, показываемых пользователю.
Исключения¶
Формат ошибки определяется опубликованным контрактом API проекта.
FE-API-006. Отмена запроса¶
Уровень: MUST
Применяется к: отмене вызова backend API
Приложение должно отменять запрос, когда результат более не имеет потребителя: при отмене родительской операции, завершении SSR- или edge-запроса, уходе с экрана либо размонтировании последнего browser-компонента-потребителя. Общий запрос нескольких потребителей не должен отменяться, пока его результат требуется хотя бы одному из них. Отмена должна распространяться во все поддерживающие её вложенные операции.
Отменённый запрос не должен регистрироваться как ошибка приложения.
Обоснование¶
Распространение отмены освобождает ресурсы и соответствует серверному принципу
BE-RES-003.
Проверка¶
- unit-тест отмены при размонтировании;
- проверка отсутствия ложной ошибки после отмены;
- review распространения сигнала отмены.
Исключения¶
Запрос, фиксирующий уже начатый необратимый эффект, должен завершаться по контракту операции, а не прерываться.
FE-API-007. Корреляция и распространение контекста трассы¶
Уровень: MUST
Применяется к: запросу к backend API внутри отслеживаемой frontend-операции
Клиент browser, SSR или edge должен передавать на разрешённые backend origins
контекст активной трассы в формате W3C Trace Context: traceparent и
tracestate, когда оно присутствует. Список origins должен быть закрытым, чтобы
контекст не передавался произвольному получателю. При использовании
request_id или correlation_id передаётся соответствующий идентификатор.
Идентификаторы должны формироваться инструментом трассировки, а не вручную. При отсутствии активной трассы не должны создаваться фиктивные идентификаторы.
Обоснование¶
Распространение контекста связывает frontend-операцию с ходом обработки на backend и наблюдаемостью сервера.
Проверка¶
- integration-тест наличия
traceparentв запросе; - тест отсутствия контекста на origin вне allowlist;
- сквозной поиск одной операции в трассах frontend-runtime и backend;
- проверка соответствия формата W3C Trace Context.
Исключения¶
Backend, контракт которого не принимает заголовки трассировки, должен фиксировать это в своём контракте.
FE-API-008. Свежесть данных после изменения прав¶
Уровень: MUST
Применяется к: данным, доступ к которым ограничен правами пользователя
При изменении прав, выходе из системы или истечении сессии приложение должно
недвусмысленно прекратить показ защищённых данных, полученных для предыдущего
состояния доступа. Стратегия кэширования и инвалидации должна быть определена и не
допускать показа данных, недоступных текущему субъекту. Browser storage
дополнительно выполняет FE-OFF-001, а HTTP cache — INT-CACHE-001–
INT-CACHE-003.
Обоснование¶
Кэшированные или сохранённые клиентом данные могут раскрыть защищённую информацию
после отзыва доступа; авторизация на backend по SEC-AUTHN-007 не покрывает уже
полученные клиентом данные.
Проверка¶
- тест выхода из системы и изменения прав;
- проверка очистки или инвалидации защищённых данных;
- review стратегии кэширования защищённых ресурсов.
Исключения¶
Публичные данные могут кэшироваться без привязки к правам.