Настройка OAuth2 для Gmail

Для Gmail предпочтительно использовать OAuth2.

Пример конфигурации:

@Configuration
public class MailConfig {

    @Bean
    public JavaMailSender javaMailSender() {
        JavaMailSenderImpl mailSender = new JavaMailSenderImpl();
        mailSender.setHost("smtp.gmail.com");
        mailSender.setPort(587);
        mailSender.setUsername("your.email@gmail.com");

        Properties props = mailSender.getJavaMailProperties();
        props.put("mail.smtp.auth", "true");
        props.put("mail.smtp.starttls.enable", "true");
        props.put("mail.smtp.auth.mechanisms", "XOAUTH2");

        // Настройка OAuth2 токена через Google API Client Library
        // Подробности: https://developers.google.com/identity/protocols/oauth2
        return mailSender;
    }
}

Примечание: Зарегистрируйте приложение в Google Cloud Console и используйте библиотеку google-auth-library-oauth2-http для получения accessToken.

Создание сервиса отправки почты

Создадим сервис EmailService для отправки писем.

@Service
public class EmailService {

    @Autowired
    private JavaMailSender mailSender;

    @Autowired
    private TemplateEngine templateEngine;

    private static final Logger logger = LoggerFactory.getLogger(EmailService.class);

    public void sendSimpleEmail(String to, String subject, String text) {
        SimpleMailMessage message = new SimpleMailMessage();
        message.setTo(to);
        message.setSubject(subject);
        message.setText(text);
        mailSender.send(message);
    }

    public void sendHtmlEmail(String to, String subject, String htmlBody) throws MessagingException {
        MimeMessage message = mailSender.createMimeMessage();
        MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
        helper.setTo(to);
        helper.setSubject(MimeUtility.encodeText(subject, "UTF-8", null));
        helper.setText(htmlBody, true);
        mailSender.send(message);
    }

    public void sendEmailWithAttachment(String to, String subject, String text, File attachment) throws MessagingException {
        MimeMessage message = mailSender.createMimeMessage();
        MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
        helper.setTo(to);
        helper.setSubject(MimeUtility.encodeText(subject, "UTF-8", null));
        helper.setText(text);
        FileSystemResource file = new FileSystemResource(attachment);
        helper.addAttachment(attachment.getName(), file);
        mailSender.send(message);
    }

    @Async
    public CompletableFuture<Void> sendSimpleEmailAsync(String to, String subject, String text IMPORTANT: text) {
        SimpleMailMessage message = new SimpleMailMessage();
        message.setTo(to);
        message.setSubject(MimeUtility.encodeText(subject, "UTF-8", null));
        message.setText(text);
        mailSender.send(message);
        return CompletableFuture.completedFuture(null);
    }

    public void sendTemplatedEmail(String to, String subject, String username) throws MessagingException {
        MimeMessage message = mailSender.createMimeMessage();
        MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
        Context context = new Context();
        context.setVariable("username", username);
        String htmlBody = templateEngine.process("email-template", context);
        helper.setTo(to);
        helper.setSubject(MimeUtility.encodeText(subject, "UTF-8", null));
        helper.setText(htmlBody, true);
        mailSender.send(message);
    }
}

Конфигурация асинхронности:

@Configuration
@EnableAsync
public class AsyncConfig {
    @Bean
    public Executor taskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(100);
        executor.initialize();
        return executor;
    }
}

#Java #middle #on_request #JavaMailSender

Примеры кода

Простой текст:

SimpleMailMessage message = new SimpleMailMessage();
message.setTo("user@example.com");
message.setSubject("Тестовое письмо");
message.setText("Привет из Spring Boot!");
mailSender.send(message);

HTML-письмо:

MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
helper.setTo("user@example.com");
helper.setSubject(MimeUtility.encodeText("HTML письмо", "UTF-8", null));
helper.setText("<h1>Привет!</h1><p>Это HTML письмо.</p>", true);
mailSender.send(message);

Вложение:

File file = new File("/path/to/file.pdf");
FileSystemResource resource = new FileSystemResource(file);
MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
helper.setTo("user@example.com");
helper.setSubject(MimeUtility.encodeText("Письмо с вложением", "UTF-8", null));
helper.setText("Смотри вложение!");
helper.addAttachment("file.pdf", resource);
mailSender.send(message);

