使用属性文件配置红帽构建的 Quarkus 应用程序

流程

1. 验证 Maven 使用 OpenJDK 17 或 21，且 Maven 版本是否为 3.8.6 或更高版本：

   mvn --version

2. 如果 mvn 命令没有返回 OpenJDK 17 或 21，请确保系统上安装 OpenJDK 17 或 21 的目录包含在 PATH 环境变量中：

   export PATH=$PATH:<path_to_JDK>

3. 输入以下命令生成项目：

   mvn com.redhat.quarkus.platform:quarkus-maven-plugin:3.15.3.SP1-redhat-00002:create \
       -DprojectGroupId=org.acme \
       -DprojectArtifactId=config-quickstart \
       -DplatformGroupId=com.redhat.quarkus.platform \
       -DplatformVersion=3.15.3.SP1-redhat-00002 \
       -DclassName="org.acme.config.GreetingResource" \
       -Dpath="/greeting"
   cd config-quickstart

流程

1. 打开 src/main/resources/application.properties 文件。

2. 在您的配置文件中添加配置属性，其中 &lt ;property_name& gt; 是属性名称，<value > 是属性值：

   <property_name>=<value>

   以下示例演示了如何在 Quarkus config-quickstart 项目中设置 greeting.message 和 greeting.name 属性的值：

   application.properties 文件示例

   greeting.message=hello
   greeting.name=quarkus

   重要

   当您配置应用程序时，请不要使用字符串 quarkus 前缀应用程序特定属性。quarkus 前缀用于在框架级别配置 Quarkus。使用 quarkus 作为特定应用程序属性的前缀可能会导致应用程序运行时出现意外的结果。

3. 查看项目中的 GreetingResource.java Java 文件。该文件包含带有 hello （） 方法的 GreetingResource 类，它会在 /greeting 端点上发送 HTTP 请求时返回一条消息：

   GreetingResource.java 文件示例

   package org.acme.config;
   
   import java.util.Optional;
   
   import jakarta.ws.rs.GET;
   import jakarta.ws.rs.Path;
   import jakarta.ws.rs.Produces;
   import jakarta.ws.rs.core.MediaType;
   
   import org.eclipse.microprofile.config.inject.ConfigProperty;
   
   @Path("/greeting")
   public class GreetingResource {
   
       String message;
       Optional<String> name;
       String suffix;
   
   
       @GET
       @Produces(MediaType.TEXT_PLAIN)
       public String hello() {
           return message + " " + name.orElse("world") + suffix;
       }
   }

   在提供的示例中，hello （） 方法中 消息和 名称 字符串的值不会被初始化。当端点被调用时，应用会抛出 NullPointerException，并成功在此状态启动。

4. 定义 消息、name 和 suffix 字段，并使用 @ConfigProperty 为它们添加注解，这与您为 greeting.message 和 greeting .name 属性定义 的值匹配。使用 @ConfigProperty 注释来注入每个字符串的配置值。例如：

   GreetingResource.java 文件示例

   package org.acme.config;
   
   import java.util.Optional;
   
   import jakarta.ws.rs.GET;
   import jakarta.ws.rs.Path;
   import jakarta.ws.rs.Produces;
   import jakarta.ws.rs.core.MediaType;
   
   import org.eclipse.microprofile.config.inject.ConfigProperty;
   
   @Path("/greeting")
   public class GreetingResource {
   
     @ConfigProperty(name = "greeting.message") 1
     String message;
   
     @ConfigProperty(name = "greeting.suffix", defaultValue="!") 2
     String suffix;
   
     @ConfigProperty(name = "greeting.name")
     Optional<String> name; 3
   
     @GET
     @Produces(MediaType.TEXT_PLAIN)
     public String hello() {
         return message + " " + name.orElse("world") + suffix;
      }
   }

   1

   如果您没有为 greeting.message 字符串配置值，应用程序会失败并抛出以下异常： jakarta.enterprise.inject.spi.DeploymentException: io.quarkus.runtime.configuration.ConfigurationException: Failed to load config value of type java.lang.String for: greeting.message

   2

   如果没有为 greeting.suffix 配置值，Quarkus 会将它解析为默认值。

   3

   如果没有定义 greeting.name 属性，则 name 的值不可用。即使这个值不可用，应用程序仍然在运行，因为您在 名称 上设置 Optional 参数。

   注意

   要注入配置的值，您可以使用 @ConfigProperty。您不需要为使用 @ConfigProperty 标注的成员包含 @Inject 注释。

