Плавающий интерфейс: как упорядочить разработку frontend + backend
Когда фронтенд и бэкенд разрабатывают параллельно, главная боль — не стыковка данных и потерянные требования. Подход «плавающий интерфейс» решает это через единый класс-контракт, который фронтендер использует как API, а бэкендер наполняет реальной логикой. Разберём, как выстроить такой контракт на современном PHP с учётом строгой типизации и актуальных практик.
Суть подхода
Классическая ситуация: фронтендер верстает страницу новостей, а API для неё ещё не готово. Он вынужден писать временные массивы, дёргать бэкендера и ждать, пока тот освободится. После подключения реального функционала шаблон приходится переписывать и вычищать мусор.
«Плавающий интерфейс» устраняет этот разрыв. Бэкендер один раз описывает класс-контракт со всеми методами, которые понадобятся фронтенду. Фронтендер сразу пишет шаблоны, вызывая методы этого класса. Пока реальная логика не готова, работает расширение-заглушка с тестовыми данными. Когда бэкендер реализует метод, заглушка переезжает в основной класс и удаляется из расширения.
Контракт становится единственной точкой взаимодействия двух ролей. Он же задаёт сигнатуры методов и типы возвращаемых данных, что особенно важно в современных PHP-проектах со строгой типизацией.
Класс-контракт и расширение-заглушка
Создаём два файла. Первый — Frontend.php с базовым классом, где уже реализованные методы возвращают реальные данные. Второй — FrontendExtended.php, наследующий базовый класс и переопределяющий только те методы, которые ещё не готовы.
<?php
declare(strict_types=1);
namespace App\Frontend;
readonly class NewsItem
{
public function __construct(
public int $id,
public string $title,
public string $text,
public ?string $code = null,
) {}
}<?php
// App\Frontend\Frontend.php — реализованный функционал
namespace App\Frontend;
use App\Repository\NewsRepository;
class Frontend
{
public function __construct(
private readonly NewsRepository $newsRepository,
) {}
/**
* @return list<NewsItem>
*/
public function getNewsList(int $limit = 10): array
{
return $this->newsRepository->findLatest($limit);
}
public function getNewsById(int $newsId): ?NewsItem
{
return $this->newsRepository->findById($newsId);
}
/**
* @return list<NewsItem>
*/
public function getRelatedNewsList(int $newsId, int $limit = 4): array
{
return $this->newsRepository->findRelated($newsId, $limit);
}
}<?php
// App\Frontend\FrontendExtended.php — заглушки для будущих методов
namespace App\Frontend;
class FrontendExtended extends Frontend
{
public function getNewsByCode(string $newsCode): NewsItem
{
// Временная заглушка: фронтендер уже может использовать метод в шаблоне
return new NewsItem(
id: 33,
title: 'news 33',
text: 'text',
code: $newsCode,
);
}
}Обратите внимание: NewsItem объявлен как readonly — это DTO с иммутабельными свойствами. Фронтендер сразу видит структуру данных из сигнатуры метода, без чтения документации в отдельном файле.
Как фронтендер работает с контрактом
В шаблонах используется единая точка входа — функция-фабрика или DI-контейнер. Фронтендеру не нужно знать детали реализации: он вызывает метод и получает готовый массив DTO или один объект.
<?php
// bootstrap.php
use App\Frontend\FrontendExtended;
function F(): FrontendExtended
{
static $instance = null;
if ($instance === null) {
$repository = new App\Repository\NewsRepository(/* ... */);
$instance = new FrontendExtended($repository);
}
return $instance;
}<?php
// templates/news_item.php
use App\Frontend\NewsItem;
/** @var NewsItem $news */
$news = F()->getNewsByCode((string) ($_GET['code'] ?? ''));
?>
<div class="news">
<h1><?= htmlspecialchars($news->title, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8') ?></h1>
<p><?= htmlspecialchars($news->text, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8') ?></p>
</div>Когда бэкендер реализует настоящую выборку по коду, он переносит метод getNewsByCode() в Frontend и удаляет переопределение из FrontendExtended. Шаблон фронтендера при этом не меняется.
Единый контракт как источник REST API
Поскольку все данные текут через один класс, его же можно использовать для генерации JSON-ответов в API-контроллерах. Заглушки позволяют поднять REST-эндпоинты раньше, чем будет готова бизнес-логика.
<?php
// App\Controller\NewsApiController.php
namespace App\Controller;
use App\Frontend\Frontend;
final class NewsApiController
{
public function __construct(
private readonly Frontend $frontend,
) {}
public function item(string $code): array
{
$news = $this->frontend->getNewsByCode($code);
return [
'id' => $news->id,
'title' => $news->title,
'text' => $news->text,
'code' => $news->code,
];
}
}Это снимает двойную работу: бэкендер не пишет отдельные выборки для шаблонов и отдельные методы для API. Данные готовятся один раз в Frontend, а отдаются в нужном формате.
Типизация вместо документации
Раньше фронтендер получал от бэкендера в лучшем случае текстовый мануал, в худшем — устные договорённости. Часть требований неизбежно терялась. Теперь сигнатуры методов сами по себе являются документацией: PHP-тип возвращаемого значения, nullable, массив DTO, строгая типизация declare(strict_types=1).
Если бэкендер меняет структуру данных, он обновляет DTO. Фронтендер сразу видит проблему: обращение к несуществующему свойству объекта вызовет ошибку на этапе разработки, а не в продакшене. Строгая типизация отсекает случайный «тихий» каст строк и чисел.
Современные ограничения и их решение
У подхода есть несколько известных минусов. Разберём, как они решаются в актуальной разработке.
- Фронтендер должен знать PHP хотя бы на уровне чтения сигнатур. В 2026 году это мягкое требование, если проект использует серверный рендеринг или гибридный подход. Если фронтенд полностью отделён на SPA, контракт можно экспортировать через OpenAPI или генерировать TypeScript-типы.
- Заглушки могут задержаться в коде дольше нужного. Дисциплина решается ревью: метод в
FrontendExtendedдолжен исчезать сразу после реализации вFrontend. Помогает и тест, который проверяет, чтоFrontendExtendedне переопределяет методы без пометки «временная заглушка». - Состояние. Исходная идея допускала синглтон со свойствами. Современная практика — не хранить состояние в классе-контракте: это усложняет тестирование и параллельные запросы в контексте одного процесса.
Где метод работает лучше всего
«Плавающий интерфейс» наиболее полезен в проектах, где шаблоны рендерятся на сервере, а фронтенд и бэкенд пишутся в одной команде или в тесной связке. Подход не заменяет полноценный API с контрактом на уровне HTTP, когда фронтенд — отдельное SPA-приложение. Но даже в этом случае единый класс подготовки данных упрощает переход от заглушек к реальной логике без переписывания потребителей.
Чек-лист внедрения
- Выделите DTO для всех сущностей, которые фронтенд забирает из бэкенда. Сделайте их
readonly, укажите типы всех свойств. - Создайте базовый класс
Frontendс реализованными методами иFrontendExtendedдля заглушек. - Подключите
declare(strict_types=1)во всех файлах контракта и DTO. - Опишите сигнатуры будущих методов в
FrontendExtendedсразу, как только фронтендер сообщил о потребности. - Обеспечьте единую точку получения экземпляра — фабрику или DI-контейнер.
- Поставьте автотесты на заглушки: они должны возвращать данные той же структуры, что планируется в продакшене.
- Договоритесь с командой: заглушка живёт до момента реализации и удаляется в рамках той же задачи бэкенда.
- Для SPA и мобильных клиентов генерируйте контракт из сигнатур PHP-методов (например, через атрибуты и рефлексию в OpenAPI) — не пишите документацию руками.
Подход не панацея, но в средних и крупных проектах с серверным рендерингом он заметно сокращает хаос на стыке фронтенда и бэкенда. Единая точка контракта в сочетании со строгой типизацией заменяет десятки уточнений в мессенджерах.
Частые вопросы
Чем подход «плавающий интерфейс» отличается от простых моков в тестах?
Моки живут в тестовой среде и не видны фронтендеру. «Плавающий интерфейс» — это рабочий контракт: заглушки отдают тестовые данные прямо в шаблоны и API, поэтому фронтенд может разрабатываться параллельно с бэкендом, не дожидаясь готовой логики.
Подходит ли метод для полностью отделённого SPA-фронтенда?
Частично. Класс-контракт можно использовать как источник данных для JSON-эндпоинтов, но фронтендер в SPA не вызывает PHP-методы напрямую. В этом случае контракт полезен внутри бэкенда, а для внешнего API лучше генерировать OpenAPI-спецификацию и типы для TypeScript.
Что делать, если заглушки накопились и мешают разработке?
Ввести процесс: каждая заглушка должна быть связана с задачей бэкендера и иметь срок реализации. Полезно добавить в CI проверку, которая подсвечивает методы в <code>FrontendExtended</code> старше определённого срока или без ссылки на таск-трекер.