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
:
quarkus extension add quarkus-config-yaml
./mvnw quarkus:add-extension -Dextensions='quarkus-config-yaml'
./gradlew addExtension --extensions='quarkus-config-yaml'
Como alternativa, adicione a seguinte dependência ao seu projeto:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-config-yaml</artifactId>
</dependency>
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
quarkus:
http:
port: 8082
An |
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"
}
]
}
}