Обработка ошибок и логирование

JavaMailSender может выбрасывать исключения, которые нужно обрабатывать.

Основные исключения:

MailAuthenticationException
MailSendException
MessagingException

Пример отлова:

try {
    mailSender.send(message);
} catch (MailException e) {
    logger.error("Ошибка отправки письма", e);
    throw e;
}

Повторные попытки
Используйте @Retryable из Spring Retry:

@Retryable(value = MailException.class, maxAttempts = 3)
public void sendSimpleEmail(String to, String subject, String text) {
    SimpleMailMessage message = new SimpleMailMessage();
    message.setTo(to);
    message.setSubject(subject);
    message.setText(text);
    mailSender.send(message);
}

Зависимость:

<dependency>
    <groupId>org.springframework.retry</groupId>
    <artifactId>spring-retry</artifactId>
</dependency>

Мониторинг и метрики

Для продакшен-приложений полезно отслеживать метрики отправки писем с помощью Spring Actuator:

@Service
public class EmailService {

    @Autowired
    private JavaMailSender mailSender;

    @Autowired
    private MeterRegistry meterRegistry;

    public void sendSimpleEmail(String to, String subject, String text) {
        SimpleMailMessage message = new SimpleMailMessage();
        message.setTo(to);
        message.setSubject(subject);
        message.setText(text);
        try {
            mailSender.send(message);
            meterRegistry.counter("email.sent.success").increment();
        } catch (MailException e) {
            meterRegistry.counter("email.sent.failure").increment();
            throw e;
        }
    }
}

Зависимость:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Безопасность и защита данных

Никогда не храните пароли в открытом виде в git-репозиториях.

Рекомендации:
Используйте переменные окружения или секреты (например, Kubernetes Secrets).
Применяйте Spring Cloud Vault или HashiCorp Vault.
Используйте шифрование с Jasypt.
Настройте OAuth2 для Gmail.

Пример с переменными окружения:

spring.config.import=optional:configserver:http://config-server
spring.mail.password=${MAIL_PASSWORD}

#Java #middle #on_request #JavaMailSender

Тестирование отправки почты

Интеграционные тесты с Testcontainers:

@Testcontainers
@SpringBootTest
public class EmailServiceTest {

    @Container
    private static final GreenMailContainer greenMail = new GreenMailContainer();

    @Autowired
    private EmailService emailService;

    @Test
    void shouldSendEmail() {
        emailService.sendSimpleEmail("test@example.com", "Test Subject", "Test Body");
        assertEquals(1, greenMail.getReceivedMessages().length);
    }
}

Зависимость:

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>greenmail</artifactId>
    <version>2.2.0</version>
    <scope>test</scope>
</dependency>

Unit-тестирование:

@MockBean
private JavaMailSender mailSender;

@Test
void shouldSendMail() {
    SimpleMailMessage message = new SimpleMailMessage();
    emailService.sendSimpleEmail("to", "subject", "body");
    verify(mailSender, times(1)).send(any(SimpleMailMessage.class));
}

Интеграция с очередями

Для отложенной отправки используйте RabbitMQ(ну или другой брокер сообщений):

@Service
public class EmailService {

    @Autowired
    private JavaMailSender mailSender;

    @Autowired
    private RabbitTemplate rabbitTemplate;

    public void sendEmailToQueue(String to, String subject, String text) {
        EmailMessage email = new EmailMessage(to, subject, text);
        rabbitTemplate.convertAndSend("emailQueue", email);
    }

    @RabbitListener(queues = "emailQueue")
    public void processEmail(EmailMessage email) {
        SimpleMailMessage message = new SimpleMailMessage();
        message.setTo(email.getTo());
        message.setSubject(email.getSubject());
        message.setText(email.getText());
        mailSender.send(message);
    }

    @Data
    static class EmailMessage {
        private String to;
        private String subject;
        private String text;
    }
}

Зависимость:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-amqp</artifactId>
</dependency>

Распространенные ошибки и подводные камни

