confd 中的 HCL：一套人机兼顾的配置语言，从语法到源码解析

• 后端
• 配置中心
• 运维

HCL（HashiCorp Configuration Language）是 HashiCorp 设计的面向 DevOps 场景的结构化配置语言，它同时兼容 JSON，既能被人类直接书写修改，也能被机器以 JSON 形式生成。本文以 confd 仓库 vendor 目录中保留的 HCL 说明文档（vendor/github.com/hashicorp/hcl/README.md）为核心，完整覆盖其设计动机、语法规范与 JSON 兼容性，并结合 vendored 源码（parse.go、decoder.go）与 confd 中真实的调用示例，讲清 HCL 是如何被解析成 AST、再解码进 Go 结构体的。

一、HCL 的定位：为什么不是 JSON、YAML 或 Ruby

原文档"为什么"一节给出了 HCL 诞生的背景。在 HCL 出现之前，HashiCorp 的工具使用过多种配置语言——从 Ruby 这类完整编程语言，到 JSON 这类纯数据结构语言。实践中发现：一部分用户想要对人类友好的配置语言，另一部分用户想要对机器友好的语言，两者难以统一。

各候选方案的问题被归纳为：

• JSON：在两者之间取得了不错的平衡，但相对冗长，最关键的问题是不支持注释；
• YAML：初学者很难判断实际结构，经常要靠猜该用连字符、冒号还是缩进来表达某个配置键；
• Ruby 等完整编程语言：允许配置语言本不该开放的复杂行为，还强迫使用者先学一套语言知识。

因此 HCL 的设计目标是：语言本身由人书写和修改，API 层面则接受 JSON 作为输入，这样机器可以生成 JSON 而不是去生成 HCL。HCL 并不试图排斥其他配置语言，而是作为专用语言存在，以 JSON 作为互操作层——这一点在源码中得到直接印证，包注释明确写道 "hcl input can come in either pure HCL format or JSON format"（见 hcl.go）。

原文档同时说明 HCL 的灵感来源：深受 libucl、nginx 配置等相似项目的启发。文档"致谢"部分还记录了两位关键贡献者：libucl 原作者 vstakhov（HCL 最初基于其 parser 与语法），以及用纯 Go 重写 HCL 解析器（不再依赖 goyacc）并支持 printer 的 fatih。

二、语法规范：注释、字面量、数组与块对象

原文档对语法的完整描述如下，本节逐条继承并补充取值细节。完整的语法形式原文档建议直接参考解析器本身（即 vendor/github.com/hashicorp/hcl/hcl/parser 目录下的 parser 实现），这里给出高层概览。

2.1 注释

• 单行注释以#或//开头；
• 多行注释（块注释）包裹在/*与*/之间，不允许嵌套块注释，遇到第一个*/即终止。

2.2 赋值与基本类型

值通过key = value语法赋值（空格不影响解析），value 可以是任意原始类型：字符串、数字、布尔值、对象或列表。

• 字符串：双引号包裹，可以包含任意 UTF-8 字符，如"Hello, World"；
• 多行字符串（heredoc）：行尾以<<EOF开始，以独立成行的EOF结束，EOF可替换为任意标识符（机制即 here document）。示例：

<<FOO hello world FOO

在 token 层面，heredoc 有独立的词法类型HEREDOC，见 token.go 中HEREDOC // <<FOO\nbar\nFOO的定义；

• 数字：默认为十进制；前缀0x表示十六进制，前缀0表示八进制；支持科学计数法，如1e10；
• 布尔值：true、false。

2.3 数组与对象

• 数组：用[]包裹，如["foo", "bar", 42]，数组内可放原始值、其他数组或对象。
• 重复块表示对象列表：等价地，可以用同名块重复出现来表达"对象的列表"：

service { key = "value" } service { key = "value" }

• 对象与嵌套对象：使用key "label" { ... }的结构。原文档给出的例子：

variable "ami" { description = "the AMI to use" }

与以下 JSON 完全等价：

{ "variable": { "ami": { "description": "the AMI to use" } } }

这个"块 → 嵌套 JSON 对象"的映射关系，正是后文 JSON 兼容性的基础。

三、JSON 兼容不是口号：格式自动识别的源码实现

原文档强调 "HCL is also fully JSON compatible"，即 JSON 可以作为期望 HCL 输入的系统完全合法输入。在 vendored 源码中，这一承诺由 parse.go 与 lex.go 共同实现。

parse.go暴露了三个入口：ParseString、ParseBytes和Parse，三者最终汇聚到同一个parse函数，并按词法模式分派给两套解析器：

func parse(in []byte) (*ast.File, error) { switch lexMode(in) { case lexModeHcl: return hclParser.Parse(in) case lexModeJson: return jsonParser.Parse(in) } return nil, fmt.Errorf("unknown config format") }