5. 在开发模式下编译并启动应用程序：

   ./mvnw quarkus:dev

6. 在新终端窗口中输入以下命令来验证端点返回消息：

   curl http://localhost:8080/greeting

   这个命令返回以下输出：

   hello quarkus!

7. 要停止应用程序，请按 Ctrl+C。

步骤

1. 打开 GreetingResourceTest.java 文件。

2. 更新 testHelloEndpoint 方法的内容：

   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
       }
   
   }

3. 在开发模式下编译并启动应用程序：

   ./mvnw quarkus:dev

4. 要开始运行测试，请在键盘上按 r 键。

步骤

1. 要打包 Quarkus 项目，请输入以下命令：

   ./mvnw clean package

2. 使用以下方法之一设置配置属性：

   • 设置系统属性：

     输入以下命令，其中 &lt ;property_name > 是您要添加的配置属性的名称，&lt ;value > 是属性值：

     java -D<property_name>=<value> -jar target/quarkus-app/quarkus-run.jar

     例如，要将 greeting.suffix 属性的值设置为 ?，请输入以下命令：

     java -Dgreeting.suffix=? -jar target/quarkus-app/quarkus-run.jar

   • 设置环境变量：

     输入以下命令，其中 &lt ;property_name > 是您要设置的配置属性的名称，&lt ;value > 是 属性的值：

     export <property_name>=<value> ; java -jar target/quarkus-app/quarkus-run.jar

     注意

     环境变量名称遵循 Eclipse MicroProfile 的转换规则。将名称转换为大写，并将不是字母数字的任何字符替换为下划线(_)。

   • 使用环境文件：

     在当前工作目录中创建 .env 文件并添加配置属性，其中 < PROPERTY_NAME& gt; 是属性名称，&lt ;value > 是属性值：

     <PROPERTY_NAME>=<value>

     注意

     在开发模式中，此文件位于项目的根目录中。不要跟踪版本控制中的文件。如果在项目的根目录中创建 .env 文件，您可以定义程序读取为属性的键和值。

   • 使用 application.properties 文件：

     将配置文件放在运行应用程序的 $PWD/config/application.properties 目录中，以便该文件中定义的任何运行时属性都覆盖默认配置。

     注意

     您还可以在开发模式中使用 config/application.properties 功能。将 config/application.properties 文件放在 目标 目录中。构建工具（如 mvn clean ）的任何清理操作也会删除 config 目录。

步骤

1. 打开 Java 资源文件并添加以下导入语句：

   import io.quarkus.runtime.configuration.ConfigUtils;

2. 要获取当前配置集的列表，请通过调用 ConfigUtils.getProfiles （） 方法来添加日志：

   LOGGER.infof("The application is starting with profiles `%s`", ConfigUtils.getProfiles());

其他资源

1. 有关使用日志记录 API、配置日志输出和使用日志记录适配器进行统一输出的更多信息，请参阅 日志配置。

步骤

1. 在您的项目中，创建一个实施 org.eclipse.microprofile.config.spi.ConfigSourceProvider 接口的新类。覆盖 getConfigSources （） 方法，以返回自定义 ConfigSource 对象列表。

   org.acme.config.InMemoryConfigSourceProvider示例

   package org.acme.config;
   
   import org.eclipse.microprofile.config.spi.ConfigSource;
   import org.eclipse.microprofile.config.spi.ConfigSourceProvider;
   
   import java.util.List;
   
   public class InMemoryConfigSourceProvider implements ConfigSourceProvider {
   
     @Override
     public Iterable<ConfigSource> getConfigSources(ClassLoader classLoader) {
       return List.of(new InMemoryConfigSource());
     }
   }

