Go go-toml 怎么把 TOML 表数组解码为结构体切片

使用 github.com/pelletier/go-toml/v2 时，TOML 的表数组 [[servers]] 可以直接对应 Go 结构体里的 []Server。关键是让外层结构体字段名或 toml 标签对应表名，让每个表内的键对应 Server 的导出字段。单次内容可以用 toml.Unmarshal，来自文件或网络流时可以改用 toml.NewDecoder。

官方地址：https://github.com/pelletier/go-toml

先把 TOML 表数组和 Go 类型对齐

表数组表示同名表可以出现多次，每一次都产生一个元素。下面的 [[servers]] 有两条记录，因此目标结构体不应该写成单个 Server，而是写成 []Server：

# 每个 [[servers]] 都对应 []Server 的一个元素。
[[servers]]
name = "api"
host = "api.internal"
port = 8080

[[servers]]
name = "worker"
host = "worker.internal"
port = 9090

package main

// 这个示例只描述 TOML 表数组与结构体切片的字段契约。
type Server struct {
	Name string `toml:"name"` // 表内的 name 键进入 Name 字段。
	Host string `toml:"host"` // 表内的 host 键进入 Host 字段。
	Port int    `toml:"port"` // 端口使用整数，避免用字符串承接数值。
}

type Config struct {
	Servers []Server `toml:"servers"` // servers 表数组对应结构体切片。
}

这里的 toml:"servers" 是外层表名映射，toml:"name"、toml:"host" 和 toml:"port" 是表内字段映射。字段必须导出，否则 Go 的反射解码无法把值写入未导出的字段。

用 Unmarshal 一次性解码到 []Server

如果 TOML 内容已经在字节切片中，toml.Unmarshal 是最短的入口。它接收 TOML 字节和目标值指针，返回解码错误；目标值要传地址，库才能填充 Config.Servers：

package main

import (
	"fmt"
	"log"

	"github.com/pelletier/go-toml/v2"
)

type Server struct {
	Name string `toml:"name"` // 与每个 servers 表中的 name 对应。
	Host string `toml:"host"` // 保存主机名或内部服务地址。
	Port int    `toml:"port"` // TOML 整数直接解码为 Go int。
}

type Config struct {
	Servers []Server `toml:"servers"` // 接收重复出现的 [[servers]]。
}

func main() {
	doc := []byte(`
[[servers]]
name = "api"
host = "api.internal"
port = 8080

[[servers]]
name = "worker"
host = "worker.internal"
port = 9090
`)

	var cfg Config
	// 传入 &cfg，解码器才能把表数组写入目标结构体。
	if err := toml.Unmarshal(doc, &cfg); err != nil {
		log.Fatalf("解码 TOML 失败: %v", err)
	}

	// 用切片长度和字段值核对每个表是否形成一个元素。
	fmt.Println("服务器数量:", len(cfg.Servers))
	for _, server := range cfg.Servers {
		fmt.Printf("%s %s:%d\n", server.Name, server.Host, server.Port)
	}
}

调用成功后，cfg.Servers[0] 是 api，cfg.Servers[1] 是 worker。这正是 “Array of Tables → slice + struct” 的组合：数组决定切片，表决定元素结构。

来自文件或网络流时使用 Decoder

当输入实现了 io.Reader，可以用 toml.NewDecoder 避免先把完整内容手动放进字节切片。Decode 仍然接收目标结构体指针，字段映射规则不变：

package main

import (
	"io"
	"log"
	"strings"

	"github.com/pelletier/go-toml/v2"
)

// decodeServers 保持 Reader 由调用方提供，便于接入文件或 HTTP 响应体。
func decodeServers(r io.Reader) (Config, error) {
	var cfg Config
	decoder := toml.NewDecoder(r)
	// Decode 读取整个 Reader 的 TOML 内容并写入 cfg。
	if err := decoder.Decode(&cfg); err != nil {
		return Config{}, err
	}
	return cfg, nil
}

func main() {
	input := strings.NewReader(`
[[servers]]
name = "api"
host = "api.internal"
port = 8080
`)

	cfg, err := decodeServers(input)
	if err != nil {
		log.Fatal(err)
	}
	log.Println("读取到:", len(cfg.Servers), "个服务器")
}

如果 Reader 来自文件，调用方仍要负责打开和关闭文件；如果来自 HTTP 响应体，也要按调用方的资源生命周期关闭响应体。Decoder 只负责从 Reader 解析 TOML，不替调用方管理 Reader。

需要严格字段契约时打开未知字段检查

默认解码时，目标结构体没有对应字段的 TOML 键会被忽略。如果配置拼写错误不能被静默接受，可以在 Decoder 上调用 DisallowUnknownFields：

func decodeStrict(r io.Reader) (Config, error) {
	var cfg Config
	decoder := toml.NewDecoder(r)
	// 严格模式把目标结构体不存在的键变成解码错误。
	decoder.DisallowUnknownFields()
	if err := decoder.Decode(&cfg); err != nil {
		return Config{}, err
	}
	return cfg, nil
}

例如 TOML 把 hostname 写进 [[servers]]，但结构体只有 Host，严格模式就能在解码阶段报告未知字段。若配置来自多个团队维护，严格模式更适合尽早暴露拼写错误；若配置需要前后兼容、允许暂时存在额外键，则可以保留默认模式。

根据错误类型定位字段和输入

语法错误、类型错误和严格模式的未知字段都应该保留原始错误，不要只返回一个“配置失败”的字符串。go-toml 提供了带上下文的 DecodeError，它可以给出错误位置；严格模式下的字段缺失信息则可以用对应错误类型继续处理。

package main

import (
	"errors"
	"fmt"

	"github.com/pelletier/go-toml/v2"
)

func reportDecodeError(err error) {
	var decodeErr *toml.DecodeError
	// 通过 errors.As 保留库提供的上下文和行列位置。
	if errors.As(err, &decodeErr) {
		row, column := decodeErr.Position()
		fmt.Printf("TOML 错误位置: 第 %d 行第 %d 列\n", row, column)
		fmt.Println(decodeErr.String())
		return
	}

	// 其他错误仍然原样返回给上层，不丢失严格模式信息。
	fmt.Println("TOML 解码失败:", err)
}

这里不要把 DecodeError 和业务校验错误混为一谈：前者说明 TOML 解析或类型映射阶段出了问题，后者才是解码完成后对端口范围、服务名格式等业务规则的判断。先分层，日志才容易定位。

一张表选定最终写法

最容易出错的地方有三个：把表数组误写成单个结构体、忘记传目标结构体地址、以及把默认忽略未知字段误认为是严格校验。围绕这三个点设计输入结构和错误处理，基本就能稳定完成 TOML 表数组到结构体切片的解码。

相关问题

一个 TOML 表数组元素可以嵌套子表吗？

可以，目标元素结构体继续嵌套结构体或对应的切片，并为名称不同的键补充 toml 标签。本文只聚焦最外层 [[servers]] 到 []Server 的映射。

为什么解码后切片为空？

先检查表名是否与外层字段或 toml 标签一致，再确认传入的是 &cfg，以及 TOML 使用的是重复的 [[servers]] 而不是单个 [servers]。

默认模式会报未知字段吗？

默认情况下，目标结构体没有对应字段的键会被忽略；需要把它变成错误时，在 Decoder 上调用 DisallowUnknownFields。