Go txtar.Parse 怎样拆分文本归档中的文件段

txtar.Parse(data) 会把文本归档拆成一个 Archive：首个有效文件标记之前的内容放入 Comment，后续每个文件段按出现顺序放入 Files，其中 Name 是名称、Data 是内容。文件标记应是独占一行的 -- 文件名 --，不是 Markdown 标题或任意分隔线。Parse 只返回归档对象，没有 error 返回值，也不会把文件写到磁盘。

官方地址：https://pkg.go.dev/golang.org/x/tools/txtar

先分清注释区和文件标记行

把几份小型测试数据放在同一个文本文件里，便于一并提交和审阅；自动任务再按文件段读取它们。若读取后只得到 Comment，没有预期的 Files，我会先查看分隔行的字面形式，而不是怀疑文件内容长度。

标记行以两个减号和一个空格开头，以一个空格和两个减号结尾。名称两边额外的空白会被去除；普通内容一直延续到下一个有效标记行。开头说明文字不需要以井号开头，也不是某个文件的数据。

例如先写一段说明，再写 -- input.txt --，其后的文字归入 input.txt；接着出现 -- expected.txt --，后续文字就属于第二段。文件名称只是归档中的字符串，不代表解析器已经在系统上打开了这个路径。

解析后按 Files 顺序读取各段

下面的封装为输入建立独立底层存储，并把“至少有一个文件段”作为本工具的业务要求。Describe 生成的是段清单，保留 Files 的原始顺序，不做同名文件合并。

package fixtures

import (
    "fmt"

    "golang.org/x/tools/txtar"
)

// ParseOwned 为调用方保留一份独立的输入存储，并要求至少包含一个文件段。
func ParseOwned(input []byte) (*txtar.Archive, error) {
    // Parse 返回的数据可能引用输入切片，因此先复制底层字节。
    owned := append([]byte(nil), input...)
    archive := txtar.Parse(owned)
    if len(archive.Files) == 0 {
        return nil, fmt.Errorf("归档中没有文件段，请检查标记行")
    }
    return archive, nil
}

// Describe 只生成清单，不创建目录，也不把文件内容写入磁盘。
func Describe(archive *txtar.Archive) []string {
    lines := make([]string, 0, len(archive.Files))
    for index, file := range archive.Files {
        lines = append(lines, fmt.Sprintf(
            "第 %d 段，名称 %q，内容 %d 字节",
            index+1, file.Name, len(file.Data),
        ))
    }
    return lines
}

项目需要依赖 golang.org/x/tools 模块。调用方先用自己的文件读取或请求读取逻辑取得 input，再调用 ParseOwned；读入失败属于输入来源错误，与 txtar 内存解析不是同一个阶段。示例没有实际执行，没有列出虚构的文件段清单。

Comment 和每段 Data 都是字节切片。需要展示内容时可转成字符串，需要比较预期文件时则可按字节处理；不要因为它是一种文本归档，就在读取后对全部 Data 自动 TrimSpace。首尾空格、空行和换行可能正是测试样例想表达的内容。

没有解析错误不等于满足业务要求

官方格式说明认为 txtar 不存在语法错误。这个特点不代表随便输入一段文本就符合应用预期：没有标记的内容也能被解释为注释。因此 ParseOwned 中的错误来自我们自己的文件段数量约定，不是伪造一个 Parse 的错误返回值。

格式也没有通用的内容转义机制来表达“这一行看起来像文件标记，但必须保留在正文里”。若要存放的文本经常包含这样的行，应重新评估归档表示，而不是指望用缩进或替换字符后还能保持原始字节内容。

保留文件顺序与底层字节的归属

Parse 的归档数据会持有输入的切片。若调用方把 input 放回字节池，或者之后覆盖原缓冲区，归档内容就可能跟着变化。示例先复制输入，再解析这份副本，使外部对 input 的修改不影响返回对象。

这不是说返回的 Archive 自动变为不可变对象。调用方仍然能够修改 Comment 或 File.Data；并发读取时应保持数据稳定。需要把某一段单独交给会改写内容的代码时，再复制那一段会更清楚。

同样，直接把 Files 转成 map[string][]byte 会失去段顺序，还必须决定同名段覆盖谁。如果自动任务依赖先后顺序或希望定位第几个段，就继续使用切片，在确实需要按名称索引时另建索引，并明确重复名称如何处理。

把内存拆分接入自动化任务

我会把读取输入、拆分归档、应用业务规则和消费文件内容放在可区分的位置。这样“没有文件段”“缺少 expected.txt”“输入读取失败”不会混成一个笼统的归档错误。任务记录可以包含段序号、名称和字节数，不必把全部内容都写入日志。

若后续功能需要真正解包到磁盘，应另行设计目标目录、文件名处理、重复名称和覆盖策略。Parse 不负责这些权限与路径约束，不能因为数据已经进入 Files，就直接将所有 Name 当作可写目标。本例停留在内存清单，不执行解包。

txtar 适合人工编辑的小型文本样例，不以通用二进制归档、文件权限或符号链接存储为目标。需要精确保存这些信息时，应选择适合的格式和处理接口，而不是继续给文件标记添加未经定义的附加字段。

常见问题：Parse 为什么没有第二个返回值？它按格式规则解释文本，文件读取和业务要求另行处理。纯注释归档可以解析吗？可以，本例只是主动拒绝没有文件段的输入。它会创建 input.txt 吗？不会。为什么重名文件没自动合并？Files 表示段序列，合并不是 Parse 的职责。

参考：txtar 官方格式与 API；Parse 和文件标记实现。