Как настроить приложение Quarkus с помощью application.properties?

Обзор механизма конфигурации

Quarkus использует стандарт MicroProfile Config для чтения настроек. Основной источник — файл src/main/resources/application.properties. Помимо него работают переменные окружения, системные свойства JVM (-Dkey=value) и любые кастомные ConfigSource. Приоритет источников определён спецификацией: системные свойства (250) > переменные окружения (300) > application.properties (100).

Профили

Quarkus поддерживает три встроенных профиля: dev, test, prod. Свойство с префиксом %dev. активируется только в режиме разработки, %prod. — только в продакшне. Активный профиль можно задать через quarkus.profile или переменную окружения QUARKUS_PROFILE.

# Общие настройки
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=app

# Переопределение для dev-профиля
%dev.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/devdb
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://prod-host:5432/proddb

# Кастомное свойство
app.max-items=100

Инъекция значений в код

Свойства инжектируются через аннотацию @ConfigProperty из пакета org.eclipse.microprofile.config.inject. Необязательные значения оборачиваются в Optional<T>, а defaultValue задаётся прямо в аннотации.

import org.eclipse.microprofile.config.inject.ConfigProperty;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("/config-demo")
public class ConfigDemoResource {

    @ConfigProperty(name = "app.max-items", defaultValue = "50")
    int maxItems;

    @ConfigProperty(name = "app.feature-flag")
    Optional<Boolean> featureFlag;

    @GET
    public String info() {
        return "maxItems=" + maxItems
            + ", feature=" + featureFlag.orElse(false);
    }
}

Типизированные группы через @ConfigMapping

Для сложных конфигураций Quarkus предлагает интерфейс @ConfigMapping, который связывает иерархические ключи с полями интерфейса. Это безопаснее, чем множество отдельных @ConfigProperty.

import io.smallrye.config.ConfigMapping;

@ConfigMapping(prefix = "app.cache")
public interface CacheConfig {
    int maxSize();
    Duration ttl();
}

app.cache.max-size=500
app.cache.ttl=PT10M

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

• Свойство с опечаткой в имени не вызывает ошибку при старте, если у него есть defaultValue — баг останется незамеченным.
• Переменные окружения имеют более высокий приоритет, чем application.properties, поэтому локальный файл может молча перекрываться окружением CI/CD.
• @ConfigProperty нельзя использовать в статических полях или конструкторах без CDI-контекста — это приводит к NullPointerException.
• Значения типа List<String> задаются через запятую: app.tags=java,quarkus. Пробел после запятой включается в элемент — нужно экранировать или убирать пробелы.
• Секреты (пароли, токены) не следует хранить в application.properties, зафиксированном в Git — используйте Vault, переменные окружения или Kubernetes Secrets.
• При нативной сборке (./mvnw package -Pnative) свойства, помеченные @ConfigProperty, фиксируются в binary; изменить их без пересборки нельзя, если они не объявлены как runtime-конфигурация.
• Профиль %prod. активен по умолчанию в нативном образе, но легко забыть об этом при локальном запуске java -jar без явного quarkus.profile.
• Формат ключей в переменных окружения использует верхний регистр и подчёркивания вместо точек: QUARKUS_DATASOURCE_JDBC_URL — несоответствие регистра даёт трудноуловимые ошибки.

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

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