Tio Boot Docs

Appearance

Tio-Boot 配置 : 现代化的配置方案 ​

简介 ​

Tio-Boot 是一个基于 Java 的轻量级框架，提供了灵活的配置管理功能。它支持多环境配置、从多种来源读取配置，并提供了优先级管理，以满足不同场景下的需求。本指南将详细介绍 Tio-Boot 的配置方法及常见配置项的使用。

配置文件概述 ​

Tio-Boot 使用 nexus.io.tio.utils.environment.EnvUtils 和 nexus.io.tio.utils.environment.PropUtils 来读取配置信息。其主要特点包括：

  • 多环境配置：支持加载 app.properties 以及 app-{dev-name}.properties 等环境特定的配置文件。
  • 多来源配置：支持从内置 Map、启动命令行、Java 环境属性、系统环境变量、.env 文件和配置文件中读取配置。读取优先级依次为内置 Map > 启动命令行 > Java 系统属性 > 系统环境变量 > PropUtils 中已加载的文件配置。.env、secrets.txt 和 properties 文件共同合并到文件配置中，不是独立的读取层级；同名项按实际加载顺序覆盖，详见 EnvUtils 配置工具。
  • 系统环境变量命名支持：支持使用下划线命名法，如配置文件中的 app.env 对应系统变量 APP_ENV。

配置文件示例 ​

主配置文件位于 src/main/resources/app.properties，示例如下：

properties
# HTTP 配置
server.port = 80

常见配置 ​

指定静态文件目录 ​

Tio-Boot 支持两种方式读取静态文件：

  1. 从 classpath 下读取静态文件

    properties
    server.resources.static-locations = classpath:/pages

  2. 从文件系统读取静态文件

    properties
    # 当前目录的 pages 目录下读取配置
server.resources.static-locations = pages

指定静态文件目录后，Tio-Boot 会在收到访问请求时自动加载相应的静态文件。

HTTP 响应头中的 Server 信息 ​

配置项简介 ​

http.response.header.showServer 是一个布尔类型的配置项，用于控制是否在 HTTP 响应头中添加服务器信息。

  • true：在每个 HTTP 响应中添加 Server 头部，显示服务器信息。
  • false（默认值）：不添加 Server 头部。

配置项意义 ​

该配置项在不同场景下具有不同的用途：

  • 开发和调试环境：启用 Server 头部，方便调试工具和开发人员查看服务器信息，有助于定位和解决问题。
  • 生产环境：禁用 Server 头部，提高安全性，防止攻击者获取服务器详细信息，减少潜在攻击面。

配置示例 ​

在 Tio-Boot 的配置文件（如 application.properties）中，可以通过以下方式设置 http.response.header.showServer：

properties
# 启用 Server 头部
http.response.header.showServer=true

# 或者禁用 Server 头部
http.response.header.showServer=false

实际效果 ​

根据配置项的设置，服务器响应头中会有不同的表现：

  • 启用 Server 头部：

    http
    HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Server: Tio
...

  • 禁用 Server 头部：

    http
    HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
...

启用全局跨域 ​

要开启全局跨域支持，可以在配置文件中添加以下配置：

properties
server.http.response.cors.enable=true

多环境配置 ​

Tio-Boot 支持多环境配置，允许在不同的环境下加载不同的配置文件。以下是配置步骤和注意事项。

设置环境键 ​

默认情况下，Tio-Boot 使用 app.env 作为环境键。可以通过 setEnvKey 方法自定义环境键。如果配置文件中使用的是默认的 app.env，则无需进行此步骤。

加载主配置文件 ​

Tio-Boot 启动时会加载主配置文件 app.properties。该文件应包含指定当前运行环境的键值对，例如：

properties
app.env=dev

可以通过配置文件、环境变量或启动参数来设置 app.env 的值。

根据环境加载特定配置文件 ​

Tio-Boot 会根据 app.env 的值自动加载相应的环境特定配置文件。例如：

  • 如果 app.env=dev，则加载 app-dev.properties。
  • 如果 app.env=prod，则加载 app-prod.properties。

这是通过 handleEnv 方法实现的，依据 app.env 的值追加相应的环境配置文件。

具体配置步骤 ​

假设有三个配置文件：app.properties（主配置文件）、app-dev.properties（开发环境配置）、app-prod.properties（生产环境配置）。按照以下步骤进行配置：

  1. 在 app.properties 中设置环境

    properties
    # 或者 prod
app.env=dev

  2. 启动 Tio-Boot

    java
    TioApplication.run(HelloApp.class, args);

  3. 获取当前环境的键值

    java
    String env = EnvironmentUtils.get(ConfigKeys.appEnv);

启动后，Tio-Boot 会根据 app.properties 中的 app.env 值加载对应的环境文件（如 app-dev.properties 或 app-prod.properties）。这样，可以根据不同环境自动加载相应的配置文件。

注意事项 ​

  • 确保 app.properties、app-dev.properties 和 app-prod.properties 文件都位于 CLASSPATH 下或在可访问的文件路径中。
  • Tio-Boot 会合并主配置文件和环境特定的配置文件。如果存在重复的键，环境特定配置文件中的值将覆盖主配置文件中的值。

通过命令行指定参数 ​

Tio-Boot 支持通过命令行指定参数，参数查找顺序为：命令行参数 > 环境变量 > 配置文件。

示例 ​

以下示例展示了如何通过命令行指定 HTTP 端口：

shell
java -jar paddle-ocr-server-1.0.1.jar --http-port=8080

这样，http-port 的值将优先于配置文件中的设置。

读取配置 ​

Tio-Boot 提供了 EnvUtils 工具类，用于在代码中读取配置。

使用示例 ​

java
import nexus.io.tio.utils.environment.EnvUtils;

// 手动加载配置，仅需执行一次。如果使用 Tio-Boot 框架，配置会自动加载
// TioApplication.run(...) 会进入 TioApplicationContext.run(...)，并在启动阶段自动调用 EnvUtils.load(args)
// 因此普通 Tio-Boot 应用通常不需要在 main 方法里再手动调用 EnvUtils.load()
EnvUtils.load();

// 读取配置
String host = EnvUtils.get("tdengine.host");
int port = EnvUtils.getInt("tdengine.port");

补充说明：标准的 Tio-Boot 启动方式是 TioApplication.run(...)，它内部会进入 TioApplicationContext.run(...)，并在启动阶段自动执行 EnvUtils.load(args)。因此常规的 Tio-Boot 应用一般不需要在 main 方法中重复调用 EnvUtils.load()；只有脱离 Tio-Boot 启动流程的独立工具类、测试代码或脚本入口，才需要自行调用。

不要在 TioApplication.run 之前调用 EnvUtils.load()

EnvUtils.load() 只会加载一次。如果在 main 方法里先调用它，TioApplication.run 启动时会跳过加载，命令行参数也不再解析，--app.env=prod、--server.port=8080 这样的参数会失效。

java
public static void main(String[] args) {
  // 错误：--app.env=prod 不会生效
  EnvUtils.load();
  TioApplication.run(App.class, args);
}

框架会自动加载配置，main 方法里不需要调用。确实要在启动前读取配置时，使用 EnvUtils.load(args)，它会同时解析命令行参数。

通过 EnvUtils，可以方便地在代码中获取配置项的值，支持不同的数据类型转换。

通过以上配置指南，可以全面掌握 Tio-Boot 的配置方法，灵活应对不同的开发和生产环境需求，确保应用程序的稳定和安全运行。

MIT Licensed

Copyright © 2023-present litongjava