Go Participle 怎么把解析错误定位到行列位置

我在把配置文本接入 Go 服务时，最先想解决的不是“能不能解析”，而是解析失败后能不能马上告诉用户哪一行、哪一列有问题。Go Participle v2 的错误对象已经保留了位置信息，不需要再拿原文手工数换行符：优先从 participle.Error 读取 Message() 和 Position()，再根据位置字段生成自己的提示。

官方地址：https://github.com/alecthomas/participle

先看清 Participle 错误里已经有什么

Participle 的公开文档把解析错误分成几个可用层次：participle.Error 是带 Message() 与 Position() 的错误接口，ParseError 是发生解析失败时常见的具体类型。FormatError 还能把错误格式化为“文件名:行:列:消息”这样的文本。

这里有一个很实用的判断：位置应当从错误对象读取，而不是从 err.Error() 的字符串里用正则反解析。字符串适合展示，结构化位置才适合日志字段、编辑器跳转和接口响应。

用 errors.As 提取带位置的解析错误

下面用一个很小的配置语法演示错误提取。示例只关注“如何取行列位置”，语法本身保持简单：每行是一个键值对，值只接受整数。代码中的注释说明每个分支为什么存在。

# 初始化一个独立示例目录，并使用 Participle v2
mkdir participle-position-demo
cd participle-position-demo
go mod init example.com/participle-position-demo
go get github.com/alecthomas/participle/v2

package main

import (
    "errors"
    "fmt"

    "github.com/alecthomas/participle/v2"
)

type Config struct {
    Entries []*Entry `@@*`
}

type Entry struct {
    Key   string `@Ident "="`
    Value int    `@Int`
}

// reportParseError 只负责把结构化错误变成稳定的诊断文本。
func reportParseError(err error) string {
    var parseErr *participle.ParseError
    if errors.As(err, &parseErr) {
        // Position 中保存文件名、行号、列号和偏移等词法位置。
        pos := parseErr.Position()
        return fmt.Sprintf("%s:%d:%d: %s", pos.Filename, pos.Line, pos.Column, parseErr.Message())
    }

    var located participle.Error
    if errors.As(err, &located) {
        // 其他实现了 participle.Error 的错误也保留它的位置。
        pos := located.Position()
        return fmt.Sprintf("%s:%d:%d: %s", pos.Filename, pos.Line, pos.Column, located.Message())
    }

    // IO 或自定义解析错误可能没有可用位置，不能伪造行列。
    return err.Error()
}

func main() {
    parser, err := participle.Build[Config]()
    if err != nil {
        // 构造语法失败属于启动错误，不是用户输入错误。
        panic(err)
    }

    input := "port = 8080\nworkers = wrong\n"
    _, err = parser.ParseString("settings.conf", input)
    if err != nil {
        // 让调用方获得文件名、行列和消息，而不是只看到一行裸字符串。
        fmt.Println(reportParseError(err))
    }
}

这个处理器有两层保护。第一层优先识别 *participle.ParseError，方便统计“解析失败”；第二层识别更宽的 participle.Error，避免自定义或包装后的定位错误丢失位置；最后才回退到普通 error 文本。这样既不会把所有错误强行标成解析错误，也不会因为错误被包装就丢掉行列。

把行列位置接到实际的输入边界

生产代码通常不是直接解析硬编码字符串，而是从文件、请求体或消息队列读取内容。关键做法是：在调用 Parse 或 ParseString 时传入稳定的文件名或来源名。这样 Position().Filename 才能成为真正有用的诊断字段。

func parseConfig(parser *participle.Parser[Config], filename string, input []byte) (*Config, error) {
    // ParseBytes 让 Participle 根据输入内容计算词法位置，并保留来源名。
    cfg, err := parser.ParseBytes(filename, input)
    if err == nil {
        return cfg, nil
    }

    var located participle.Error
    if errors.As(err, &located) {
        // 返回原始错误，调用方仍可读取 Position 和 Message。
        pos := located.Position()
        return nil, fmt.Errorf("配置解析失败 %s:%d:%d: %s", pos.Filename, pos.Line, pos.Column, located.Message())
    }

    // 读取失败、编码问题或自定义错误不一定拥有行列位置。
    return nil, fmt.Errorf("配置读取或解析失败: %w", err)
}

如果上层 API 需要 JSON 响应，可以把 Filename、Line、Column、Message 分成字段，而不是只保存拼接后的字符串。日志展示可以使用 participle.FormatError 或自定义文本，数据存储则优先保存结构化字段。

行号和列号出现偏差时先看三个边界

拿到位置后仍可能觉得“列号不对”，通常不是 Participle 少算了一列，而是输入边界和展示方式不同。

• 列号按 lexer 看到的字符计算。制表符、非 ASCII 字符和换行格式会影响人眼对列的估计，展示时应保留原始行文本供用户对照。
• 传入的来源名要稳定。不要把临时对象地址或随机请求 ID 当成文件名；错误响应里应能让人定位到真实配置来源。
• 不要把普通错误补成 0:0。没有位置时写“位置不可用”比伪造第一行第一列更可靠。

Participle 官方文档还提醒，增加 lookahead 会降低错误报告的准确度。若 grammar 存在多个分支，先把 UseLookahead 当成语法消歧工具，再接受它可能影响“最近错误位置”的取舍，不要为了更大的 lookahead 直接承诺更精确的行列。

最后形成一条可维护的诊断策略

我的实践是把错误处理拆成三件事：解析边界负责提供来源名，Participle 错误负责提供位置和消息，展示层负责决定给用户看一句话还是给日志写完整字段。这样改日志格式、改接口协议时，不会反过来污染 grammar 和解析流程。

常见问题

Participle 的错误一定都有行列位置吗？

不一定。文档说明错误在位置可用时才包含位置信息；IO、构造语法或自定义错误应允许回退到普通错误文本。

应该从 Error() 字符串里解析行号吗？

不建议。使用 participle.Error 的 Position() 读取结构化信息，展示格式变化时更稳定。

为什么增加 lookahead 后位置可能变化？

lookahead 会改变解析器为分支做判断时观察的 token 范围，官方文档明确提示更大的 lookahead 可能降低错误报告准确度，应按语法歧义需要取值。