Golang TOML 配置处理指南

TOML (Tom’s Obvious Minimal Language) 是一种易读的配置文件格式，Golang 中有优秀的第三方库来处理 TOML 文件。下面我将介绍如何使用 github.com/BurntSushi/toml 这个最流行的 TOML 库。

安装

首先安装库：

go get github.com/BurntSushi/toml

基本用法

1. 解析 TOML 文件

假设有一个 config.toml 文件：

title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00

[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002 ]
connection_max = 5000
enabled = true

解析代码：

package main

import (
	"fmt"
	"log"
	
	"github.com/BurntSushi/toml"
)

type Config struct {
	Title    string
	Owner    OwnerInfo
	Database Database `toml:"database"`
}

type OwnerInfo struct {
	Name string
	Dob  string `toml:"dob"` // 可以使用标签指定TOML中的字段名
}

type Database struct {
	Server         string
	Ports          []int
	ConnectionMax  int `toml:"connection_max"`
	Enabled        bool
}

func main() {
	var config Config
	
	// 解析TOML文件
	if _, err := toml.DecodeFile("config.toml", &config); err != nil {
		log.Fatal(err)
	}
	
	fmt.Printf("Title: %s\n", config.Title)
	fmt.Printf("Owner: %s (%s)\n", config.Owner.Name, config.Owner.Dob)
	fmt.Printf("Database: %s %v (max conn: %d, enabled: %t)\n",
		config.Database.Server,
		config.Database.Ports,
		config.Database.ConnectionMax,
		config.Database.Enabled)
}

2. 生成 TOML 文件

将 Go 结构体编码为 TOML：

func writeTOML() {
	config := Config{
		Title: "Sample Config",
		Owner: OwnerInfo{
			Name: "John Doe",
			Dob:  "1980-01-01T00:00:00Z",
		},
		Database: Database{
			Server:        "127.0.0.1",
			Ports:         []int{8080, 8081},
			ConnectionMax: 1000,
			Enabled:       true,
		},
	}

	// 创建文件
	f, err := os.Create("output.toml")
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()

	// 编码并写入文件
	enc := toml.NewEncoder(f)
	if err := enc.Encode(config); err != nil {
		log.Fatal(err)
	}
	
	fmt.Println("TOML file created successfully")
}

3. 元数据控制

toml 包还提供了元数据访问功能：

func metaExample() {
	var config Config
	meta, err := toml.DecodeFile("config.toml", &config)
	if err != nil {
		log.Fatal(err)
	}

	// 获取未映射的键
	fmt.Println("Undecoded keys:", meta.Undecoded())
	
	// 检查某个键是否存在
	if meta.IsDefined("database", "server") {
		fmt.Println("Database server is defined")
	}
}

高级特性

1. 内联表

处理内联表：

[name]
first = "Tom"
last = "Preston-Werner"

# 内联表写法
[person]
name = { first = "Tom", last = "Preston-Werner" }

对应的 Go 结构体：

type Person struct {
	Name struct {
		First string
		Last  string
	} `toml:"name"`
}

type InlinePerson struct {
	Person struct {
		Name Name `toml:"name"`
	} `toml:"person"`
}

type Name struct {
	First string
	Last  string
}

2. 时间处理

TOML 有原生日期时间支持：

time = 1979-05-27T07:32:00-08:00

Go 中可以使用 time.Time 类型：

type TimeExample struct {
	Time time.Time
}

3. 自定义 Marshal/Unmarshal

实现 toml.Marshaler 和 toml.Unmarshaler 接口：

type Custom struct {
	Data string
}

func (c *Custom) UnmarshalTOML(data interface{}) error {
	// 自定义解析逻辑
	return nil
}

func (c Custom) MarshalTOML() ([]byte, error) {
	// 自定义编码逻辑
	return []byte(`"` + c.Data + `"`), nil
}

最佳实践

1. 配置文件位置：通常放在 ./config.toml 或 /etc/app/config.toml
2. 环境变量覆盖：可以使用环境变量覆盖配置值
3. 默认值：在结构体中设置合理的默认值
4. 配置验证：解析后验证配置值是否有效

替代库

除了 BurntSushi/toml，还有其他 TOML 实现：

• pelletier/go-toml：功能更丰富，支持更多 TOML 特性
• naoina/toml：另一个轻量级实现

选择哪个库取决于你的具体需求，BurntSushi/toml 是最稳定和广泛使用的。

希望这个指南能帮助你开始在 Golang 项目中使用 TOML 配置文件！