Caddyfile 支持

Caddy 模块在 原生 JSON 配置 中通过其命名空间自动添加，当它们 注册 时，使其既可用又可文档化。这使得 Caddyfile 支持纯粹是可选的，但它经常被喜欢 Caddyfile 的用户所要求。

反序列化器

要为您的模块添加 Caddyfile 支持，只需实现 caddyfile.Unmarshaler 接口。您可以通过解析标记的方式来选择模块的 Caddyfile 语法。

反序列化器的作用仅仅是设置模块的类型，例如，通过使用传递给它的 caddyfile.Dispenser 来填充其字段。例如，一个名为 Gizmo 的模块类型可能具有以下方法

// UnmarshalCaddyfile implements caddyfile.Unmarshaler. Syntax:
//
//     gizmo <name> [<option>]
//
func (g *Gizmo) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
	d.Next() // consume directive name

	if !d.Args(&g.Name) {
		// not enough args
		return d.ArgErr()
	}
	if d.NextArg() {
		// optional arg
		g.Option = d.Val()
	}
	if d.NextArg() {
		// too many args
		return d.ArgErr()
	}

	return nil
}

在方法的 godoc 注释中记录语法是一个好主意。有关解析 Caddyfile 的更多信息，请参阅 caddyfile 包的 godoc。

可以使用简单的 d.Next() 调用来使用/跳过指令名称标记。

确保使用 d.NextArg() 或 d.RemainingArgs() 检查缺少和/或多余的参数。使用 d.ArgErr() 来显示简单的“无效情况”消息，或使用 d.Errf("some message") 来创建包含问题解释（理想情况下，还包含建议的解决方案）的有用错误消息。

您还应该添加一个 接口保护 来确保正确地满足接口

var _ caddyfile.Unmarshaler = (*Gizmo)(nil)

块

要接受比单行可以容纳的更多配置，您可能希望允许使用包含子指令的块。这可以使用 d.NextBlock() 完成，并迭代直到返回到原始嵌套级别

for nesting := d.Nesting(); d.NextBlock(nesting); {
	switch d.Val() {
		case "sub_directive_1":
			// ...
		case "sub_directive_2":
			// ...
	}
}

只要循环的每次迭代都使用整个段（行或块），那么这是一种处理块的优雅方式。

HTTP 指令

HTTP Caddyfile 是 Caddy 的默认 Caddyfile 适配器语法（或“服务器类型”）。它是可扩展的，这意味着您可以 注册 自己的模块的“顶级”指令

func init() {
	httpcaddyfile.RegisterDirective("gizmo", parseCaddyfile)
}

如果您的指令只返回单个 HTTP 处理程序（很常见），您可能会发现 RegisterHandlerDirective 更容易

func init() {
	httpcaddyfile.RegisterHandlerDirective("gizmo", parseCaddyfileHandler)
}

基本思想是，您与指令关联的 解析函数 返回一个或多个 ConfigValue 值。（或者，如果使用 RegisterHandlerDirective，它直接返回填充的 caddyhttp.MiddlewareHandler 值。）每个配置值都与一个 “类” 相关联，这有助于 HTTP Caddyfile 适配器了解它可以在最终 JSON 配置的哪些部分使用。所有配置值都被转储到一个堆中，适配器在构建最终 JSON 配置时从中提取。

这种设计允许您的指令为任何识别的类返回任何配置值，这意味着它可以影响 HTTP Caddyfile 适配器为其指定了类的任何配置部分。

如果您已经实现了 UnmarshalCaddyfile() 方法，那么您的解析函数可以像这样简单：

// parseCaddyfileHandler unmarshals tokens from h into a new middleware handler value.
func parseCaddyfileHandler(h httpcaddyfile.Helper) (caddyhttp.MiddlewareHandler, error) {
	var g Gizmo
	err := g.UnmarshalCaddyfile(h.Dispenser)
	return g, err
}

有关如何使用 httpcaddyfile.Helper 类型的更多信息，请参阅 httpcaddyfile 包的 godoc。

处理程序顺序

所有返回 HTTP 中间件/处理程序值的指令都需要以正确的顺序进行评估。例如，设置站点根目录的处理程序必须在访问根目录的处理程序之前，以便它知道目录路径是什么。

HTTP Caddyfile 对标准指令有一个硬编码的排序。这确保用户不需要了解其 Web 服务器最常见功能的实现细节，并使他们更容易编写正确的配置。鉴于 Caddyfile 的可扩展性，单个硬编码列表还可以防止非确定性。

当您注册新的处理程序指令时，必须在可以使用它（在 route 块之外）之前将其添加到该列表中。 这是在配置中使用两种方法之一完成的

• order 全局选项 仅修改该配置的标准顺序。例如：order mydir before respond 将插入一个新的指令 mydir，以便在 respond 处理程序之前进行评估。然后，该指令可以正常使用。
• 或者，在 route 块 中使用该指令。因为 route 块中的指令不会重新排序，所以 route 块中使用的指令不需要出现在列表中。

请为您的用户记录您的指令在列表中的正确位置，以便他们能够正确使用它。

类

此表描述了 HTTP Caddyfile 适配器识别的每个具有导出类型的类

服务器类型

从结构上讲，Caddyfile 是一种简单的格式，因此可以有不同类型的 Caddyfile 格式（有时称为“服务器类型”）来满足不同的需求。

默认的 Caddyfile 格式是 HTTP Caddyfile，您可能已经熟悉它。这种格式主要配置 http 应用程序，同时可能只在 Caddy 配置结构的其他部分（例如 tls 应用程序以加载和自动执行证书）中添加一些配置。

要配置除 HTTP 之外的应用程序，您可能希望实现自己的配置适配器，该适配器使用 自己的服务器类型。Caddyfile 适配器实际上会为您解析输入，并为您提供服务器块和选项的列表，由您的适配器来理解该结构并将其转换为 JSON 配置。