1. 为什么我们需要手写YmlUtils？

每次做项目配置迁移时，最头疼的就是格式转换问题。上周我接手一个老项目改造，需要把上百个YAML配置迁移到只支持Properties格式的配置中心。试了市面上所有转换工具后，发现它们都存在几个致命问题：

• 原文件被覆盖：就像IDEA的Convert插件，转换后原始YAML直接消失，想回看配置得去翻Git历史
• 注释全丢失：团队辛苦写的配置说明全变成光秃秃的键值对
• 顺序混乱：开发时精心分组的配置项被打乱成字典序
• 跨平台限制：只能在特定IDE使用，CI/CD流程中无法集成

最坑的是遇到多层嵌套配置时，像这样的结构：

spring: datasource: master: url: jdbc:mysql://localhost:3306/main # 生产环境需修改 username: root slave: url: jdbc:mysql://backup:3306/main

转换后不仅缩进关系丢失，关键注释也不见了。这就是为什么我决定自己造轮子——用纯Java实现一个零依赖的YmlUtils工具类。

2. 现有转换方案的致命缺陷

2.1 IDEA插件的问题实测

Convert YAML and Properties File这个插件看起来方便，但实际测试时会发现：

1. 文件覆盖风险：转换后原YAML文件直接被替换，没有备份机制
2. 注释处理缺陷：无论是行首的# 说明还是行尾的key: value # 备注都会被丢弃
3. 格式错乱：转换后的Properties文件变成纯字母序排列，破坏原有逻辑分组
4. 空值问题：未配置的项会显示为key=null而非保持空值

2.2 在线工具的局限性

像ToYaml.com这类在线转换器：

• 安全隐患：敏感配置如数据库密码可能通过公网传输
• 批量处理困难：每次只能单个文件操作
• 无版本控制：无法与Git等版本管理系统集成
• 定制化缺失：不能按项目需求调整转换规则

2.3 第三方库的依赖负担

SnakeYAML等库虽然强大，但：

• 会增加项目依赖复杂度
• 可能引发版本冲突
• 对Android等轻量级环境不友好

3. YmlUtils的核心设计思路

3.1 无损转换的三大原则

1. 原文保留：原YAML文件保持只读，输出到新Properties文件
2. 注释继承：行级注释转为# 注释，行尾注释单独成行
3. 顺序保持：严格按YAML中的出现顺序输出

3.2 关键数据结构设计

用YmlNode类记录每个配置项的元信息：

class YmlNode { private Integer level; // 缩进层级 private String key; // 组合后的key（如spring.datasource.url） private String value; private String headRemark;// 行首注释 private String tailRemark;// 行尾注释 private Boolean last; // 是否末级节点 }

3.3 转换流程分解

1. 文件读取：用FileInputStream按UTF-8读取YAML
2. 行解析：通过缩进空格数判断层级关系
3. 键名组合：处理多级key的拼接（如spring.datasource.url）
4. 注释处理：识别#符号位置决定注释类型
5. 结果输出：按原始顺序写入Properties文件

4. 完整实现与使用示例

4.1 核心转换方法

public static List<YmlNode> castProperties(String ymlFileName) { // 参数校验 if (!ymlFileName.endsWith(".yml")) { throw new RuntimeException("请指定.yml文件"); } // 读取文件内容 String ymlContent = readFile(new File(ymlFileName)); // 解析为节点列表 List<YmlNode> nodes = parseNodes(ymlContent); // 输出到properties文件 writePropertiesFile(ymlFileName, nodes); return nodes; }

4.2 缩进层级计算

处理YAML最关键的缩进识别：

private static int getNodeLevel(String line) { char[] chars = line.toCharArray(); int spaceCount = 0; for (char c : chars) { if (c != ' ') break; spaceCount++; } return spaceCount / 2; // 按2空格为一级缩进 }

4.3 注释保留策略

// 行首注释处理 if (line.trim().startsWith("#")) { node.setHeadRemark(line.replaceFirst("#", "").trim()); return node; } // 行尾注释处理 if (value.contains(" #")) { String[] parts = value.split("#", 2); node.setValue(parts[0].trim()); node.setTailRemark(parts[1].trim()); }

4.4 实际使用案例

假设有application-dev.yml：

# 数据库配置 db: master: url: jdbc:mysql://localhost:3306/app # 主库地址 pool: 20

转换调用：

YmlUtils.castProperties("application-dev.yml");

生成application-dev.properties：

# 数据库配置 db.master.url=jdbc:mysql://localhost:3306/app # 主库地址 db.master.pool=20

5. 高级功能扩展

5.1 多文件批量处理

添加批量转换方法：

public static void batchConvert(String[] ymlFiles) { Arrays.stream(ymlFiles) .parallel() .forEach(YmlUtils::castProperties); }

5.2 键名前缀过滤

支持只转换特定前缀的配置：

public static List<YmlNode> filterByPrefix(List<YmlNode> nodes, String prefix) { return nodes.stream() .filter(n -> n.getKey().startsWith(prefix)) .collect(Collectors.toList()); }

5.3 与Spring配置集成

在Spring Boot中自动加载：

@Bean @ConfigurationProperties public Properties ymlConfig() throws IOException { Properties props = new Properties(); Map<String, String> map = YmlUtils.getPropertiesMap("application.yml"); props.putAll(map); return props; }

6. 性能优化与异常处理

6.1 大文件处理优化

采用流式读取避免OOM：

try (BufferedReader reader = Files.newBufferedReader(path)) { String line; while ((line = reader.readLine()) != null) { // 逐行处理 } }

6.2 错误恢复机制

• 记录失败行号
• 自动生成.error.log
• 支持断点续转

try { // 转换逻辑 } catch (Exception e) { log.error("转换失败，行号: {}", currentLine); throw new RuntimeException("转换中断，已处理部分已保存"); }

7. 实际项目中的踩坑经验

1. 编码问题：Windows下需显式指定UTF-8
2. 特殊字符：处理包含冒号的值时需要额外转义
3. 空行保留：有些工具会忽略空行破坏格式
4. 性能陷阱：超过10MB的YAML文件需要特殊处理

记得有次处理K8s的configMap时，因为没处理好多行字符串的|语法，导致整个服务启动失败。后来在解析逻辑里加了这样的特殊判断：

if (line.contains("|")) { // 处理多行文本块 node.setValue(parseMultiLineText(reader)); }

这个工具类现在已经在我们团队内部使用了两年多，经历过三次大版本迭代。最让我自豪的是有次帮运维同事快速迁移了300+微服务的配置，相比人工操作至少节省了40人/天的工作量。