Неверная конфигурация SMTP (порт, шифрование).
Проблемы с двухфакторной авторизацией (особенно Gmail).
Ограничения на массовую рассылку (например, Gmail: ~500 писем/день для бесплатных аккаунтов).
Проблемы с кодировкой (например, кириллица в теме письма).
Отсутствие MIME-типа у вложений.
Блокировка сервером (например, Mail.ru требует DKIM и SPF).

Решение для кодировки:

helper.setSubject(MimeUtility.encodeText("Тема на кириллице", "UTF-8", null));

#Java #middle #on_request #JavaMailSender

Введение в Flyway

Flyway представляет собой специализированный инструмент управления миграциями баз данных, реализующий принцип "Database-as-Code". Его фундаментальная задача заключается в обеспечении контролируемого и воспроизводимого процесса эволюции схемы базы данных через систему версионированных изменений.

Ключевые функциональные аспекты:
Декларативное управление схемой - все изменения БД описываются в виде отдельных скриптов
Детерминированность применения - каждая миграция имеет строгую версионную привязку
Атомарность изменений - миграции применяются как единое целое (транзакционно)
Историчность - полный аудит всех выполненных изменений

Сравнение с Liquibase

Принципиальные различия между Flyway и Liquibase проявляются в нескольких аспектах:

Архитектурный подход
Flyway придерживается парадигмы "SQL-первым", где основным носителем изменений являются нативные SQL-скрипты. Liquibase предлагает абстрактный DSL (XML/YAML/JSON) для описания изменений, который затем транслируется в SQL.

Механизм откатов
В Flyway стратегия откатов реализована через создание новых миграционных скриптов с обратными изменениями. Liquibase предоставляет встроенный механизм описания операций отката непосредственно в changeSet.

Сложность и гибкость
Flyway демонстрирует минималистичный подход с низким порогом вхождения. Liquibase предлагает более богатый функционал за счет усложненной модели конфигурации.

Интеграционные возможности
Оба инструмента имеют глубокую интеграцию с экосистемой Java, но Flyway чаще выбирают для Spring Boot-проектов благодаря более простой автоконфигурации.


Базовые концепции

Модель миграций

Flyway оперирует двумя фундаментальными типами миграций:

Версионные миграции (префикс V)
Линейно упорядоченные изменения схемы
Неизменяемые после применения

Пример именования: V2__Add_email_column.sql

Содержимое SQL-скрипта:

ALTER TABLE users ADD COLUMN email VARCHAR(255);

Повторяемые миграции (префикс R)
Перезаписываемые скрипты
Применяются при изменении контрольной суммы

Пример: R__Update_report_views.sql


Механизм контроля версий

Система использует служебную таблицу flyway_schema_history, содержащую:
Точную версию каждой примененной миграции
Контрольную сумму скрипта
Временные метки выполнения
Статус операции

Жизненный цикл изменений

Типичный workflow включает:
Инициализацию схемы (baseline)
Валидацию существующих миграций
Применение новых изменений (migrate)
При необходимости - очистку (clean) и повторное развертывание


Поддерживаемые системы управления базами данных

Flyway обеспечивает совместимость с большинством современных реляционных СУБД:
PostgreSQL (полная поддержка, включая расширения)
MySQL/MariaDB (включая специфичные движки хранения)
Oracle (с учетом особенностей PL/SQL)
SQL Server (включая Azure SQL)
Встраиваемые БД (H2, SQLite)
Для NoSQL-систем (MongoDB) требуется использование коммерческой версии Flyway. Важно отметить, что некоторые специфические функции СУБД могут требовать особого подхода при миграциях.


Типовые сценарии использования

Разработка - синхронизация схемы между средами
Тестирование - подготовка изолированных тестовых БД
Развертывание - автоматизация деплоя в production
Анализ - отслеживание истории изменений схемы

#Java #middle #Flyway

Настройка и базовые команды Flyway

1. Конфигурация Flyway

1.1. Файл flyway.conf
Основной файл конфигурации Flyway. Располагается в корне проекта или в директории conf.

Пример содержимого:

# Подключение к БД
flyway.url=jdbc:postgresql://localhost:5432/mydb
flyway.user=admin
flyway.password=secret

# Директории с миграциями
flyway.locations=classpath:db/migration,filesystem:/opt/migrations

# Дополнительные настройки
flyway.schemas=public
flyway.baselineOnMigrate=true

