选择指南版本

配置你的应用程序

The content of this guide and been revised and split into additional topics. Please check the Additional Information section.

Hardcoded values in your code are a no-go (even if we all did it at some point ;-)). In this guide, we will learn how to configure a Quarkus application.

先决条件

完成这个指南，你需要:

大概15分钟
编辑器
JDK 17+ installed with JAVA_HOME configured appropriately
Apache Maven 3.9.9
如果你愿意的话，还可以选择使用Quarkus CLI
如果你想构建原生可执行程序，可以选择安装Mandrel或者GraalVM，并正确配置(或者使用Docker在容器中进行构建)

解决方案

我们建议您按照下一节的说明逐步创建应用程序。然而，您可以直接转到已完成的示例。

克隆 Git 仓库: git clone https://github.com/quarkusio/quarkus-quickstarts.git ，或下载一个存档。

The solution is located in the config-quickstart directory.

Create the Maven project

首先，我们需要一个新的工程项目。用以下命令创建一个新项目：

CLI

quarkus create app org.acme:config-quickstart \
    --extension='rest' \
    --no-code
cd config-quickstart

创建Grade项目，请添加 --gradle 或者 --gradle-kotlin-dsl 参数。

For more information about how to install and use the Quarkus CLI, see the Quarkus CLI guide.

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:3.17.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=config-quickstart \
    -Dextensions='rest' \
    -DnoCode
cd config-quickstart

创建Grade项目，请添加 -DbuildTool=gradle 或者 -DbuildTool=gradle-kotlin-dsl 参数。

For Windows users:

If using cmd, (don’t use backward slash \ and put everything on the same line)
If using Powershell, wrap -D parameters in double quotes e.g. "-DprojectArtifactId=config-quickstart"

It generates:

Maven的结构
a landing page accessible on http://localhost:8080
example Dockerfile files for both native and jvm modes
应用程序的配置文件

创建配置

A Quarkus application uses the SmallRye Config API to provide all mechanisms related with configuration.

By default, Quarkus reads configuration properties from several sources. For the purpose of this guide, we will use an application configuration file located in src/main/resources/application.properties.

Edit the file with the following content:

application.properties

# Your configuration properties
greeting.message=hello
greeting.name=quarkus

Create a REST resource

Create the org.acme.config.GreetingResource REST resource with the following content:

package org.acme.config;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/greeting")
public class GreetingResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello RESTEasy";
    }
}

Inject the configuration

Quarkus uses MicroProfile Config annotations to inject the configuration properties in the application.

@ConfigProperty(name = "greeting.message") (1)
String message;

1	You can use `@Inject @ConfigProperty` or just `@ConfigProperty`. The `@Inject` annotation is not necessary for members annotated with `@ConfigProperty`.

If the application attempts to inject a configuration property that is not set, an error is thrown.

Edit the org.acme.config.GreetingResource, and introduce the following configuration properties:

@ConfigProperty(name = "greeting.message") (1)
String message;

@ConfigProperty(name = "greeting.suffix", defaultValue="!") (2)
String suffix;

@ConfigProperty(name = "greeting.name")
Optional<String> name; (3)

1	If you do not provide a value for this property, the application startup fails with `jakarta.enterprise.inject.spi.DeploymentException: No config value of type [class java.lang.String] exists for: greeting.message`.
2	The default value is injected if the configuration does not provide a value for `greeting.suffix`.
3	This property is optional - an empty `Optional` is injected if the configuration does not provide a value for `greeting.name`.

Now, modify the hello method to use the injected properties:

@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
    return message + " " + name.orElse("world") + suffix;
}

Use @io.smallrye.config.ConfigMapping annotation to group multiple configurations in a single interface. Please, check the Config Mappings documentation.

Store secrets in an environment properties file

A secret (such as a password, a personal access token or an API key) must not end up in version control for security reasons. One way is to store them in a local environment properties (.env) file:

Store the secret in the .env file in the project root directory.
The .env file
```
foo.api-key=ThisIsSecret
```
Add the .env file to .gitignore.

mvn quarkus:dev automatically picks up the properties in the .env file, similar to those in the application.properties file.

Update the test

We also need to update the functional test to reflect the changes made to the endpoint. Create the src/test/java/org/acme/config/GreetingResourceTest.java file with the following content:

package org.acme.config;

import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.Test;

import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;

@QuarkusTest
public class GreetingResourceTest {

    @Test
    public void testHelloEndpoint() {
        given()
          .when().get("/greeting")
          .then()
             .statusCode(200)
             .body(is("hello quarkus!")); // Modified line
    }

}

打包并运行该应用程序

使用以下命令运行该应用程序:

CLI

quarkus dev

Maven

./mvnw quarkus:dev

Gradle

./gradlew --console=plain quarkusDev

在你的浏览器中打开 http://localhost:8080/greeting 网页。

Changing the configuration file is immediately reflected. You can add the greeting.suffix, remove the other properties, change the values, etc.

像往常一样，该应用程序可以用以下方式打包：

CLI

quarkus build

Maven

./mvnw install

Gradle

./gradlew build

and executed using java -jar target/quarkus-app/quarkus-run.jar.

你也可以通过以下命令生成本地可执行文件:

CLI

quarkus build --native

Maven

./mvnw install -Dnative

Gradle

./gradlew build -Dquarkus.native.enabled=true

Programmatically access the configuration

The org.eclipse.microprofile.config.ConfigProvider.getConfig() API allows to access the Config API programmatically. This API is mostly useful in situations where CDI injection is not available.

String databaseName = ConfigProvider.getConfig().getValue("database.name", String.class);
Optional<String> maybeDatabaseName = ConfigProvider.getConfig().getOptionalValue("database.name", String.class);

Configuring Quarkus

Quarkus itself is configured via the same mechanism as your application. Quarkus reserves the quarkus. namespace for its own configuration. For example to configure the HTTP server port you can set quarkus.http.port in application.properties. All the Quarkus configuration properties are documented and searchable.

As mentioned above, properties prefixed with quarkus. are effectively reserved for configuring Quarkus itself and its extensions. Therefore, the quarkus. prefix should never be used for application specific properties.

Build Time configuration

Some Quarkus configurations only take effect during build time, meaning is not possible to change them at runtime. These configurations are still available at runtime but as read-only and have no effect in Quarkus behaviour. A change to any of these configurations requires a rebuild of the application itself to reflect changes of such properties.

The properties fixed at build time are marked with a lock icon () in the list of all configuration options.

However, some extensions do define properties overridable at runtime. A simple example is the database URL, username and password which is only known specifically in your target environment, so they can be set and influence the application behaviour at runtime.

Additional Information

Quarkus relies on SmallRye Config and inherits its features:

Additional ConfigSources
Additional Converters
Indexed properties
Parent profile
Interceptors for configuration value resolution
Relocate configuration properties
Fallback configuration properties
日志
Hide secrets

For more information, please check the SmallRye Config documentation.

先决条件
解决方案
Create the Maven project
创建配置
Create a REST resource
Inject the configuration
Store secrets in an environment properties file
Update the test
打包并运行该应用程序
Programmatically access the configuration
Configuring Quarkus
- Build Time configuration
Additional Information

配置你的应用程序

先决条件

解决方案

Create the Maven project

创建配置

Create a REST resource

Inject the configuration

Store secrets in an environment properties file

Update the test

打包并运行该应用程序

Programmatically access the configuration

Configuring Quarkus

Build Time configuration

Additional Information

Related content

On the same topics