Когда frontend и backend на PHP разрабатываются или развёртываются отдельно, каждая команда может выпускать изменения в собственном темпе. Такая автономность помогает организовать работу, но создаёт и точку трения: интерфейс может ожидать поле, формат или состояние, которые API уже не возвращает. Решение не в том, чтобы обе команды всегда меняли всё одновременно, а в явном контракте, чётко разграниченных обязанностях и тестах, проверяющих реальное использование интеграции.
Контракт между frontend и backend на PHP описывает данные и поведение, которые одна сторона предоставляет, а другая использует. Это не просто список маршрутов: контракт включает методы, параметры, схемы ответов, ошибки, права доступа и правила совместимости. Цель — дать каждой стороне возможность развиваться, не завися от внутренних деталей другой.
Почему независимые версии создают трения
Интерфейс и сервер могут выпускаться с разной периодичностью, и новая версия может поступать не всем пользователям одновременно. Закэшированный frontend может продолжать отправлять старый запрос после обновления backend. Возможна и обратная ситуация: API получает новую возможность, о которой интерфейс ещё не знает.
Несовместимости часто возникают из-за изменений, которые кажутся незначительными: переименования свойства, преобразования числа в строку, смены необязательного поля на обязательное, изменения формата даты или возврата ошибки в другой структуре. Изменение может быть допустимым для серверного кода и при этом нарушить работу существующих потребителей.
Важно отличать реализацию от контракта. Backend может менять базу данных или реорганизовывать внутренние сервисы, не затрагивая API, если сохраняет опубликованное поведение. Аналогично, frontend может полностью переработать компоненты без необходимости менять бизнес-правила.
Обязанности интерфейса, API и домена
Интерфейс отвечает за пользовательский опыт: отображает информацию, помогает пользователю, сразу сообщает об ошибках формата и управляет визуальными состояниями — загрузкой, успехом или отсутствием результатов. Такие проверки улучшают взаимодействие, но не являются защитным барьером: запросы можно изменить или отправить, не используя официальный интерфейс.
API обеспечивает взаимодействие между внешним протоколом и приложением. Оно проверяет структуру запроса, при необходимости аутентифицирует пользователя или проверяет его права, преобразует данные и возвращает предсказуемые ответы. Представление данных должно оставаться стабильным, даже если меняются внутренние классы или схема хранения.
Домен содержит правила, определяющие допустимые для бизнеса операции: например, разрешён ли переход состояния или требуется ли для операции предварительное условие. Такие правила не должны существовать только в JavaScript или независимо дублироваться в разных контроллерах. Backend обязан обеспечивать их выполнение, поскольку именно он принимает или отклоняет операцию.
Для ориентации пользователя интерфейс может предварительно проверить правило, но окончательная проверка выполняется повторно на сервере. Визуальная проверка не заменяет валидацию и авторизацию на backend.
Определение входных данных, выходных данных, ошибок и состояний
Для каждой операции задокументируйте как минимум метод и маршрут, параметры, обязательные и необязательные поля, типы, форматы, важные ограничения и структуру ответа. Также уточните, что означает отсутствие поля, значение null или пустой список: это не всегда взаимозаменяемые состояния.
Ответ должен передавать потребителю понятный результат, а не раскрывать детали реализации. Согласуйте HTTP-коды и единую структуру ошибки со стабильным кодом или категорией, подходящим для интерфейса сообщением и, если уместно, ошибками, связанными с конкретными полями. Не раскрывайте трассировки, SQL-запросы и конфиденциальную информацию. Вместо зависимости от внутренних текстов, которые могут измениться, frontend может сопоставлять известные коды с локализованными сообщениями.
Опишите также состояния, влияющие на ход работы: отсутствующий ресурс, отказ в доступе, конфликт с текущим состоянием, ошибка валидации или ограничение числа запросов, если применимо. Для данных с пагинацией определите, как представляются результаты, лимиты и механизм продолжения выдачи. Для дат укажите формат и часовой пояс; для денежных сумм — валюту и единицу измерения. Чем меньше каждой команде приходится полагаться на предположения, тем ниже вероятность расхождений.
Валидация на обоих уровнях без дублирования доменной логики
Некоторые проверки стоит повторять, поскольку они служат разным целям. Интерфейс может проверить, что обязательное поле не пусто, прежде чем отправить форму; API должно проверить это снова, чтобы принимать только корректные запросы. Первая проверка упрощает взаимодействие, вторая защищает целостность системы.
Нет необходимости дублировать во frontend всю доменную логику. Если правило сложное, часто меняется или зависит от данных сервера, оставьте его авторитетную реализацию на backend и возвращайте ошибку, на которую можно дать понятный ответ. Если интерфейсу нужно заранее оценить результат, предусмотрите операцию запроса или предварительной валидации, учитывая, что состояние может измениться до выполнения основной операции. Любая операция изменения должна повторно проверять условия.
Валидация входных данных также не заменяет авторизацию, контроль доступа или меры против злоупотреблений. Каждый запрос должен оцениваться на сервере с учётом пользователя и затронутого ресурса. В PHP полезно чётко разделять валидацию транспортного уровня, применение правил и работу с хранилищем, не считая данные доверенными лишь потому, что их отправил собственный интерфейс.
Внедрение совместимых изменений и координация несовместимых
Изменение обычно совместимо, если существующие потребители могут продолжать работу без изменений в своём коде. Добавление необязательного поля может быть совместимым, если клиенты допускают неизвестные поля и новое поле не меняет значения существующих полей. Удаление или переименование свойств, изменение типов или превращение необязательного поля, используемого старыми клиентами, в обязательное обычно несовместимы.
Прежде чем менять контракт, определите потребителей, развёрнутые версии, кэши и фоновые процессы, вызывающие API. При совместимом развитии сервер может внедрить новое поведение, временно сохранив прежнее. Frontend может начать использовать новую возможность, а прежнюю можно удалить после явной проверки и подтверждения того, что старых потребителей больше нет.
Если сделать изменение совместимым невозможно, рассмотрите новую версию или согласованный переход с датой, ответственными и критериями вывода прежнего контракта из использования. Версионирование имеет смысл, только если помогает управлять разными потребителями; версия для каждой мелкой корректировки может обойтись дороже, чем дать защиты. Развёртывание кода не обязательно означает активацию функциональности: её можно развернуть и оставить выключенной до завершения тестирования или включать постепенно. Такую контролируемую активацию не следует путать с раскрытием информации пользователям.
Тестирование контракта на сценариях реального использования
Тесты API проверяют, что backend принимает корректные входные данные, отклоняет некорректные и возвращает согласованные схемы и состояния. Тесты frontend проверяют, что он правильно интерпретирует ответы и отображает нужные состояния. Интеграционные тесты проверяют обе части вместе в важных для продукта сценариях: создании, получении, обновлении или обработке ошибок.
Тест контракта может зафиксировать конкретные ожидания потребителя, не проверяя всю реализацию. Чтобы он был полезен, его нужно запускать в процессе, который выявляет расхождения до выпуска, и охватывать такие случаи, как отсутствие необязательного поля, ошибка валидации и отказ в доступе, если они применимы. Описательные контракты, например спецификация API, упрощают проверку и генерацию типов, но сами по себе не гарантируют соответствие реализации: в процессе интеграции нужны тесты или проверки.
Выбирайте сценарии на основе реальных операций и рисков, а не только списка маршрутов. Endpoint может возвращать данные нужного типа и всё же неправильно работать при переходе состояния или для пользователя без прав. Сочетайте автоматизированные тесты с проверкой изменений и наблюдаемостью: ошибки клиентов, неожиданные ответы и различия между версиями помогают находить проблемы после развёртывания.
Контрольный список перед выпуском
- Понятно ли, кто использует эту операцию и какие версии могут оставаться активными?
- Задокументированы ли поля, типы, обязательность, форматы, ошибки и важные состояния?
- Применяются ли бизнес-правила и авторизация на backend, даже если интерфейс предоставляет аналогичные подсказки?
- Продолжат ли существующие потребители работать без изменений кода, или изменение требует перехода и стратегии вывода прежнего контракта из использования?
- Есть ли тесты контракта и интегрированного сценария, включая важные ошибки?
- Можно ли обнаружить несовместимость по журналам и метрикам, не раскрывая конфиденциальные данные?
- Есть ли безопасный способ отключить изменение или откатить его, если оно не сработает?
Полезный контракт не замораживает архитектуру: он ограничивает неожиданности на границе систем. Чёткое распределение обязанностей, совместимые по умолчанию изменения и тесты, сосредоточенные на наблюдаемом поведении, позволяют командам развёртывать изменения независимо, не превращая каждую корректировку в экстренную ручную координацию.
