The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Configuração YAML

Você pode usar um arquivo YAML, application.yaml , para configurar sua aplicação Quarkus em vez do arquivo de propriedades Java padrão, application.properties .

O YAML é amplamente usado para definir descritores de recursos, especialmente no Kubernetes.

Habilitar a configuração YAML

Para ativar a configuração YAML, adicione a extensão quarkus-config-yaml :

CLI
quarkus extension add quarkus-config-yaml
Maven
./mvnw quarkus:add-extension -Dextensions='quarkus-config-yaml'
Gradle
./gradlew addExtension --extensions='quarkus-config-yaml'

Como alternativa, adicione a seguinte dependência ao seu projeto:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-config-yaml</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-config-yaml")

Depois de adicionar a extensão ou a dependência, para evitar confusão, remova o arquivo src/main/resources/application.properties e crie um arquivo src/main/resources/application.yaml .

Se ambos os arquivos estiverem presentes, o Quarkus dará prioridade às propriedades do arquivo YAML.
Quarkus reconhece ambas as extensões de arquivo .yml e .yaml.

Exemplo de configurações YAML

Os trechos a seguir fornecem exemplos de configurações do YAML:

# YAML supports comments
quarkus:
  datasource:
    db-kind: postgresql
    jdbc:
      url: jdbc:postgresql://localhost:5432/some-database

# REST Client configuration property
quarkus:
  rest-client:
    org.acme.rest.client.ExtensionsService:
      url: https://stage.code.quarkus.io/api
# For configuration property names that use quotes, do not split the string inside the quotes
quarkus:
  log:
    category:
      "io.quarkus.category":
        level: INFO
quarkus:
  datasource:
    jdbc:
      url: jdbc:postgresql://localhost:5432/quarkus_test

  hibernate-orm:
    database:
      generation: drop-and-create

  oidc:
    enabled: true
    auth-server-url: http://localhost:8180/auth/realms/quarkus
    client-id: app


app:
  frontend:
    oidc-realm: quarkus
    oidc-app: app
    oidc-server: http://localhost:8180/auth

# With profiles
"%test":
   quarkus:
     oidc:
       enabled: false
     security:
        users:
            file:
              enabled: true
              realm-name: quarkus
              plain-text: true

Perfis

Como o você pode ver no trecho anterior, é possível usar perfis no YAML.

No YAML, as chaves que começam com % não são permitidas. Entretanto, as chaves de perfil devem começar com esse símbolo. Para resolver isso, coloque as chaves de perfil entre aspas duplas, conforme demonstrado no exemplo "%test" .

Todas as configurações sob a chave "%test" são ativadas somente quando o perfil test está ativado. Por exemplo, o trecho anterior mostra que o OpenID Connect (OIDC) ( quarkus.oidc.enabled: false ) está desativado quando o perfil test está ativo. Sem o perfil test , o OIDC é ativado por padrão.

Você pode também definir perfis personalizados, como %staging no exemplo a seguir:

quarkus:
  http:
    port: 8081

"%staging":
    quarkus:
        http:
          port: 8082

Se você ativar o perfil staging , a porta HTTP será definida como 8082 em vez de 8081 .

A configuração YAML também oferece suporte a arquivos com reconhecimento de perfil. Nesse caso, as propriedades de um perfil específico podem estar presente em um arquivo nomeado application-{profile}.yaml . O exemplo anterior pode ser expresso como:

quarkus:
  http:
    port: 8081
application-staging.yaml
quarkus:
  http:
    port: 8082

An application.yaml file must exist (even if empty) in the exact location of the profile-aware (application-{profile}.yaml) file to be included in the configuration to ensure a consistent order when loading the files.

Expressões

O formato YAML também é compatível com expressões de propriedade (property expressions), usando o mesmo formato das propriedades Java:

mach: 3
x:
  factor: 2.23694

display:
  mach: ${mach}
  unit:
    name: "mph"
    factor: ${x.factor}

Você pode fazer referência a propriedades vinculadas (nested) usando o separador . (ponto), como em ${x.factor} .

Arquivo application.yaml externo

O arquivo application.yaml também pode ser colocado em config/application.yaml para especializar a configuração do tempo de execução. O arquivo deve estar presente na raiz do diretório de trabalho em relação ao executor da aplicação Quarkus:

.
├── config
│    └── application.yaml
├── my-app-runner

Os valores deste arquivo substituem quaisquer valores do arquivo application.yaml regular, se ele existir.

Conflitos de propriedades de configuração

The MicroProfile Config specification defines configuration properties as an arbitrary .-delimited string. However, structured formats such as YAML only support a subset of the possible configuration namespace. For example, consider the two configuration properties one.two and one.two.three. One property is the prefix of another, so it might not be immediately evident how to specify both keys in your YAML configuration.

Isso é resolvido com o uso de ~ como uma chave null para representar qualquer propriedade YAML que seja um prefixo de outra:

one:
  two:
    ~: 12
    three: 123

As chaves YAML null não são incluídas na composição do nome da propriedade de configuração, permitindo que sejam usadas em qualquer nível para remover ambiguidade das propriedades de configuração.

Embora o Quarkus use principalmente a extensão de arquivo .properties para configuração, a biblioteca snakeyaml, que é usada para interpretar YAML no Quarkus, também pode interpretar estruturas JSON. Isso significa que você pode usar arquivos YAML com conteúdo JSON.

Estruturas YAML e JSON podem ser interpretadas em um arquivo application.yaml.

Certamente, aqui está um guia passo a passo sobre como usar estruturas de configuração complexas com o Quarkus:

  • Define sua interface de configuração.

@ConfigMapping(prefix = "server")
public interface ServiceConfig {

  List<Environment> environments();

  interface Environment {
    String name();
    String services();
  }
}
  • Crie a estrutura JSON apropriada e armazene-a em um arquivo YAML.

{
  "server": {
    "environments": [
      {
        "name": "dev",
        "services": "bookstore"
      },
      {
        "name": "batch",
        "services": "warehouse"
      }
    ]
  }
}

Conteúdo Relacionado