Class YmlIncludeResolver

java.lang.Object
cloud.opencode.base.yml.include.YmlIncludeResolver
public final class YmlIncludeResolver extends Object
YAML Include Resolver - Resolves !include directives in YAML files YAML 包含解析器 - 解析 YAML 文件中的 !include 指令

This class processes YAML content and resolves !include <path> directives by loading referenced files and substituting their content into the parent document. It supports nested includes with configurable depth limits and security controls.

此类处理 YAML 内容并解析 !include <path> 指令，通过加载引用的文件并将其内容 替换到父文档中。支持嵌套包含，提供可配置的深度限制和安全控制。

Features | 主要功能:

  • Resolve !include directives in YAML files - 解析 YAML 文件中的 !include 指令
  • Nested include support with depth limit - 嵌套包含支持，带深度限制
  • Circular reference detection - 循环引用检测
  • Path traversal prevention - 路径遍历防护
  • Configurable allowed file extensions - 可配置的允许文件扩展名
  • Builder pattern for configuration - 构建器模式配置

Usage Examples | 使用示例:

// Simple usage with defaults
Map<String, Object> data = YmlIncludeResolver.load(Path.of("config.yml"));

// Custom configuration
YmlIncludeResolver resolver = YmlIncludeResolver.builder()
    .maxDepth(5)
    .allowedExtensions(Set.of(".yml", ".yaml"))
    .basePath(Path.of("/etc/config"))
    .build();
Map<String, Object> data = resolver.resolve(Path.of("/etc/config/app.yml"));

Security | 安全性:

  • Thread-safe: Yes (immutable after construction) - 线程安全: 是（构建后不可变）
  • Path traversal prevention via basePath containment check - 通过 basePath 包含检查防止路径遍历
  • Circular reference detection via visited file tracking - 通过已访问文件跟踪检测循环引用
  • Extension whitelist to prevent loading non-YAML files - 扩展名白名单防止加载非 YAML 文件
Since:
JDK 25, opencode-base-yml V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • builder

      public static YmlIncludeResolver.Builder builder()
      Creates a new builder for configuring the resolver. 创建用于配置解析器的新构建器。
      Returns:
      a new builder | 新构建器

    • load

      public static Map<String,Object> load(Path file)
      Convenience method to load a YAML file with include resolution using defaults. 使用默认配置加载带包含解析的 YAML 文件的便捷方法。
      Parameters:
      file - the YAML file to load | 要加载的 YAML 文件
      Returns:
      the resolved YAML data as a map | 解析后的 YAML 数据映射
      Throws:
      OpenYmlException - if loading or resolution fails | 当加载或解析失败时

    • resolve

      public Map<String,Object> resolve(Path file)
      Resolves a YAML file with !include directives. 解析带有 !include 指令的 YAML 文件。
      Parameters:
      file - the YAML file to resolve | 要解析的 YAML 文件
      Returns:
      the resolved YAML data as a map | 解析后的 YAML 数据映射
      Throws:
      OpenYmlException - if loading or resolution fails | 当加载或解析失败时

    • resolve

      public Map<String,Object> resolve(String yaml, Path resolveBasePath)
      Resolves a YAML string with !include directives relative to the given base path. 解析相对于给定基础路径的带有 !include 指令的 YAML 字符串。
      Parameters:
      yaml - the YAML string to resolve | 要解析的 YAML 字符串
      basePath - the base path for resolving includes | 解析包含的基础路径
      Returns:
      the resolved YAML data as a map | 解析后的 YAML 数据映射
      Throws:
      OpenYmlException - if resolution fails | 当解析失败时