Ключевые параметры:
flyway.url — JDBC-URL базы данных (формат зависит от СУБД).

flyway.locations — пути к миграциям:
classpath: — поиск в ресурсах проекта (например, src/main/resources/db/migration).
filesystem: — абсолютный путь на диске.
flyway.baselineOnMigrate — инициализация существующей БД (без таблицы flyway_schema_history).

1.2. Параметры командной строки

Настройки можно переопределять через аргументы:

flyway -url=jdbc:postgresql://localhost:5432/mydb \
       -user=admin \
       -password=secret \
       -locations=classpath:db/migration \
       migrate
Важно: Параметры из командной строки имеют приоритет над flyway.conf.

2. Основные CLI-команды

2.1. flyway migrate

Применяет все невыполненные миграции.

Процесс:
Проверяет таблицу flyway_schema_history.
Находит скрипты, которых нет в истории.
Выполняет их в порядке версий (например, V1__... перед V2__...).

Пример:

flyway migrate

2.2. flyway info

Показывает текущее состояние БД:
Какие миграции применены.
Какие ожидают выполнения.
Статус (Success, Pending, Failed).

Вывод:

+-----------+---------+---------------------+------+---------------------+---------+
| Version   | Description | Installed on       | State | Type    | Checksum |
+-----------+---------+---------------------+------+---------------------+---------+
| 1         | Create users | 2024-03-15 10:00  | Done | SQL     | 1234abcd |
| 2         | Add email   | Pending            |      | SQL     | 5678efgh |
+-----------+---------+---------------------+------+---------------------+---------+

2.3. flyway validate

Проверяет:
Целостность скриптов (не изменены ли уже примененные).
Корректность именования.

Ошибка:

Validation failed: Detected applied migration not resolved locally: 1
Причина: Локальный скрипт V1__... был изменен после применения к БД.

2.4. flyway clean

Удаляет все объекты БД (таблицы, процедуры), включая flyway_schema_history.
Опасность: Необратимая операция. Используется только в dev-среде.

flyway clean

3. Форматы миграций

3.1. SQL-миграции

Стандартный подход. Скрипты с расширением .sql в директории db/migration.

Пример (V1__Create_users.sql):

CREATE TABLE users (
    id INT PRIMARY KEY,
    username VARCHAR(50) NOT NULL
);

INSERT INTO users (id, username) VALUES (1, 'admin');

3.2. Java-миграции

Для сложной логики (например, условные операции).

Шаги:
Создайте класс в проекте:

public class V2__InsertTestData implements JdbcMigration {
    public void migrate(Connection connection) throws Exception {
        try (Statement stmt = connection.createStatement()) {
            stmt.execute("INSERT INTO users (username) VALUES ('test')");
        }
    }
}

Укажите путь к Java-классам в flyway.locations:

flyway.locations=classpath:db/migration,classpath:com/example/migrations

3.3. Callbacks (SQL-хуки)

Скрипты, выполняемые до/после событий Flyway.

Пример (beforeMigrate.sql):

-- Выполняется перед началом миграций
CREATE SCHEMA IF NOT EXISTS audit;

Поддерживаемые события:
beforeMigrate, afterMigrate.
beforeClean, afterClean.

Директория:

db/
  migration/
    V1__...sql
  callback/
    beforeMigrate.sql

4. Важные замечания

Именование файлов:
Регистрозависимо (V1__test.sql ≠ v1__test.sql).
Разделитель — двойное подчеркивание (__).

Порядок выполнения:
Сначала V1__..., затем V2__....
R__... выполняются после всех версионных.

Безопасность:
Никогда не изменяйте уже примененные скрипты.
Для отката создавайте новые миграции (например, V3__Drop_table.sql).

#Java #middle #Flyway

Типы миграций и версионирование в Flyway

1. Структура SQL-миграций

Flyway классифицирует SQL-миграции по префиксам в именах файлов, определяя их поведение при выполнении.

1.1. Именование файлов

Версионные миграции (Versioned)

Префикс V + версия + описание:

V<Версия>__<Описание>.sql

Пример:

-- V1__Create_users_table.sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL
);

Повторяемые миграции (Repeatable)

Префикс R + описание:

R__<Описание>.sql

Пример:

