Tio Boot Docs

Appearance

配置文件 ​

tio-boot 使用 EnvUtils 统一读取应用参数与私密配置。应用策略可以随 app.properties 发布，密钥保存在不提交的配置文件中，避免散落在业务代码。

文件按以下顺序合并，后加载的同名文件配置覆盖先前值：

  1. 用户目录 .env、secrets.txt。
  2. 类路径 app.properties、工作目录 app.properties。
  3. 类路径 app-环境.properties、工作目录 app-环境.properties。
  4. 类路径 .env，工作目录 .env、secrets.txt、my.txt。

加载分为环境选择与配置合并两个阶段。先读取基础文件和本地覆盖文件，结合程序设置、命令行、JVM 属性与环境变量确定 app.env，再追加对应环境文件。因此工作目录 secrets.txt 中的 app.env=test 也能选择 app-test.properties。环境只选择一次，环境文件中的 app.env 不会触发另一个环境文件的加载，合并配置中的 app.env 保持为本次选择的环境。环境名称支持字母、数字、下划线和短横线。

环境文件可以省略；存在的文件若解析失败，加载会抛出异常，保留此前已发布的配置，修正文件后可以重试。EnvUtils.load() 与 EnvUtils.load(args) 在首次成功后不重复加载，也不替换首次加载的启动参数；并发启动调用会串行完成初始化。

用户目录私密配置与类路径应用配置会合并保留；同名值按上述顺序确定。工作目录是启动 Java 进程时所在目录，建议从保存本地 secrets.txt 的服务目录启动。类路径中的私密文件会被打包，应优先使用工作目录文件或部署环境变量。

取值优先级为 EnvUtils.set 设置值、命令行参数、JVM 系统属性、系统环境变量、合并后的文件配置。点号名称也可使用大写下划线环境变量形式，例如 server.port 对应 SERVER_PORT。

java
package com.example.config;

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

public class LoginConfig {
  public String appId() {
    return EnvUtils.get("WECHAT_MINI_APP_ID");
  }

  public int sessionIdleSeconds() {
    return EnvUtils.getInt("identity.session.idle.seconds", 7200);
  }
}

框架启动时自动加载配置；独立工具程序可先调用 EnvUtils.load()。不要输出 AppSecret、AccessKey、密码或身份加密密钥。

不要在 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)，它会同时解析命令行参数。

可执行 JAR 的配置与依赖核对 ​

应用同时引入多个业务模块时，各模块应在自己的 POM 中声明经过验证的 tio-utils 依赖，并与应用选定的框架依赖保持兼容。Maven 会按依赖路径进行选择，较短路径上的传递依赖可能先于其他模块的依赖被选中。维护这些模块时，应优先更新依赖来源模块的声明，重新构建安装，再构建应用，让其他使用该模块的应用也能获得一致的配置加载行为。应用级依赖管理适合统一约束整个依赖图；暂时覆盖依赖后，仍应同步维护来源模块的依赖声明。

构建前可查看实际依赖选择：

shell
mvn dependency:tree -Dincludes=nexus.io:tio-utils -Dverbose

使用 Spring Boot 打包插件时，应用配置位于 BOOT-INF/classes/app.properties，依赖位于 BOOT-INF/lib/。更新底层源码后，需要先安装对应构建产物，再重新打包应用，使可执行 JAR 包含已验证的依赖。配置加载日志中的文件名用于识别读取来源；需要确认业务参数时，应检查参数是否存在，不输出其值。

下面的独立诊断程序只加载配置，不初始化数据库或业务服务。把它放在待验证应用的运行类路径中执行，可以核对实际加载的类、配置资源和必要参数：

java
package com.example.config;

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

public class ConfigurationCheck {
  public static void main(String[] args) {
    EnvUtils.load(args);
    ClassLoader loader = Thread.currentThread().getContextClassLoader();
    if (loader == null) {
      loader = EnvUtils.class.getClassLoader();
    }
    System.out.println("Configuration resource: " + loader.getResource("app.properties"));
    System.out.println("Configuration loader: " + EnvUtils.class.getResource("EnvUtils.class"));
    String jdbcUrl = EnvUtils.get("jdbc.url");
    if (jdbcUrl == null || jdbcUrl.trim().isEmpty()) {
      throw new IllegalStateException("Required configuration jdbc.url is missing");
    }
    System.out.println("Database configuration is present");
  }
}

数据库初始化与表初始化应按顺序执行：先读取配置、启动数据源与 ActiveRecord 插件，再执行表初始化。需要数据库的应用可以在启动数据源前校验必需参数，便于明确定位配置条件。

MIT Licensed

Copyright © 2023-present litongjava