2. 要定义您的自定义配置源，请创建一个实现 org.eclipse.microprofile.config.spi.ConfigSource 接口的 InMemoryConfigSource 类：

   org.acme.config.InMemoryConfigSource示例

   package org.acme.config;
   
   import org.eclipse.microprofile.config.spi.ConfigSource;
   
   import java.util.HashMap;
   import java.util.Map;
   import java.util.Set;
   
   public class InMemoryConfigSource implements ConfigSource {
   
     private static final Map<String, String> configuration = new HashMap<>();
   
     static {
       configuration.put("my.prop", "1234");
     }
   
     @Override
     public int getOrdinal() { 1
       return 275;
     }
   
     @Override
     public Set<String> getPropertyNames() {
       return configuration.keySet();
     }
   
     @Override
     public String getValue(final String propertyName) {
       return configuration.get(propertyName);
     }
   
     @Override
     public String getName() {
       return InMemoryConfigSource.class.getSimpleName();
     }
   }

   1

   getOrdinal （） 方法返回 ConfigSource 类的优先级。因此，当多个配置源定义同一属性时，Quarkus 可以选择适当的值，如具有最高优先级的 ConfigSource 类定义。

3. 在项目的 src/main/resources/META-INF/services/ 子目录中，创建名为 org.eclipse.microprofile.config.spi.ConfigSourceProvider 的文件，并在您创建的文件中输入实施 ConfigSourceProvider 的类的完全限定域名：

   org.eclipse.microprofile.config.spi.ConfigSourceProvider 文件示例：

   org.acme.config.InMemoryConfigSourceProvider

   要确保在编译和启动应用程序时注册并安装您创建的 ConfigSourceProvider，您必须完成上一步。

4. 编辑项目中的 GreetingResource.java 文件，添加以下更新：

   @ConfigProperty(name="my.prop") int value;

5. 在 GreetingResource.java 文件中，扩展 hello 方法以使用新属性：

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

6. 在开发模式下编译并启动应用程序：

   ./mvnw quarkus:dev

7. 打开终端窗口并发送请求到 /greeting 端点：

   curl http://localhost:8080/greeting

8. 验证您的应用程序是否已读取自定义配置并返回预期信息：

   hello world 1234

步骤

1. 在 org.acme.config 软件包中，使用以下内容创建 org.acme.config.MyCustomValue 类：

   自定义配置值示例

   package org.acme.config;
   
   public class MyCustomValue {
   
       private final int value;
   
       public MyCustomValue(Integer value) {
           this.value = value;
       }
   
       public int value() {
           return value;
       }
   }

2. 实施转换器类，以覆盖生成 MyCustomValue 实例的转换方法。

   转换类的实现示例

   package org.acme.config;
   
   import org.eclipse.microprofile.config.spi.Converter;
   
   public class MyCustomValueConverter implements Converter<MyCustomValue> {
   
       @Override
       public MyCustomValue convert(String value) {
           return new MyCustomValue(Integer.valueOf(value));
       }
   }

3. 将转换器的完全限定类名称 org.acme.config.MyCustomValueConverter 添加至您的 META-INF/services/org.eclipse.microprofile.config.spi.Converter 服务文件。

4. 在 GreetingResource.java 文件中，注入 MyCustomValue 属性：

   @ConfigProperty(name="custom")
   MyCustomValue value;

5. 编辑 hello 方法以使用此值：

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

6. 在 application.properties 文件中，添加要转换的字符串表示：

   custom=1234

7. 要在开发模式下编译并启动应用程序，请输入以下命令：

   ./mvnw quarkus:dev

8. 要验证 /greeting 端点是否返回预期消息，请打开终端窗口并输入以下命令：

   curl http://localhost:8080/greeting

9. 当应用程序成功读取自定义配置时，命令会返回以下响应：

   hello world - 1234

   注意

   您的自定义转换器类必须 是公共的，且必须有一个 公共 的 no-argument 构造器。您的自定义转换器类不能 抽象。