（见 parse.go）

lexMode的判定逻辑极其简洁：跳过开头的空白字符后，看第一个非空白字符是否为{——是则走 JSON 解析器，否则走 HCL 解析器（见 lex.go）。这个"以{开头即为 JSON"的启发式规则，意味着纯 HCL 块语法与 JSON 输入在入口层就被无歧义地区分开，两套解析器最终都产出统一的ast.File树，后续的解码逻辑无需关心输入形态。

目录结构上也体现出了双解析器的设计：hcl/子目录（ast、parser、scanner、strconv、token）负责 HCL 方言，json/子目录（parser、scanner、token）负责 JSON 方言，JSON 解析器直接复用 HCL 的ast包（见 json/parser/parser.go 的 import 列表），保证两种输入落到同一棵语法树上。

四、从 AST 到 Go 结构体：解码器与hcl结构标签

包注释（hcl.go）说明了两条使用路径：

1. Parse into AST：先Parse得到原始语法树，好处是可以编写自定义 visitor 实现自定义语义检查——默认 HCL 不做任何语义检查；
2. Decode directly：通过Unmarshal/Decode直接从字符串解码进结构体。

decoder.go定义了结构体字段映射所使用的标签名为hcl（decoder.go：const tagName = "hcl"）。解码入口有两个：

• Unmarshal(bs []byte, v interface{})：先parse成 AST，再调用DecodeObject；
• Decode(out interface{}, in string)：等价于Parse+DecodeObject（见 decoder.go）。

结构体字段的支持能力集中在decodeStruct中，从源码可以确认：

• 字段名映射：优先取hcl标签的第一段作为配置键名，未写标签则用字段名本身；
• squash：内嵌结构体可打hcl:",squash"标签，把内嵌结构的字段"压平"到当前层级参与匹配（decoder.go）；
• key：字段可声明hcl:",key"，解码时直接填入该对象的键名（decoder.go）；
• decodedFields/unusedKeyPositions：可分别记录实际解码成功的字段列表与 AST 中出现但未被结构体消费的键及位置信息，便于做配置校验；
• -：标签为-的字段直接跳过。

五、confd 仓库中的真实使用样例：Vault API 的 SSH Helper 配置

confd 本身是一个"用模板 + 后端数据管理本地应用配置文件"的工具，它自身的运行配置使用的是TOML（config.go 中toml.Decode解析/etc/confd/confd.toml），HCL 并非 confd 主流程的直接依赖——在 go.mod 中它被列为github.com/hashicorp/hcl v1.0.1-vault-5 // indirect，即经由 HashiCorp 系客户端库间接引入。

仓库内可以直接观察到的真实调用方是 vendored 的 Vault API 客户端。它用 HCL 解析vault-ssh-helper的配置文件，是一个从"语法 → Parse → 键校验 → DecodeObject"的完整示范：

1. 目标结构体用hcl标签声明每个字段的配置键（ssh_agent.go）：

type SSHHelperConfig struct { VaultAddr string `hcl:"vault_addr"` SSHMountPoint string `hcl:"ssh_mount_point"` Namespace string `hcl:"namespace"` CACert string `hcl:"ca_cert"` ... TLSSkipVerify bool `hcl:"tls_skip_verify"` TLSServerName string `hcl:"tls_server_name"` }

2. ParseSSHHelperConfig先hcl.Parse得到根对象，再把根节点断言为*ast.ObjectList，随后用白名单CheckHCLKeys校验只允许上述九个键出现，最后hcl.DecodeObject(&c, list)完成映射（ssh_agent.go）。

这个样例同时展示了 HCL 解码的一个实际工程约束：默认不做语义检查，未知键要靠调用方显式校验——与包注释中"HCL does not perform any semantic checks"的说法一致。

六、小结：适用边界与阅读路径

结合原文档与 vendored 源码，可以确认 HCL v1 这套实现的定位与边界：

• 它是为"人类手写 + 机器交换"双需求设计的配置语言：HCL 方言负责可读性（注释、heredoc、块语法），JSON 兼容层负责互操作性，入口由 lex.go 的{检测自动分派；
• 解析与解码分层清晰：scanner/parser 产出ast.File，decoder.go负责按hcl标签映射到 Go 结构体、map、slice 等目标类型；
• 在 confd 仓库中，HCL 是 Vault 客户端链路上的间接依赖；confd 自己的配置入口是 TOML（见 config.go 的initConfig），阅读 confd 配置体系时应区分这两条路径。

如需继续深入，可按以下路径阅读仓库内文件：语法总览见 README.md；入口与格式分派见 parse.go；词法类型定义见 token.go；AST 节点定义见 ast.go；结构体解码细节见 decoder.go；真实调用方见 ssh_agent.go。

• 后端
• 配置中心
• 运维