Class YmlProfile

java.lang.Object
cloud.opencode.base.yml.profile.YmlProfile
public final class YmlProfile extends Object
YAML Profile Loader - Profile-based configuration loading with deep merge YAML Profile 加载器 - 基于 Profile 的配置加载与深度合并

This utility class supports loading a base YAML configuration file and overlaying profile-specific files (e.g. application-dev.yml, application-prod.yml) using deep merge. Missing profile files are silently skipped.

此工具类支持加载基础 YAML 配置文件并使用深度合并覆盖 Profile 特定文件 （如 application-dev.yml、application-prod.yml）。 缺失的 Profile 文件会被静默跳过。

Features | 主要功能:

  • Load base + profile overlay YAML files - 加载基础 + Profile 覆盖 YAML 文件
  • Deep merge of profile-specific overrides - Profile 特定覆盖的深度合并
  • Multiple profile support with ordered application - 多 Profile 支持，按顺序应用
  • Auto-detect active profiles from system properties or environment - 从系统属性或环境变量自动检测活跃 Profile
  • Custom merge strategy support - 自定义合并策略支持
  • Missing profile files silently skipped - 缺失的 Profile 文件静默跳过

Usage Examples | 使用示例:

// Load application.yml + application-dev.yml
YmlDocument doc = YmlProfile.load(Path.of("config"), "application", "dev");

// Load with multiple profiles
YmlDocument doc = YmlProfile.load(Path.of("config"), "application", "dev", "local");

// Load with default name "application"
YmlDocument doc = YmlProfile.load(Path.of("config"), "dev", "local");

// Get active profiles from system property or env
List<String> profiles = YmlProfile.getActiveProfiles();

Security | 安全性:

  • Thread-safe: Yes (stateless utility class) - 线程安全: 是（无状态工具类）
  • Null-safe: No (null inputs throw exceptions) - 空值安全: 否（空输入抛出异常）
Since:
JDK 25, opencode-base-yml V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • load

      public static YmlDocument load(Path basePath, String name, String... profiles)
      Loads base configuration and profile overlays with deep merge. 加载基础配置和 Profile 覆盖，使用深度合并。

      Loads {basePath}/{name}.yml as the base, then for each profile, loads {basePath}/{name}-{profile}.yml if it exists and merges it.

      加载 {basePath}/{name}.yml 作为基础，然后对每个 Profile， 如果存在则加载 {basePath}/{name}-{profile}.yml 并合并。

      Parameters:
      basePath - the directory containing config files | 包含配置文件的目录
      name - the base config file name (without extension) | 基础配置文件名（无扩展名）
      profiles - the profile names to overlay | 要覆盖的 Profile 名称
      Returns:
      the merged document | 合并后的文档
      Throws:
      OpenYmlException - if the base file cannot be read | 当基础文件无法读取时

    • load

      public static YmlDocument load(Path basePath, String name, MergeStrategy strategy, List<String> profiles)
      Loads base configuration and profile overlays with a custom merge strategy. 使用自定义合并策略加载基础配置和 Profile 覆盖。
      Parameters:
      basePath - the directory containing config files | 包含配置文件的目录
      name - the base config file name (without extension) | 基础配置文件名（无扩展名）
      strategy - the merge strategy | 合并策略
      profiles - the profile names to overlay | 要覆盖的 Profile 名称
      Returns:
      the merged document | 合并后的文档
      Throws:
      OpenYmlException - if the base file cannot be read | 当基础文件无法读取时

    • loadDefault

      public static YmlDocument loadDefault(Path directory, String... profiles)
      Loads configuration from a directory using the default base name "application". 使用默认基础名称 "application" 从目录加载配置。

      Equivalent to load(directory, "application", profiles).

      等价于 load(directory, "application", profiles)。

      Parameters:
      directory - the directory containing config files | 包含配置文件的目录
      profiles - the profile names to overlay | 要覆盖的 Profile 名称
      Returns:
      the merged document | 合并后的文档
      Throws:
      OpenYmlException - if the base file cannot be found | 当基础文件找不到时

    • getActiveProfiles

      public static List<String> getActiveProfiles()
      Gets the active profiles from system property or environment variable. 从系统属性或环境变量获取活跃的 Profile。

      Checks in order:

      1. System property yml.profiles.active
      2. Environment variable YAML_PROFILES_ACTIVE

      The value is split by comma, and each token is trimmed.

      Returns:
      list of active profile names, or empty list if none configured | 活跃 Profile 名称列表，如果未配置则返回空列表