yaml/go-yaml
GitHub: yaml/go-yaml
Go 语言中极受欢迎的 go-yaml 库由 YAML 官方组织接手维护的分支版本，提供可靠的 YAML 序列化与反序列化能力。
Stars: 493 | Forks: 57
# go.yaml.in/yaml
## 简介
`yaml` 包使得 [Go](https://go.dev/) 程序能够轻松地编码
和解码 [YAML](https://yaml.org/) 值。
它最初由 [Canonical](https://www.canonical.com) 开发，作为
[juju](https://juju.ubuntu.com) 项目的一部分，并且基于著名的
[libyaml](http://pyyaml.org/wiki/LibYAML) C 库的纯 Go 移植版，以
快速且可靠地解析和生成 YAML 数据。
## 项目状态
本项目最初是极受欢迎的 [go-yaml](
https://github.com/go-yaml/yaml/)
项目的分支（fork），目前由官方的 [YAML 组织](
https://github.com/yaml/) 维护。
在 2025 年 4 月，go-yaml 的作者 @niemeyer 决定
[将项目仓库标记为“无人维护”](
https://github.com/go-yaml/yaml/blob/944c86a7d2/README.md) 后，经过与他讨论，
YAML 团队接管了本项目的持续维护和开发工作。
我们组建了一支专注的维护团队，其中包括
go-yaml 最重要的下游项目的代表。
我们将努力赢得各个 go-yaml 分支的信任，使其重新切换回
此仓库作为其上游。
如果您想做出贡献或参与其中，请
[联系我们](https://cloud-native.slack.com/archives/C08PPAT8PS7)。
### 版本规划
版本 `v1`、`v2` 和 `v3` 将保持为**冻结的历史版本**。
它们将**仅接收安全修复**，以便现有用户能够
在不受破坏性变更影响的情况下继续正常工作。
所有正在进行的工作，包括新功能和常规错误修复，都将在
**`v4`** 中进行。
如果您正在启动一个新项目或升级现有项目，请使用
`go.yaml.in/yaml/v4` 导入路径。
## 兼容性
`yaml` 包支持 YAML 1.2 的大部分功能，但为了向后兼容，
保留了部分 1.1 的行为。
具体而言，`yaml` 包的 v3 版本：
* 只要被解码为类型化的 bool 值，就支持 YAML 1.1 的布尔值（`yes`/`no`、`on`/`off`）。
否则，它们将被视为字符串。
YAML 1.2 中的布尔值仅限 `true`/`false`。
* 支持按照 YAML 1.1 标准以 `0777` 格式编码和解码八进制数，
而不是 YAML 1.2 中规定的 `0o777`，因为大多数解析器仍在使用旧格式。
不过，同时也支持 `0o777` 格式的八进制数，因此新文件也能正常工作。
* 不支持 base-60 浮点数。
这在 YAML 1.2 中已被取消，而且实际上本包
从未支持过，因为这显然是一个糟糕的设计。
## 安装与使用
该包的导入路径为 *go.yaml.in/yaml/v4*。
要安装它，请运行：
```
go get go.yaml.in/yaml/v4
```
## API 文档
参见：
## API 稳定性
yaml v3 的包 API 将保持稳定，如 [gopkg.in](
https://gopkg.in) 中所述。
## 示例
```
package main
import (
"fmt"
"log"
"go.yaml.in/yaml/v4"
)
var data = `
a: Easy!
b:
c: 2
d: [3, 4]
`
// Note: struct fields must be public in order for unmarshal to
// correctly populate the data.
type T struct {
A string
B struct {
RenamedC int `yaml:"c"`
D []int `yaml:",flow"`
}
}
func main() {
t := T{}
err := yaml.Unmarshal([]byte(data), &t)
if err != nil {
log.Fatalf("error: %v", err)
}
fmt.Printf("--- t:\n%v\n\n", t)
d, err := yaml.Marshal(&t)
if err != nil {
log.Fatalf("error: %v", err)
}
fmt.Printf("--- t dump:\n%s\n\n", string(d))
m := make(map[any]any)
err = yaml.Unmarshal([]byte(data), &m)
if err != nil {
log.Fatalf("error: %v", err)
}
fmt.Printf("--- m:\n%v\n\n", m)
d, err = yaml.Marshal(&m)
if err != nil {
log.Fatalf("error: %v", err)
}
fmt.Printf("--- m dump:\n%s\n\n", string(d))
}
```
此示例将生成以下输出：
```
--- t:
{Easy! {2 [3 4]}}
--- t dump:
a: Easy!
b:
c: 2
d: [3, 4]
--- m:
map[a:Easy! b:map[c:2 d:[3 4]]]
--- m dump:
a: Easy!
b:
c: 2
d:
- 3
- 4
```
## 使用 `make` 进行开发和测试
一些 `make` 命令如下：
* `make test`
* `make lint tidy`
* `make test-shell`
* `make test v=1`
* `make test o='-foo --bar=baz'` # 添加额外的 CLI 选项
* `make test GO-VERSION=1.2.34`
* `make test GO_YAML_PATH=/usr/local/go/bin`
* `make shell` # 启动带有本地 `go` 环境的 shell
* `make shell GO-VERSION=1.2.34`
* `make distclean` # 删除所有生成的文件，包括 `.cache/`
### 依赖自动安装
默认情况下，此 makefile 不会使用您系统的 Go 安装或
其需要的任何其他系统工具。
它所依赖的系统组件仅有：
* Linux 或 macOS
* GNU `make` (3.81+)
* `git`
* `bash`
* `curl`
其他所有内容，包括 Go 和 Go 工具，都会在 makefile
需要时被安装并缓存（在 `.cache/` 目录下）。
### 使用您自己的 Go
如果您想使用自己的 Go 安装和工具，请将 `GO_YAML_PATH` 导出为
包含 `go` 二进制文件的目录。
请使用类似以下的命令：
```
export GO_YAML_PATH=$(dirname "$(command -v go)")
make
# 或:
make GO_YAML_PATH=$(dirname "$(command -v go)")
```
## `go-yaml` CLI 工具
本仓库包含一个 `go-yaml` CLI 工具，可用于了解
使用 go-yaml 库进行 YAML 处理的内部阶段和最终结果。
我们强烈建议您在报告和讨论问题时，
提供该命令的相关输出。
```
make go-yaml
./go-yaml --help
./go-yaml <<< '
foo: &a1 bar
*a1: baz
' -n # Show value on decoded Node structs (formatted in YAML)
```
您也可以使用以下命令安装它：
```
go install go.yaml.in/yaml/v4/cmd/go-yaml@latest
```
## 许可证
yaml 包采用 MIT 和 Apache License 2.0 双重许可。
详情请参阅 LICENSE 文件。
标签：EVTX分析, Go, Ruby工具, SOC Prime, YAML, 反序列化, 安全库, 序列化, 开发工具, 日志审计, 解析库