-- R__Update_user_view.sql
CREATE OR REPLACE VIEW user_view AS
SELECT id, username FROM users;

2. Java-миграции

Позволяют описывать миграции на Java для сложной логики, недоступной в SQL.

2.1. Реализация интерфейсов

JdbcMigration (устаревший):

public class V2__InsertTestData implements JdbcMigration {
    @Override
    public void migrate(Connection connection) throws Exception {
        try (Statement stmt = connection.createStatement()) {
            stmt.execute("INSERT INTO users (username) VALUES ('admin')");
        }
    }
}

JavaMigration (рекомендуемый):

public class V3__AddAdminUser implements JavaMigration {
    @Override
    public void migrate(Context context) throws Exception {
        try (Statement stmt = context.getConnection().createStatement()) {
            stmt.execute("INSERT INTO users (username) VALUES ('superuser')");
        }
    }
}

2.2. Правила

Классы должны находиться в classpath (обычно src/main/java/db/migration).
Имя класса соответствует имени файла SQL-миграции (например, V2__InsertTestData.java).

3. Правила версионирования

3.1. Семантическое версионирование

Рекомендуемый формат версии:

V<Мажор>.<Минор>.<Патч>__<Описание>.sql

Пример:

-- V1.2.3__Fix_email_constraint.sql
ALTER TABLE users ALTER COLUMN email SET NOT NULL;

Преимущества:
Понятная история изменений.
Совместимость с Semantic Versioning.

3.2. Откат изменений

Flyway не поддерживает автоматический откат. Альтернативы:

Новая миграция для отмены изменений:

-- V3__Drop_users_table.sql
DROP TABLE users;

Callbacks (SQL-хуки):
Скрипты beforeMigrate/afterMigrate для резервного копирования.

Важно: Не изменяйте уже примененные миграции — это нарушит целостность flyway_schema_history.

4. Примеры

4.1. SQL-миграции

-- V1__Initial_schema.sql
CREATE TABLE users (
    id INT PRIMARY KEY,
    name VARCHAR(100)
);

-- R__Update_view.sql
CREATE OR REPLACE VIEW active_users AS 
SELECT * FROM users WHERE deleted_at IS NULL;

4.2. Java-миграция

public class V4__EncryptPasswords implements JavaMigration {
    @Override
    public void migrate(Context context) throws Exception {
        try (PreparedStatement ps = context.getConnection()
            .prepareStatement("UPDATE users SET password = encrypt(password)")) {
            ps.executeUpdate();
        }
    }
}

#Java #middle #Flyway

Интеграция Flyway с инструментами

1. Maven: плагин flyway-maven-plugin
Настройка в pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>org.flywaydb</groupId>
            <artifactId>flyway-maven-plugin</artifactId>
            <version>9.22.0</version>
            <configuration>
                <url>jdbc:postgresql://localhost:5432/mydb</url>
                <user>postgres</user>
                <password>password</password>
                <locations>
                    <location>classpath:db/migration</location>
                </locations>
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>org.postgresql</groupId>
                    <artifactId>postgresql</artifactId>
                    <version>42.6.0</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

Ключевые параметры:
url — JDBC-строка подключения.
locations — пути к папкам с миграциями (classpath: или filesystem:).
baselineVersion — версия для инициализации существующей БД (если не пустая).

Команды:

mvn flyway:migrate  # Применить миграции
mvn flyway:info     # Показать статус
mvn flyway:clean    # Очистить БД (удалить все объекты)

2. Gradle: плагин org.flywaydb.flyway
Настройка в build.gradle:

plugins {
    id "org.flywaydb.flyway" version "9.22.0"
}

flyway {
    url = 'jdbc:postgresql://localhost:5432/mydb'
    user = 'postgres'
    password = 'password'
    locations = ['classpath:db/migration']
}

dependencies {
    flywayRuntime 'org.postgresql:postgresql:42.6.0'
}

Команды:

gradle flywayMigrate  # Применить миграции
gradle flywayInfo    # Показать статус

3. Интеграция с Spring Boot
Автоконфигурация через application.yml:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: postgres
    password: password
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true  # Игнорировать существующую БД
    validate-on-migrate: false # Отключить валидацию (для dev)

Принцип работы:

