Go Participle 怎么用结构体标签定义小型配置语法

如果配置格式只有几种固定结构，例如 key = "value" 的内部文件，不必马上引入完整配置语言。Go Participle 的做法是把语法写进结构体标签，让同一个结构体同时承担 AST 和语法说明两项职责。

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

本文只做一个小型键值配置：每行是一个标识符、一个等号和一个字符串值。重点是标签如何表达字段、重复项、递归项，以及调用方如何区分“解析器定义错了”和“输入文本不符合语法”。

先定义输入格式和 AST 边界

先把语法压缩到一个可以解释的边界。示例输入如下：

name = "service-a"
region = "east"
owner = "platform"

它的业务结果不是一棵复杂语法树，而是一组配置项。可以用根结构保存多条记录，用子结构描述单条记录：

package main

// Config 是整个配置文件的 AST 根节点。
type Config struct {
	Entries []*Entry `@@*`
}

// Entry 只描述一条 key = "value" 配置，不把业务校验塞进语法标签。
type Entry struct {
	Key   string `@Ident "="`
	Value string `@String`
}

这里有两个关键决定：Entries 是切片，说明根节点允许出现多条记录；Entry 是指针字段，说明每次匹配可以生成一个独立对象。结构体字段顺序就是语法顺序，因此标签不能只看成普通元数据。

用标签表达重复项和递归项

Participle 常用的几个符号分别对应不同的接口语义：

如果希望结构体标签还能和 JSON 标签共存，可以把语法放进命名的 parser 标签：

type Entry struct {
	// parser 标签保存 Participle 语法，json 标签服务另一条数据边界。
	Key string `parser:"@Ident \"=\"" json:"key"`
	// 字符串值仍然由词法器捕获，不在这里做业务默认值处理。
	Value string `parser:"@String" json:"value"`
}

不使用命名标签时，整个结构体标签都会被当作语法片段；使用 parser 后，其他反射标签就能保留下来。小型配置如果没有第二套序列化需求，可以选择更短的未命名写法。

构建解析器并解析配置文本

语法结构准备好后，用泛型 Build 根据根类型构建解析器，再把文本交给 ParseString：

package main

import (
	"fmt"

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

func parseConfig(source string) (*Config, error) {
	// Build 阶段检查标签能否组成合法文法，失败时还没有读取业务输入。
	parser, err := participle.Build[Config]()
	if err != nil {
		return nil, fmt.Errorf("build config parser: %w", err)
	}

	// ParseString 阶段只负责把本次输入映射到 Config。
	config, err := parser.ParseString("config", source)
	if err != nil {
		return nil, fmt.Errorf("parse config: %w", err)
	}
	return config, nil
}

调用方可以把错误分成两层：Build 错误表示结构体标签或词法配置需要修复；ParseString 错误表示某份输入没有满足既定格式。前者通常在启动阶段暴露，后者应带上文件名或配置来源返回给用户。

把接口语义和业务校验分开

Participle 标签适合描述“文本长什么样”，不适合承载所有业务约束。例如 region 是否只能是几个区域名，属于解析完成后的业务校验：

func validateConfig(config *Config) error {
	// 语法层只保证 key 和 value 能被读出，业务层再限制允许的键和值。
	for _, entry := range config.Entries {
		if entry.Key == "" {
			return fmt.Errorf("empty config key")
		}
		if entry.Key == "region" && entry.Value != "east" && entry.Value != "west" {
			return fmt.Errorf("unsupported region %q", entry.Value)
		}
	}
	return nil
}

这种分层让语法变更和业务规则变更互不牵连：增加一个新的配置键，只需保留同一条 Entry 语法；增加值域限制，则只改校验函数。

兼容策略：小语法什么时候该继续扩展

如果配置开始出现区块、数字和布尔值，可以新增子结构并用 | 表达备选值，但要先确认新分支的起始词法不会互相覆盖。不要为了“以后可能用到”一次性把标签写成一套完整语言。

一个实用的判断表如下：

常见问题

@@* 和 @* 有什么区别？

@@* 是重复调用字段类型自己的结构；@* 更适合重复捕获当前表达式的词法值。前者适合 []*Entry 这类递归对象，后者要结合字段类型和词法器规则谨慎使用。

为什么标签写对了仍然解析失败？

先看输入是否真的符合词法器产生的 token，再看标签里的字面量、字段顺序和重复符号。结构体标签只定义语法，不会替调用方自动修剪任意格式或补齐缺失分隔符。

什么时候不该用 Participle？

如果格式需要复杂的错误恢复、跨文件语义分析或大量上下文相关规则，建议把 Participle 只放在词法和 AST 入口，后续另设语义分析层；不要继续把所有规则堆进结构体标签。

总结一下：先用结构体表达 AST，再用 @ 捕获词法值、@@ 复用子结构、* 表达重复，最后把业务默认值和枚举约束放到解析之后。这样一个小型配置语法既容易读，也给后续扩展留下了清晰的接口边界。