如何将Ruby Hash转换为YAML并保留注释？

问题说明 #

我需要把带注释的Ruby Hash序列化为YAML时保留原有的注释，同时也想了解如何把带注释的YAML反向转回Ruby Hash。

Ruby示例代码 #

require 'yaml'

h = {
  # The garage in Miami
  'garage_A' => {
    'car_x' => {
      # Bought in Gotham
      'name' => 'Batmobile',
      'color' => 'black'
    }
  },
  'garage_B' => {
    # Mike's bike
    'bike_m' => {
      # Cherry red
      'color' => 'red',
      'wheels' => 2
    }
  }
}

puts YAML.dump(h)

期望YAML输出 #

---
# The garage in Miami
garage_A:
  car_x:
    # Bought in Gotham
    name: Batmobile
    color: black
garage_B:
  # Mike's bike
  bike_m:
    # Cherry red
    color: red
    wheels: 2

当前实际输出 #

---
garage_A:
  car_x:
    name: Batmobile
    color: black
garage_B:
  bike_m:
    color: red
    wheels: 2

解决方案 #

Ruby的Hash对象本身不会存储代码里的注释——这些注释只是Ruby代码的一部分，不属于Hash数据结构的内容，所以标准库的YAML.dump无法直接保留它们。要实现需求，有两种可行思路：

1. 自定义结构存储注释并手动生成YAML #

你可以把注释和键值对关联起来，用特殊结构存储（比如包含键、值、注释的数组），然后自己写逻辑生成带注释的YAML：

# 定义包含注释的配置结构
config_with_comments = [
  ['garage_A', {
    'car_x' => [
      ['name', 'Batmobile'],
      ['color', 'black', 'Bought in Gotham']
    ]
  }, 'The garage in Miami'],
  ['garage_B', {
    'bike_m' => [
      ['color', 'red', 'Cherry red'],
      ['wheels', 2]
    ]
  }, "Mike's bike"]
]

# 自定义YAML生成方法
def generate_yaml_with_comments(data, indent = 0)
  yaml = ''
  indent_str = '  ' * indent
  data.each do |item|
    if item.is_a?(Array)
      key, value, comment = item
      # 输出注释（如果存在）
      yaml += "#{indent_str}# #{comment}\n" if comment
      # 处理嵌套结构
      if value.is_a?(Hash) || (value.is_a?(Array) && value.first.is_a?(Array))
        yaml += "#{indent_str}#{key}:\n"
        yaml += generate_yaml_with_comments(value, indent + 1)
      else
        yaml += "#{indent_str}#{key}: #{value}\n"
      end
    elsif item.is_a?(Hash)
      item.each do |k, v|
        yaml += "#{indent_str}#{k}:\n"
        yaml += generate_yaml_with_comments(v, indent + 1)
      end
    end
  end
  # 根节点添加YAML头
  indent == 0 ? "---\n" + yaml : yaml
end

# 输出带注释的YAML
puts generate_yaml_with_comments(config_with_comments)

这段代码会生成符合期望的带注释YAML，注释和对应配置项的位置完全匹配。

2. 使用支持注释的第三方库 #

可以使用yaml-comments这类专门处理YAML注释的gem（先执行gem install yaml-comments安装）。它支持序列化和反序列化时保留注释，只需按照库的规则处理数据结构即可。

反向操作：带注释YAML转回Ruby Hash

对于反向需求，同样可以用yaml-comments库，它会把YAML解析成包含注释信息的特殊结构，你可以从中提取出纯Hash数据，同时保留注释内容供后续使用。

使用场景 #

某工具的默认配置原本以Ruby Hash形式存储，当目标配置文件不存在时，需要将默认配置转存为YAML格式。为了提升用户友好性，让用户无需查阅文档就能理解每个配置项的含义，要求生成的YAML文件必须保留原Hash中的注释说明。

内容的提问来源于stack exchange，提问作者noraj