При старте приложения Spring Boot автоматически:
Проверяет наличие таблицы flyway_schema_history.
Применяет невыполненные миграции из указанных в locations.
Если baseline-on-migrate: true, Flyway инициализирует БД без ошибок, даже если она не пуста.

Важные свойства:
spring.flyway.clean-disabled — запрет на случайную очистку БД (по умолчанию true в prod).
spring.flyway.table — кастомное имя для таблицы истории (по умолчанию flyway_schema_history).

4. Callbacks (SQL-хуки)

SQL-скрипты, выполняемые до/после основных операций Flyway (миграции, очистки и т.д.).

Поддерживаемые события:
beforeMigrate, afterMigrate
beforeClean, afterClean
beforeInfo, afterInfo

Пример использования:

Создайте файл db/migration/beforeMigrate.sql:

-- beforeMigrate.sql
CREATE TABLE IF NOT EXISTS _flyway_audit (
    operation VARCHAR(20),
    timestamp TIMESTAMP
);
INSERT INTO _flyway_audit VALUES ('migration_started', NOW());

Flyway выполнит этот скрипт перед применением миграций.

Правила:
Имена файлов должны соответствовать шаблону: <event>.sql (например, afterMigrate.sql).
Размещаются в папке locations (рядом с миграциями).

5. Мультимодульные проекты (Maven/Gradle)

Если миграции находятся в отдельном модуле:
Укажите путь к ресурсам через filesystem::

<!-- Maven -->
<location>filesystem:${project.basedir}/../migrations/src/main/resources/db/migration</location>

// Gradle
locations = ['filesystem:../migrations/src/main/resources/db/migration']

6. Пропуск миграций в тестах

В application-test.yml:

spring:
  flyway:
    enabled: false

7. Кастомные места хранения миграций

S3-хранилище (через Flyway Teams):

spring:
  flyway:
    locations: s3://my-bucket/db/migration

Классовый путь + файловая система:

locations: classpath:db/migration, filesystem:/opt/migrations

#Java #middle #Flyway

Best Practices и расширенные сценарии работы с Flyway

1. Организация миграций

1.1. Разделение миграций по окружениям

Проблема:
Разные БД для dev/test/prod могут требовать специфичных скриптов (например, тестовые данные только для dev).

Решение:
Структура папок:

db/
  migration/
    dev/
      V1__Dev_only_data.sql
    prod/
      V1__Prod_indexes.sql
    common/
      V1__Base_schema.sql

Настройка application.yml для dev:

spring:
  flyway:
    locations: classpath:db/migration/common, classpath:db/migration/dev

1.2. Работа с существующей БД (baseline)

Проблема:
Flyway ожидает пустую БД или таблицу flyway_schema_history. Если БД уже используется, требуется инициализация.

Решение:
Включить baseline-on-migrate:

spring:
  flyway:
    baseline-on-migrate: true
    baseline-version: 1.0  # Версия, с которой начнется контроль

Вручную через CLI:

flyway baseline -baselineVersion="1.0"

Важно:
После baseline миграции с версией ≤ baselineVersion игнорируются.


2. Тестирование миграций

2.1. Интеграция с Testcontainers + JUnit

Цель:
Проверить, что миграции применяются без ошибок в изолированной БД.

Пример теста (Java + JUnit 5):

import org.flywaydb.core.Flyway;
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

@Testcontainers
public class FlywayMigrationTest {

    @Container
    private static final PostgreSQLContainer<?> postgres = 
        new PostgreSQLContainer<>("postgres:15");

    @Test
    void testMigrations() {
        Flyway flyway = Flyway.configure()
            .dataSource(
                postgres.getJdbcUrl(),
                postgres.getUsername(),
                postgres.getPassword()
            )
            .load();
        flyway.migrate(); // Упадет, если есть ошибки
    }
}

Что проверяем:
Применение всех миграций без исключений.
Соответствие схемы ожиданиям (можно добавить проверку через DataSource).


3. Работа в команде

3.1. Именование файлов

Правила:
Уникальность версий:
Используйте дату + порядковый номер: V20240315-1__Add_users_table.sql.

Описательные имена:
Плохо: V1__Changes.sql.
Хорошо: V20240315-2__Alter_users_add_email.sql.

3.2. Запрет изменения примененных скриптов

