Go groot 怎样列出ROOT文件中的对象键

用 Go 的 go-hep.org/x/hep/groot 列出 ROOT 文件对象键，核心就是打开文件后遍历 File.Keys()。每个键都能提供对象名称、ROOT 类名、标题和 cycle；这一步只做目录清单，不会自动把对象内容读成直方图、树或图形。官方文档地址：https://pkg.go.dev/go-hep.org/x/hep/groot。

最小做法是 groot.Open、defer f.Close()、遍历 f.Keys()，再按需读取 key.Name()、key.ClassName()、key.Title() 和 key.Cycle()。先列键、后读对象，排查 ROOT 文件时更容易定位问题。

对象键和对象内容不是一回事

ROOT 文件中的对象通常由一个键描述名称、类名、标题和写入周期，真正的数据负载还需要按照对应类型解码。Keys() 返回的是当前文件目录里的键集合，适合做目录浏览、类型筛选和后续读取决策；它不是对所有嵌套目录的递归扫描，也不会替你完成类型断言。

因此，标题为 events 的键可能指向一棵树，标题为 energy 的键可能指向直方图。先打印 ClassName()，再决定使用哪个包的接口读取内容，能避免把所有对象都强行当成同一种类型。

先打开文件并安排关闭动作

读取入口使用 groot.Open。打开成功后要尽早登记 Close，这样后面的枚举或对象读取发生错误时，也不会遗漏底层文件资源。下面的代码只演示目录枚举，不依赖本地 ROOT/C++ 安装。

package main

import (
    "fmt"
    "log"

    "go-hep.org/x/hep/groot"
)

func listKeys(path string) error {
    // Open 只负责建立 ROOT 文件读取入口，失败时把路径带回上层。
    f, err := groot.Open(path)
    if err != nil {
        return fmt.Errorf("打开 ROOT 文件 %q: %w", path, err)
    }
    // 无论后续枚举是否出错，都要释放文件句柄和关联资源。
    defer f.Close()

    // Keys 枚举当前目录的键；它不会自动递归进入嵌套目录。
    for _, key := range f.Keys() {
        fmt.Printf("name=%q class=%q title=%q cycle=%d\\n",
            key.Name(), key.ClassName(), key.Title(), key.Cycle())
    }
    return nil
}

func main() {
    if err := listKeys("sample.root"); err != nil {
        // 把打开或读取阶段的错误作为命令失败返回，而不是打印空清单。
        log.Fatal(err)
    }
}

这个函数的关键点不是输出格式，而是把“打开失败”和“文件为空”区分开：打开失败会返回错误，打开成功但没有键时则只是没有可枚举对象。生产代码可以把输出改成结构化日志或 JSON，但应保留键名和类型字段。

遍历 Keys 读取哪些字段

Key 的四个字段适合组成一行目录摘要：

• Name()：后续传给 f.Get 的对象名称。
• ClassName()：ROOT 对象的类名，用来决定下一步的 Go 类型。
• Title()：文件写入者给对象设置的说明性标题，可能为空。
• Cycle()：同名对象的写入周期；同一个名字出现多次时不要只按名字去重。

如果清单用于排查数据文件，建议把 name 和 class 作为稳定字段，把 title 当作辅助描述。标题可能由上游程序留空，但空标题不代表键无效。

需要内容时再按名称调用 Get

目录枚举之后，如果确认某个键是目标对象，再用 f.Get(keyName) 读取它。读取结果是通用对象，需要依据 ClassName() 和项目约定做类型判断；不要因为键名看起来像树或直方图，就跳过错误检查和类型断言。

func findObject(path, wanted string) (string, error) {
    // 先建立文件读取入口，再用 defer 保证所有返回路径都关闭文件。
    f, err := groot.Open(path)
    if err != nil {
        return "", fmt.Errorf("打开 ROOT 文件失败: %w", err)
    }
    defer f.Close()

    for _, key := range f.Keys() {
        // 只按键名筛选，避免先把所有大对象载入内存。
        if key.Name() != wanted {
            continue
        }
        obj, err := f.Get(wanted)
        if err != nil {
            return "", fmt.Errorf("读取对象 %q 失败: %w", wanted, err)
        }
        // 这里返回类名和对象的动态类型，具体断言放在调用方边界。
        return fmt.Sprintf("key-class=%s object-type=%T", key.ClassName(), obj), nil
    }
    return "", fmt.Errorf("对象键 %q 不存在", wanted)
}

示例把动态对象返回给调用方，是为了突出职责边界：Keys() 负责发现，Get 负责取对象，业务代码负责把它转换成 rtree.Tree、直方图或其他接口。对于同名不同 cycle 的文件，若业务必须精确选择某个周期，还应把周期选择规则写清楚，而不是依赖枚举顺序。

嵌套目录和异常文件怎么处理

如果 ROOT 文件包含目录层级，顶层 Keys() 只解决当前目录的清单问题。遇到目录键时，应先读取目录对象，再使用该目录对应的枚举能力；不要把操作系统路径拼接规则当成 ROOT 对象路径规则。

常见错误可以按三类处理：

• 打开失败：路径错误、权限不足或文件格式无法识别，直接返回错误。
• 清单为空：文件可以打开，但当前目录没有键；这不等于读取成功拿到了业务对象。
• 键可见但 Get 失败：对象负载损坏、类不受支持或读取方式不匹配，应记录键名和类名，避免只记录一条模糊错误。

groot 的定位是纯 Go 读写 ROOT 文件；常规读取不要求先安装 ROOT/C++。只有涉及生成兼容性测试文件或执行特定的 go generate 流程时，才可能需要额外的 ROOT/C++ 环境。

常见问题

为什么 Keys() 看不到嵌套目录里的对象？

因为它列的是当前目录。先识别目录键，再进入对应目录读取下一层，不要把顶层清单理解成递归结果。

只有对象名称，没有标题时正常吗？

正常。Title() 是辅助描述，可能为空；判断对象身份时优先看名称、类名和 cycle。

列键时需要先安装 ROOT/C++ 吗？

常规的 groot.Open、Keys() 和 Get 读取路径不要求本机安装 ROOT/C++。兼容性生成或特定生成流程才可能需要它。

为什么不直接把每个键都调用 Get？

枚举阶段通常只需要元数据。先筛选名称和类名，再读取目标对象，可以减少无意义的解码，也更容易处理不支持或损坏的对象。

总结一下：Go groot 列出 ROOT 文件对象键的最小路径是 groot.Open 加 f.Keys()。把 Name、ClassName、Title 和 Cycle 作为目录摘要，确认目标后再用 Get 读取内容，能让文件浏览、类型判断和业务解析保持清晰分层。