EnvUtils

EnvUtils 是 tio-utils 库提供的配置工具类，用于统一管理应用程序的配置来源。它支持从内部 Map、命令行参数、系统属性、环境变量、配置文件等渠道获取配置值，并按照固定优先级进行查找。

功能概述

EnvUtils 提供一组静态方法，可从多种来源获取配置值，优先级从高到低如下：

  1. 内部 Map（通过 EnvUtils.set 设置）
  2. 命令行参数（--key=value）
  3. Java 系统属性（-Dkey=value）
  4. 系统环境变量（key 和 KEY_WITH_UNDERSCORE 形式）
  5. 配置文件（由 PropUtils 加载）

EnvUtils 与 PropUtils 配合使用，可以轻松加载 app.properties 及多环境配置文件，例如 app-dev.properties。

配置文件加载

1. 加载默认配置：EnvUtils.load()

源码行为如下：

  1. 在 classpath 中查找 app.properties

  2. 如果存在：

    • 调用 PropUtils.use(app.properties, env) 即根据 app.env 自动加载主文件 + 子环境文件

  3. 若 classpath 没找到 app.properties：

    • 若 app.env 存在：尝试加载 app-{env}.properties
    • 否则直接加载默认的 app.properties

  4. 附加加载（append方式，不会覆盖前面加载的文件）：

    • classpath 中的 .env
    • 工作目录中的 .env
    • 工作目录中的 secrets.txt

  5. 打印加载结果日志

其核心逻辑简化如下：

EnvUtils.load();

它会依次加载：

  • app.properties（如存在）
  • app-{env}.properties（根据环境自动加载）
  • .env（classpath 或文件系统）
  • secrets.txt（若存在）

2. 明确指定文件名

EnvUtils.load("custom.properties");

3. 指定环境 + 文件名

EnvUtils.load("dev", "app.properties");

配置值获取方法

EnvUtils 根据键名自动从上述渠道依次查找对应的值。

字符串

String value = EnvUtils.get("config.key");
String valueWithDefault = EnvUtils.get("config.key", "default");

整数类型

源代码中 getInt(String key) 的行为是：

  • 如果键不存在，返回 0（非 null）
  • 如果需要 null 值，请使用 getInteger
int intValue = EnvUtils.getInt("config.int.key");
int intValueWithDefault = EnvUtils.getInt("config.int.key", 42);

Integer nullableInt = EnvUtils.getInteger("config.int.key");
Integer nullableIntWithDefault = EnvUtils.getInteger("config.int.key", 10);

Long 类型

Long value = EnvUtils.getLong("config.long.key");
Long valueWithDefault = EnvUtils.getLong("config.long.key", 100L);

Boolean 类型

boolean flag = EnvUtils.getBoolean("config.boolean.key");
boolean flagWithDefault = EnvUtils.getBoolean("config.boolean.key", true);

环境模式管理

EnvUtils 使用 app.env 键标识当前环境。源码提供了方便的方法：

String env = EnvUtils.getEnv(); // 或 env()
boolean dev = EnvUtils.isDev();
boolean test = EnvUtils.isTest();
boolean prod = EnvUtils.isProd();
boolean local = EnvUtils.isLocal();

快速切换环境：

EnvUtils.useDev();
EnvUtils.use("custom"); // 自定义环境名

设置自定义配置值（最高优先级）

内部 Map 优先级最高，可覆盖所有其他方式。

EnvUtils.set("server.port", "9090");

命令行参数解析

EnvUtils 支持解析格式为 --key=value 的参数。

public static void main(String[] args) {
    EnvUtils.buildCmdArgsMap(args);
}

示例

示例 1：基本配置加载

public class Main {
    public static void main(String[] args) {
        EnvUtils.buildCmdArgsMap(args);
        EnvUtils.load();

        String host = EnvUtils.get("server.host", "localhost");
        int port = EnvUtils.getInt("server.port", 8080);
        boolean debug = EnvUtils.getBoolean("debug.mode", false);

        System.out.println("host=" + host);
        System.out.println("port=" + port);
        System.out.println("debug=" + debug);
    }
}

示例 2：多环境配置

public static void main(String[] args) {
    EnvUtils.use("dev");
    EnvUtils.load();

    if (EnvUtils.isDev()) {
        System.out.println("开发模式");
    }

    System.out.println("数据库地址：" + EnvUtils.get("database.url"));
}

示例 3：覆盖配置值

public static void main(String[] args) {
    EnvUtils.buildCmdArgsMap(args);
    EnvUtils.load();

    EnvUtils.set("server.port", "8081");

    int port = EnvUtils.getInt("server.port", 8080);
    System.out.println(port); // 输出 8081
}

补充说明

键名大小写敏感

键名严格区分大小写。

环境变量自动转换规则

在查找环境变量时会进行两次尝试：

  1. 直接查 System.getenv(key)
  2. 将 key 的.替换为 _并转为大写 例如：config.key → CONFIG_KEY

配置文件加载依赖

EnvUtils 依赖：

  • PropUtils
  • ResourceUtil

需要确保它们存在于项目中。

日志记录

使用 SLF4J 输出加载信息。