Проблема:
Изменение уже выполненного скрипта приводит к ошибке:

Validate failed: Migration checksum mismatch for V1__Create_table.sql

Решение:
Никогда не изменять содержимое V*-файлов после их применения.

Для исправлений:
Создать новую миграцию с корректировкой:

-- V20240315-3__Fix_users_table.sql
ALTER TABLE users ALTER COLUMN email SET NOT NULL;

Если критично, использовать flyway repair (пересчитывает контрольные суммы).

Исключение:
R__-миграции (повторяемые) можно изменять — они переприменяются при изменениях.


4. Расширенные сценарии

4.1. Миграции для нескольких схем БД

Настройка:

spring:
  flyway:
    schemas: public, audit
    default-schema: public
В SQL-файлах укажите схему явно:

sql
-- V1__Create_audit_table.sql
CREATE TABLE audit.logs (
    id SERIAL PRIMARY KEY,
    message TEXT
);

4.2. Шаблонизация SQL

Проблема:
Разные SQL-синтаксисы для PostgreSQL/Oracle.

Решение (через Maven/Gradle):
Используйте placeholders в pom.xml:

<configuration>
    <placeholders>
        <table.prefix>${env}</table.prefix>
    </placeholders>
</configuration>

В SQL:

CREATE TABLE ${table.prefix}_users (...);

4.3. Откаты (безопасная альтернатива)

Тактика:
Для деструктивных изменений (DROP, DELETE) создавать "обратные" миграции:

-- V5__Drop_users.sql
DROP TABLE users;

-- V6__Restore_users.sql (если нужно откатить)
CREATE TABLE users (...); -- Повторяем структуру из V1
INSERT INTO users (...) SELECT ... FROM backup_users;
Использовать резервные копии перед рискованными операциями.

#Java #middle #Flyway

Архитектура Maven и философия Convention over Configuration

После первого знакомства с Maven важно не просто уметь пользоваться им, а понимать его архитектуру, принципы работы и идеологию. Это особенно критично для тех, кто хочет углубиться в автоматизацию, CI/CD и масштабирование проектов с помощью Maven.

Maven как декларативная модель

Maven основан на декларативной модели сборки: вы описываете, что должно быть сделано, а не как. Это противоположность императивным сборочным системам вроде Ant, где разработчик пишет шаг за шагом скрипты сборки. В Maven центром управления является файл pom.xml — он описывает структуру проекта, зависимости, плагины, цели сборки и метаинформацию.

Архитектура Maven

Архитектура Maven построена вокруг трёх ключевых сущностей:

1. POM (Project Object Model)
POM — сердце проекта. В нем описано всё: от координат артефакта (groupId, artifactId, version) до зависимостей, плагинов, профилей и модулей. POM определяет не только поведение сборки, но и организацию кода, стратегию управления версиями и способы расширения функциональности проекта.

2. Репозитории
Система Maven разделяет репозитории на три уровня:
Локальный (~/.m2/repository) — кеш библиотек и плагинов, уже использованных разработчиком
Центральный (Maven Central) — основной публичный репозиторий.
Удалённые (корпоративные) — приватные хранилища (Nexus, Artifactory и др.).
При разрешении зависимостей Maven сначала ищет артефакт в локальном репозитории, затем — в удалённых.

3. Плагины и цели (goals)
Maven сам по себе — движок исполнения, не знающий, как компилировать, тестировать или архивировать проект. Всё это делают плагины, привязанные к жизненному циклу. Например, maven-compiler-plugin отвечает за компиляцию, а maven-surefire-plugin — за запуск тестов. Каждый плагин состоит из целей (goals), которые выполняются в рамках фаз сборки.


Жизненный цикл сборки

Основой выполнения в Maven является жизненный цикл сборки (Build Lifecycle) — предопределённая последовательность фаз.

Есть три основных цикла:
default — основной, включает: compile, test, package, install, deploy.
clean — очищает артефакты: pre-clean, clean, post-clean.
site — генерирует документацию: site, site-deploy.
Maven всегда выполняет все фазы до указанной. То есть mvn install запустит validate, compile, test, package, verify, install.


Convention over Configuration

Одной из ключевых идей Maven является принцип «Конвенция важнее конфигурации» (Convention over Configuration):

