Что такое MicroProfile Config и как он работает в Quarkus?

MicroProfile Config в Quarkus

MicroProfile Config — стандарт (спецификация Eclipse MicroProfile) для управления конфигурацией в Java-приложениях. Quarkus реализует эту спецификацию через расширение quarkus-smallrye-config, которое входит в quarkus-core по умолчанию. Конфигурация агрегируется из нескольких источников с разным приоритетом и доступна через инъекцию @ConfigProperty или программно через ConfigProvider.

Источники конфигурации (ConfigSource) и их приоритет

• 400 — системные свойства JVM (-Dkey=value)
• 300 — переменные окружения (MY_APP_HOST=localhost)
• 295 — файл .env в рабочей директории
• 250 — application.properties (или application.yaml если подключить quarkus-config-yaml)
• 100 — значения по умолчанию из аннотации @ConfigProperty(defaultValue=...)

Чем выше число — тем выше приоритет. Переменная окружения всегда перекрывает application.properties.

Базовое использование

@ApplicationScoped
public class EmailService {
    // Обязательное свойство — упадёт при старте, если не задано
    @ConfigProperty(name = "email.smtp.host")
    String smtpHost;

    // Со значением по умолчанию
    @ConfigProperty(name = "email.smtp.port", defaultValue = "587")
    int smtpPort;

    // Optional — свойство может отсутствовать
    @ConfigProperty(name = "email.from")
    Optional<String> fromAddress;

    // Список через запятую
    @ConfigProperty(name = "email.allowedDomains")
    List<String> allowedDomains;
}

# application.properties (или application.yaml)
email:
  smtp:
    host: smtp.resend.com
    port: 587
  from: noreply@example.com
  allowed-domains: example.com,acme.org

Группировка через @ConfigMapping

SmallRye Config (реализация в Quarkus) добавляет @ConfigMapping — type-safe интерфейс для конфигурационных групп. Это предпочтительный подход для сложных конфигураций.

@ConfigMapping(prefix = "database")
public interface DatabaseConfig {
    String host();
    int port();
    String name();
    PoolConfig pool();

    interface PoolConfig {
        int minSize();
        int maxSize();
        Duration timeout();
    }
}

database:
  host: localhost
  port: 5432
  name: mydb
  pool:
    min-size: 5
    max-size: 20
    timeout: 30S

@Inject
DatabaseConfig dbConfig;

void connect() {
    String url = "jdbc:postgresql://" + dbConfig.host() + ":" + dbConfig.port() + "/" + dbConfig.name();
    int maxConn = dbConfig.pool().maxSize();
}

Профили конфигурации

Quarkus поддерживает встроенные профили dev, test, prod и кастомные. Активный профиль задаётся переменной окружения QUARKUS_PROFILE или системным свойством -Dquarkus.profile=staging.

# Значения для всех профилей
database.host: prod-db.internal

# Переопределение только для dev
%dev.database.host: localhost

# Переопределение только для test
%test.database.host: testcontainer-host

# Кастомный профиль staging
%staging.database.host: staging-db.internal

Программный доступ

// Без CDI инъекции, например в утилитном коде
Config config = ConfigProvider.getConfig();
String host = config.getValue("database.host", String.class);
Optional<Integer> port = config.getOptionalValue("database.port", Integer.class);

Подводные камни

• Маппинг имён свойств из env. Переменная окружения EMAIL_SMTP_HOST соответствует свойству email.smtp.host. Правило: точки и дефисы → подчёркивания, всё в верхний регистр. Ошибки в этом маппинге — самая частая причина «свойство не подхватилось».
• Eager validation при старте. Если обязательное @ConfigProperty не найдено — приложение не запустится с DeploymentException. Это хорошо в проде, но требует заглушек в тестах.
• @ConfigMapping — интерфейс, не класс. @ConfigMapping работает только с интерфейсами. Попытка использовать abstract class вызовет ошибку генерации кода в build time.
• Инъекция в статический контекст. @ConfigProperty — CDI-механизм, работает только в managed бинах. В статических методах или утилитных классах используйте ConfigProvider.getConfig().
• Секреты в application.properties. Файл попадает в Docker image и git. Для секретов используйте переменные окружения или подключайте Vault через quarkus-vault.
• Тип Duration в @ConfigMapping. Формат Duration в MicroProfile Config — PT30S (ISO-8601), но SmallRye также принимает 30S. Смешивание форматов при разных версиях может дать неожиданный результат.
• List через запятую теряет пробелы. Значение a, b, c даёт элементы ["a", " b", " c"] — с пробелом в начале. Trim не применяется автоматически.

• Путать термин «microprofile config» с соседним механизмом Quarkus.
• Не называть границу lifecycle, transaction, thread или request для «microprofile config».
• Игнорировать production-эффекты «microprofile config»: latency, SQL shape, memory, security или observability.

• Попросить объяснить механизм «microprofile config» на минимальном примере.
• Проверить, видит ли кандидат failure mode и диагностику для «microprofile config».
• Уточнить, какие настройки или API меняют «microprofile config» в реальном сервисе.