PHPTime

Плавающий интерфейс: как упорядочить разработку frontend + backend

Когда фронтенд и бэкенд разрабатывают параллельно, главная боль — не стыковка данных и потерянные требования. Подход «плавающий интерфейс» решает это через единый класс-контракт, который фронтендер использует как API, а бэкендер наполняет реальной логикой. Разберём, как выстроить такой контракт на современном PHP с учётом строгой типизации и актуальных практик.

Суть подхода

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

«Плавающий интерфейс» устраняет этот разрыв. Бэкендер один раз описывает класс-контракт со всеми методами, которые понадобятся фронтенду. Фронтендер сразу пишет шаблоны, вызывая методы этого класса. Пока реальная логика не готова, работает расширение-заглушка с тестовыми данными. Когда бэкендер реализует метод, заглушка переезжает в основной класс и удаляется из расширения.

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

Класс-контракт и расширение-заглушка

Создаём два файла. Первый — Frontend.php с базовым классом, где уже реализованные методы возвращают реальные данные. Второй — FrontendExtended.php, наследующий базовый класс и переопределяющий только те методы, которые ещё не готовы.

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
<?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
<?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
<?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
<?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
<?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-приложение. Но даже в этом случае единый класс подготовки данных упрощает переход от заглушек к реальной логике без переписывания потребителей.

Чек-лист внедрения

  1. Выделите DTO для всех сущностей, которые фронтенд забирает из бэкенда. Сделайте их readonly, укажите типы всех свойств.
  2. Создайте базовый класс Frontend с реализованными методами и FrontendExtended для заглушек.
  3. Подключите declare(strict_types=1) во всех файлах контракта и DTO.
  4. Опишите сигнатуры будущих методов в FrontendExtended сразу, как только фронтендер сообщил о потребности.
  5. Обеспечьте единую точку получения экземпляра — фабрику или DI-контейнер.
  6. Поставьте автотесты на заглушки: они должны возвращать данные той же структуры, что планируется в продакшене.
  7. Договоритесь с командой: заглушка живёт до момента реализации и удаляется в рамках той же задачи бэкенда.
  8. Для SPA и мобильных клиентов генерируйте контракт из сигнатур PHP-методов (например, через атрибуты и рефлексию в OpenAPI) — не пишите документацию руками.

Подход не панацея, но в средних и крупных проектах с серверным рендерингом он заметно сокращает хаос на стыке фронтенда и бэкенда. Единая точка контракта в сочетании со строгой типизацией заменяет десятки уточнений в мессенджерах.

Частые вопросы

Чем подход «плавающий интерфейс» отличается от простых моков в тестах?

Моки живут в тестовой среде и не видны фронтендеру. «Плавающий интерфейс» — это рабочий контракт: заглушки отдают тестовые данные прямо в шаблоны и API, поэтому фронтенд может разрабатываться параллельно с бэкендом, не дожидаясь готовой логики.

Подходит ли метод для полностью отделённого SPA-фронтенда?

Частично. Класс-контракт можно использовать как источник данных для JSON-эндпоинтов, но фронтендер в SPA не вызывает PHP-методы напрямую. В этом случае контракт полезен внутри бэкенда, а для внешнего API лучше генерировать OpenAPI-спецификацию и типы для TypeScript.

Что делать, если заглушки накопились и мешают разработке?

Ввести процесс: каждая заглушка должна быть связана с задачей бэкендера и иметь срок реализации. Полезно добавить в CI проверку, которая подсвечивает методы в <code>FrontendExtended</code> старше определённого срока или без ссылки на таск-трекер.

Справка по теме

Ещё в разделе «Фронтенд»

Система сборки фронтенда для PHP-проекта: от Grunt до современных таск-раннеров

Как подключить систему сборки CSS и JavaScript к бэкенду на PHP 8.3–8.5: минификация, конкатенация, версионирование ассетов и автодеплой в 2026 году.

6 мин

Stylus в 2026 году: стоит ли использовать CSS-препроцессор в современной разработке

Разбираем CSS-препроцессор Stylus в реалиях 2026 года: установка, синтаксис, БЭМ, миксины, подводные камни и сравнение с Sass. Практический чек-лист для разработчика.

5 мин

Правила именования CSS-классов и организации файлов стилей

Практические правила именования CSS-классов, структурирования файлов стилей и подключения ассетов в современных PHP-проектах. Разбор на примерах.

7 мин

HTML5-видео на сайте: форматы, кодеки, конвертация ffmpeg и оптимизация загрузки

Практический разбор HTML5-видео в 2026: конвертация в MP4/H.264, WebM/VP9/AV1 через ffmpeg, тег source, постер и lazy-loading для быстрой загрузки.

8 мин