EnvUtils 使用文档

EnvUtils 是 tio-utils 库中提供的一个实用工具类。它简化了在应用程序中从各种来源获取配置值的过程，例如内部 Map、命令行参数、Java 属性、环境变量和配置文件。

本使用文档将引导您了解 EnvUtils 的功能，包括如何获取配置值、设置自定义值以及从文件加载配置。

概述

EnvUtils 提供了一个统一的接口，用于从多个来源访问配置值。它按照预定义的顺序检查每个来源，并返回找到的第一个非空值。此方法允许灵活地管理配置，适应各种部署和开发场景。

配置来源的优先级

在获取配置值时，EnvUtils 按以下顺序检查来源：

内部 Map：您可以使用 EnvUtils.set(key, value) 以编程方式设置键值对。
命令行参数：通过 main 方法传递的参数，格式为 --key=value。
Java 系统属性：通过 System.setProperty(key, value) 设置的属性，或使用 JVM 参数 -Dkey=value。
环境变量：通过 System.getenv(key) 访问的操作系统级环境变量。
配置文件：使用 PropUtils 从文件加载的属性，通常是 app.properties 或特定环境的文件，如 app-dev.properties。

获取配置值

EnvUtils 提供了多个静态方法来获取不同类型的配置值。

字符串值

EnvUtils.get(String key)
获取指定键的字符串值。
```
String value = EnvUtils.get("config.key");
```
EnvUtils.get(String key, String defaultValue)
获取指定键的字符串值。如果未找到键，返回 defaultValue。
```
String value = EnvUtils.get("config.key", "default");
```

整数值

EnvUtils.getInt(String key)
获取指定键的整数值。如果未找到键，返回 null。
```
Integer intValue = EnvUtils.getInt("config.int.key");
```
EnvUtils.getInt(String key, int defaultValue)
获取指定键的整数值。如果未找到键，返回 defaultValue。
```
int intValue = EnvUtils.getInt("config.int.key", 42);
```

布尔值

EnvUtils.getBoolean(String key)
获取指定键的布尔值。如果未找到键，返回 false。
```
boolean flag = EnvUtils.getBoolean("config.boolean.key");
```
EnvUtils.getBoolean(String key, boolean defaultValue)
获取指定键的布尔值。如果未找到键，返回 defaultValue。
```
boolean flag = EnvUtils.getBoolean("config.boolean.key", true);
```

环境模式

EnvUtils 提供了根据 app.env 键确定当前环境模式的实用方法。

EnvUtils.getEnv() 或 EnvUtils.env()
获取当前环境模式的字符串值（例如："dev"、"test"、"prod"）。
```
String env = EnvUtils.getEnv();
```

EnvUtils.isDev()

如果当前环境是 "dev"，返回 true。

if (EnvUtils.isDev()) {
    // 开发环境的特定逻辑
}

EnvUtils.isTest()
如果当前环境是 "test"，返回 true。
EnvUtils.isProd()
如果当前环境是 "prod"，返回 true。

设置自定义配置值

您可以以编程方式设置自定义配置值，这些值在检索时具有最高优先级。

EnvUtils.set(String key, String value)
在内部 Map 中设置自定义键值对。
```
EnvUtils.set("custom.config", "customValue");
```

加载配置文件

EnvUtils 依赖于 PropUtils 来加载配置文件。您可以从特定文件加载配置，也可以使用默认的加载机制。

EnvUtils.load()
根据 app.env 的值，从默认文件 app.properties 或特定环境的文件（如 app-dev.properties）加载配置。
```
EnvUtils.load();
```
EnvUtils.load(String fileName)
从指定文件加载配置。
```
EnvUtils.load("custom.properties");
```
EnvUtils.load(String env, String fileName)
从指定的环境和文件加载配置。
```
EnvUtils.load("dev", "app.properties");
```

命令行参数

EnvUtils 可以解析传递给应用程序 main 方法的命令行参数。参数格式应为 --key=value。

EnvUtils.buildCmdArgsMap(String[] args)

解析命令行参数并在内部存储。

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 debugMode = EnvUtils.getBoolean("debug.mode", false);

        // 使用配置值
        System.out.println("服务器主机：" + host);
        System.out.println("服务器端口：" + port);
        System.out.println("调试模式：" + debugMode);
    }
}

示例 2：环境特定的配置

public class Main {
    public static void main(String[] args) {
        // 将环境设置为 'dev'
        EnvUtils.set("app.env", "dev");

        // 根据环境加载配置
        EnvUtils.load();

        // 检查环境模式
        if (EnvUtils.isDev()) {
            System.out.println("运行在开发模式。");
        }

        // 获取配置值
        String dbUrl = EnvUtils.get("database.url");
        System.out.println("数据库 URL：" + dbUrl);
    }
}

示例 3：覆盖配置

public class Main {
    public static void main(String[] args) {
        // 命令行参数：--server.port=9090
        EnvUtils.buildCmdArgsMap(args);

        // 加载配置
        EnvUtils.load();

        // 覆盖配置值
        EnvUtils.set("server.port", "8081");

        // 获取端口（由于内部 Map 具有最高优先级，将返回 8081）
        int port = EnvUtils.getInt("server.port", 8080);
        System.out.println("服务器端口：" + port); // 输出：服务器端口：8081
    }
}

附加说明

大小写敏感：键名是大小写敏感的。设置和检索配置值时，请确保使用一致的大小写。
环境变量：在检索环境变量时，EnvUtils 还会检查将点替换为下划线并转换为大写的键（例如，config.key 变为 CONFIG_KEY）。
依赖项：EnvUtils 依赖于 PropUtils 和 ResourceUtil 来加载配置文件。请确保这些工具在您的项目中可用。
日志记录：EnvUtils 使用 SLF4J 进行日志记录。请确保在项目中包含适当的日志框架。

通过利用 EnvUtils，您可以更有效地管理应用程序的配置，支持多种环境并根据需要覆盖设置。