ИИ-агент мигрировал Spring Boot на 3.5, но провалил 7 из 12 контрактных тестов

Разработчик befayer опубликовал подробный разбор миграции реального биллингового сервиса с Java 11 и Spring Boot 2.7.18 на Spring Boot 3.5. Вместо ручной проверки «на глаз» он создал 12 контрактных тестов, которые ИИ-агенту Kodacode запрещено менять, и отдал миграцию агенту. «Наивная» миграция, где исправлено только то, на что ругается компилятор, прошла сборку и health-check, но провалила 7 из 12 контрактных тестов. Это и есть главная проблема: код компилируется, сервис стартует, а клиенты ломаются.

Почему «наивная» миграция Spring Boot проходит сборку, но ломает клиентов?

Переход Spring Boot 2.7 → 3.x принёс самые крупные изменения со времён второй версии. Часть из них компилятор видит сразу, а часть ломает поведение молча.

• javax.* → jakarta.* Все пакеты Java EE переименованы. Проект не соберётся, пока не поменяете импорты. Это видимая часть.
• WebSecurityConfigurerAdapter удалён. Конфигурацию безопасности нужно переписывать через компонентную модель Security 6. Без этого проект тоже не соберётся.
• Spring Cloud Sleuth заменён на Micrometer Tracing. Заголовки трассировки (формат B3, который передаёт gateway) нужно подключать заново.
• Hibernate 5.6 → Hibernate 6. Меняется маппинг enum-полей: раньше в базу писалось число (ordinal), теперь строка. Код собирается, сервис стартует, но при вставке записи падает с ошибкой 500.
• Trailing slash больше не совпадает. Запрос /api/invoices/ со слэшем на конце раньше работал, теперь возвращает 404. Мобильное приложение, которое ходит именно так, ломается.
• Максимальный размер HTTP-заголовка по умолчанию уменьшен. Заголовок X-Client-Context размером до 16 КБ, который передаёт gateway, перестаёт проходить и возвращает 400.
• Публичные эндпоинты и редирект на логин. Без правильной настройки Security 6 просроченная ссылка на оплату из письма возвращает 401 (просьбу залогиниться) вместо ожидаемого 404.

Именно последние четыре пункта не видны ни компилятору, ни стандартным тестам, которые мигрируют вместе с кодом.

Контрактные тесты: как не дать агенту «договориться» с кодом?

Обычные юнит-тесты и интеграционные тесты мигрируют вместе с кодом: в них тоже надо менять javax на jakarta, чинить MockMvc и настройки Security. Если после этого тесты зелёные, это доказывает только то, что тесты и код «договорились между собой», но не то, что клиенты получат прежние ответы.

Контрактные тесты в этом проекте работают иначе:

• Запросы идут через стандартный java.net.http.HttpClient из JDK, без Spring-зависимостей.
• Состояние базы перед тестом сбрасывается обычным JDBC (прямое подключение к базе данных через стандартный Java-интерфейс).
• Тесты лежат в отдельной директории src/contractTest и стучатся в уже запущенный сервис по адресу из переменной TARGET_BASE_URL.

Один скрипт scripts/contract-check.sh поднимает PostgreSQL, запускает сервис из текущей ветки, гоняет все 12 тестов и гасит сервис. Один и тот же набор работает и на 2.7, и на 3.5.

Запрет менять контрактные тесты записан не в промпт (промпт, текстовая инструкция для модели), а в файл AGENTS.md прямо в репозитории. ИИ-агент (программа, которая сама выполняет шаги без ручного контроля) читает этот файл при старте. Проверка простая: если git diff boot-2.7 -- src/contractTest показывает пустой результат, агент тесты не трогал.

Как попробовать на своём проекте?

1. Склонируйте демо-репозиторий: github.com/befayer/spring-boot-27-migration-demo. Код открыт, можно изучить структуру контрактных тестов и файл AGENTS.md.
2. Запустите контрактные тесты на текущей версии 2.7 скриптом scripts/contract-check.sh, чтобы убедиться, что все 12 проходят.
3. Попробуйте «наивную» миграцию: исправьте только ошибки компиляции и запустите тесты заново. По данным автора, 7 из 12 тестов упадут, и вы увидите те самые «тихие» поломки.
4. Для своего сервиса напишите аналогичные контрактные тесты: вынесите HTTP-вызовы в отдельный source set без Spring-зависимостей и опишите, что именно ожидает каждый клиент (мобильное приложение, gateway, публичные ссылки).

Есть ли аналог для российских команд?

Kodacode, ИИ-агент, который использовал автор для миграции, не имеет прямого российского аналога именно для задач миграции Spring Boot. YandexGPT и GigaChat умеют генерировать и рефакторить код по промпту, но не работают как агенты (автономно выполняющие многошаговые задачи в репозитории).

Для русскоязычных команд, где сервисы на Java 11 с WebSecurityConfigurerAdapter живут в проде годами, а мобильные приложения стучатся со слэшами на конце, подход из этого проекта ценен не агентом, а контрактными тестами. Их можно написать без Kodacode и без любой нейросети: обычный HttpClient, обычный JUnit, отдельная директория. Нейросеть тут ускоряет рутину, но страховочная сетка работает независимо от неё.

Что делать с этим прямо сейчас, по ролям?

Разработчику или тимлиду. Если ваш сервис на Spring Boot 2.7, он не получает патчей безопасности уже полтора года. Перед миграцией напишите контрактные тесты для каждого клиента: мобильного приложения, gateway, публичных страниц. Именно они покажут «тихие» поломки, которые пропустит компилятор.

Автору Дзена или контент-маркетологу. Тема миграции Spring Boot 2.7 → 3.x остаётся болезненной для тысяч команд. Если пишете для разработчиков, разбор конкретных «тихих» поломок (trailing slash, Hibernate enum, размер заголовка) даёт материал с высокой практической ценностью.

Предпринимателю. Спросите у своей команды, на какой версии Spring Boot работают ваши сервисы. Если на 2.7, это не техдолг «когда-нибудь», а отсутствие обновлений безопасности прямо сейчас.

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

Почему именно Spring Boot 3.5, а не сразу 4.x?

Переход 2.7 → 3.x самый тяжёлый: именно здесь прилетают jakarta, Security 6 и Hibernate 6. Ветка 3.x заканчивается на 3.5, и это логичная промежуточная остановка перед следующим обновлением.

Можно ли использовать Spring Boot Initializer для миграции?

Spring Boot Initializer (start.spring.io, веб-инструмент для создания нового проекта Spring Boot с нужными зависимостями) генерирует каркас нового проекта, но не мигрирует существующий код. Для миграции он полезен как справочник: создайте проект на 3.5 с теми же стартерами и сравните зависимости с вашим текущим build.gradle.

Что делать, если нет ресурсов на контрактные тесты?

Начните с минимума: один тест на каждый тип клиента. Мобильное приложение шлёт запрос со слэшем на конце? Один тест. Публичная ссылка из письма должна отдавать 404, а не форму входа? Ещё один тест. Даже три-четыре контрактных теста поймают те поломки, которые не видит компилятор и пропускает стандартный health-check.

Контрактные тесты не заменяют ИИ-агента и не требуют его. Но если вы решите отдать миграцию агенту, именно они станут единственным доказательством, что клиенты продолжат получать те же ответы, что и до обновления.