pelletier/go-toml
GitHub: pelletier/go-toml
Go 语言的 TOML 格式解析与序列化库，提供高性能的编解码能力和友好的错误提示。
Stars: 1961 | Forks: 247
# go-toml v2
用于 [TOML](https://toml.io/en/) 格式的 Go 库。
本库支持 [TOML v1.1.0](https://toml.io/en/v1.1.0)。
[🐞 Bug 报告](https://github.com/pelletier/go-toml/issues)
[💬 其他问题](https://github.com/pelletier/go-toml/discussions)
## 文档
完整的 API、示例和实现说明可在 Go 文档中找到。
[](https://pkg.go.dev/github.com/pelletier/go-toml/v2)
## 导入
```
import "github.com/pelletier/go-toml/v2"
```
## 功能
### 标准库行为
尽可能地，本库在设计上与标准库的 `encoding/json` 行为保持一致。
在对结构体进行编码时，如果带有 `omitempty` 标签的字段为空，则会被省略。对于 `time.Time`，零值被视为空，因此除非您从结构体标签中移除 `omitempty` 或使用指针类型（`*time.Time`），否则不会写入诸如 `created_at` 或 `updated_at` 之类的时间戳。
### 性能
虽然 go-toml 倾向于易用性，但它在编写时也充分考虑了性能。大多数操作不应该慢得离谱。请参阅[基准测试](#benchmarks)。
### 严格模式
`Decoder` 可以设置为“严格模式”，当 TOML 文档的某些部分未在目标结构中体现时，它会报错。这是检查拼写错误的好方法。[在文档中查看示例][strict]。
### 上下文错误
当发生大多数解码错误时，go-toml 会返回 [`DecodeError`][decode-err]，其中包含人类可读的带有上下文的错误信息。例如：
```
1| [server]
2| path = 100
| ~~~ cannot decode TOML integer into struct field toml_test.Server.Path of type string
3| port = 50
```
### 带注释的配置
由于 TOML 通常用于配置文件，go-toml 可以生成带有[注释和被注释掉的值][comments-example]的文档。例如，它可以生成以下文件：
```
# 要连接的 Host IP。
host = '127.0.0.1'
# 远程服务器的端口。
port = 4242
# 加密参数（可选）
# [TLS]
# cipher = 'AEAD-AES128-GCM-SHA256'
# version = 'TLS 1.3'
```
## 快速开始
给定以下结构体，让我们看看如何读取它并将其写入为 TOML：
```
type MyConfig struct {
Version int
Name string
Tags []string
}
```
### Unmarshal
请注意，结构体变量名是_首字母大写_的，而 toml 文档中的变量是_小写_的。
例如：
```
doc := `
version = 2
name = "go-toml"
tags = ["go", "toml"]
`
var cfg MyConfig
err := toml.Unmarshal([]byte(doc), &cfg)
if err != nil {
panic(err)
}
fmt.Println("version:", cfg.Version)
fmt.Println("name:", cfg.Name)
fmt.Println("tags:", cfg.Tags)
// Output:
// version: 2
// name: go-toml
// tags: [go toml]
```
这是一个包含简单嵌套 table 的示例：
```
doc := `
age = 45
fruits = ["apple", "pear"]
# 这些非常重要！
[my-variables]
first = 1
second = 0.2
third = "abc"
# 这没那么重要。
[my-variables.b]
bfirst = 123
`
var Document struct {
Age int
Fruits []string
Myvariables struct {
First int
Second float64
Third string
B struct {
Bfirst int
}
} `toml:"my-variables"`
}
err := toml.Unmarshal([]byte(doc), &Document)
if err != nil {
panic(err)
}
fmt.Println("age:", Document.Age)
fmt.Println("fruits:", Document.Fruits)
fmt.Println("my-variables.first:", Document.Myvariables.First)
fmt.Println("my-variables.second:", Document.Myvariables.Second)
fmt.Println("my-variables.third:", Document.Myvariables.Third)
fmt.Println("my-variables.B.Bfirst:", Document.Myvariables.B.Bfirst)
// Output:
// age: 45
// fruits: [apple pear]
// my-variables.first: 1
// my-variables.second: 0.2
// my-variables.third: abc
// my-variables.B.Bfirst: 123
```
### Marshal
[`Marshal`][marshal] 是 Unmarshal 的反向操作：它将 Go 结构体表示为 TOML 文档：
```
cfg := MyConfig{
Version: 2,
Name: "go-toml",
Tags: []string{"go", "toml"},
}
b, err := toml.Marshal(cfg)
if err != nil {
panic(err)
}
fmt.Println(string(b))
// Output:
// Version = 2
// Name = 'go-toml'
// Tags = ['go', 'toml']
```
## 不稳定的 API
### Parser
Parser 是一个不稳定的 API，允许在 AST 级别对 TOML 文档进行迭代解析。请参阅 https://pkg.go.dev/github.com/pelletier/go-toml/v2/unstable。
## 基准测试
与其他 Go TOML 库相比，执行时间的加速比：
## 工具
Go-toml 提供了三个方便的命令行工具：
### Docker 镜像
这些工具也以 [Docker 镜像][docker] 的形式提供。例如，要使用 `tomljson`：
```
docker run -i ghcr.io/pelletier/go-toml:v2 tomljson < example.toml
```
可以在 [ghcr.io][docker] 上找到多个版本。
## 版本控制
除明确标记的部分外，go-toml 遵循 [语义化版本](https://semver.org)。支持的 [TOML](https://github.com/toml-lang/toml) 版本已在本文档开头指出。支持最新的两个 Go 主版本（请参阅 [Go 发布策略](https://golang.org/doc/devel/release.html#policy)）。
## 许可证
The MIT License (MIT)。请阅读 [LICENSE](LICENSE)。
| 基准测试 | go-toml v1 | BurntSushi/toml |
|---|---|---|
| Marshal/HugoFrontMatter-2 | 2.3x | 2.4x |
| Marshal/ReferenceFile/map-2 | 2.2x | 2.6x |
| Marshal/ReferenceFile/struct-2 | 4.9x | 5.0x |
| Unmarshal/HugoFrontMatter-2 | 7.8x | 5.9x |
| Unmarshal/ReferenceFile/map-2 | 6.8x | 6.4x |
| Unmarshal/ReferenceFile/struct-2 | 6.8x | 6.3x |
查看更多
上表包含了最常见的使用场景的结果。下表包含了所有基准测试的结果，包括一些不切实际的测试。提供这些结果是为了保证完整性。
| 基准测试 | go-toml v1 | BurntSushi/toml |
|---|---|---|
| Marshal/SimpleDocument/map-2 | 2.1x | 3.1x |
| Marshal/SimpleDocument/struct-2 | 3.4x | 4.8x |
| Unmarshal/SimpleDocument/map-2 | 10.1x | 7.0x |
| Unmarshal/SimpleDocument/struct-2 | 12.4x | 8.0x |
| UnmarshalDataset/example-2 | 8.2x | 6.9x |
| UnmarshalDataset/code-2 | 7.5x | 8.3x |
| UnmarshalDataset/twitter-2 | 9.0x | 7.6x |
| UnmarshalDataset/citm_catalog-2 | 5.0x | 4.5x |
| UnmarshalDataset/canada-2 | 6.4x | 4.7x |
| UnmarshalDataset/config-2 | 10.2x | 6.1x |
| geomean | 5.8x | 5.3x |
可以使用 ./ci.sh benchmark -a -html 生成此表。
标签：EVTX分析, Go, Ruby工具, TOML, 序列化, 开发库, 日志审计, 请求拦截, 配置解析