ADR-0001: Use JdbcTemplate over JPA/Hibernate

Date: 2026-06-12 Status: Accepted

Context

При выборе способа доступа к данным для сервера Mozhno рассматривались два варианта: Spring Data JPA/Hibernate и прямой JDBC через JdbcTemplate.

Mozhno — это сервер фиче-флагов, критичный к latency: SDK-клиенты запрашивают правила флагов на каждый запрос. Доменная модель относительно проста: 15 таблиц, чёткие связи, никаких сложных графов объектов.

Decision

Выбран Spring JdbcTemplate с ручным написанием SQL и RowMapper.

Consequences

Позитивные:

• Полный контроль над каждым SQL-запросом. Никаких сгенерированных LEFT JOIN на 5 таблиц из-за FetchType.EAGER.
• Никаких LazyInitializationException в продакшене.
• Прямой INSERT ... RETURNING id вместо currval() для получения сгенерированных ключей.
• Прозрачная производительность: каждый запрос виден в коде, легко добавить индекс или переписать запрос.
• Отсутствие ORM-зависимости упрощает потенциальную миграцию на другие БД.

Негативные:

• Больше ручного кода (RowMapper, SQL-строки).
• Нет автоматической валидации схемы на старте (компенсируется Flyway).
• Нет кеша первого уровня / dirty checking (компенсируется явным Caffeine-кешем).

Alternatives Considered

• Spring Data JPA: Отклонён из-за риска N+1 запросов, сложности с нативными RETURNING для PostgreSQL, потери контроля над SQL.
• jOOQ: Избыточен для 15 таблиц. Добавляет кодогенерацию.
• MyBatis: Разумная альтернатива, но требует XML-маппингов. JdbcTemplate достаточен.