Maven ожидает, что структура проекта будет стандартной:

src/
  main/java/
  test/java/

Артефакт будет упакован как jar (если не указано иное).
Папки ресурсов и тестов тоже стандартны.
Это означает, что вам не нужно конфигурировать то, что уже стандартизировано. Но при этом Maven предоставляет гибкость, позволяя переопределять любую часть стандартной логики при необходимости.


Maven и расширяемость

Благодаря своей архитектуре, Maven легко адаптируется под различные сценарии.

Расширение происходит через:
Подключение плагинов.
Наследование и агрегацию POM'ов.
Создание собственных плагинов и Mojo.
Подключение профилей и переменных окружения.

Именно такая расширяемость делает Maven удобным не только для простых библиотек, но и для масштабных корпоративных решений.

#Java #middle #Maven

Руководство по POM (Project Object Model) в Maven

POM (Project Object Model) является основой любого Maven-проекта. Файл pom.xml определяет структуру проекта, его зависимости, процесс сборки и другие аспекты, необходимые для управления жизненным циклом проекта. Этот документ представляет собой XML-файл, который Maven интерпретирует для создания модели проекта в памяти.


Основные теги

Основные теги pom.xml формируют базовую идентификацию и структуру проекта. Они обязательны или критически важны для корректной работы Maven.

<project>: Корневой элемент каждого pom.xml. Он определяет пространство имен XML (xmlns) и схему (xsi:schemaLocation), чтобы Maven мог валидировать файл. Все остальные элементы являются дочерними для <project>. В памяти Maven создает объект Project, который хранит всю информацию о проекте, включая зависимости, плагины и настройки сборки.
<modelVersion>: Указывает версию модели POM, используемой в файле. На момент 2025 года стандартной является версия 4.0.0. Этот тег необходим, так как Maven использует его для определения правил парсинга и совместимости. Неправильная версия приведет к ошибке парсинга.
<groupId>: Уникальный идентификатор группы, к которой относится проект. Обычно это доменное имя компании или организации в обратном порядке (например, com.example). В памяти Maven использует groupId как часть координат для идентификации артефакта в репозитории.
<artifactId>: Уникальное имя артефакта внутри группы. Это название проекта или модуля (например, my-app). Вместе с groupId и version формирует уникальные координаты артефакта.
<version>: Версия проекта. Следует семантическому версионированию (например, 1.0.0-SNAPSHOT). Maven использует версию для управления артефактами в локальном и удаленных репозиториях. Суффикс SNAPSHOT указывает на нестабильную версию, что влияет на поведение кэширования.
<packaging>: Определяет тип выходного артефакта (например, jar, war, pom). По умолчанию — jar. Этот тег влияет на жизненный цикл сборки, так как Maven выбирает соответствующие плагины и цели (goals) для обработки. Например, для war подключается плагин maven-war-plugin.

Эти теги формируют минимальный pom.xml. Maven парсит их в объектную модель, которая хранится в памяти JVM во время выполнения. Объектная модель включает org.apache.maven.model.Model, где каждый тег маппится на соответствующее поле или коллекцию. Например, groupId, artifactId и version объединяются в уникальный ключ артефакта.


Расширенные теги

Расширенные теги добавляют метаданные, улучшающие документацию и управление проектом. Они необязательны, но полезны в корпоративных средах.

<name>: Человекочитаемое название проекта. Используется в отчетах и документации, генерируемых Maven (например, через maven-site-plugin). Не влияет на логику сборки, но хранится в метаданных артефакта.
<description>: Описание проекта. Как и <name>, используется для документации. Maven включает это поле в метаданные артефакта, которые публикуются в репозиторий.

<url>: URL проекта, например, сайт или репозиторий. Используется в документации и для генерации ссылок в отчетах.

<inceptionYear>: Год создания проекта. Это поле чисто информационное, хранится в метаданных.

<organization>: Содержит информацию об организации, включая <name> и <url>. Используется для единообразной документации в крупных проектах.

Эти теги не влияют на процесс сборки, но добавляются в файл метаданных артефакта (META-INF/maven/groupId/artifactId/pom.properties), который создается при упаковке. В памяти они хранятся как часть объекта Model, но не участвуют в логике выполнения.

#Java #middle #Maven #pom