API 教程

本教程将向您展示如何使用 Caddy 的管理 API，它使以编程方式进行自动化成为可能。

目标：

🔲 运行守护进程
🔲 为 Caddy 提供配置
🔲 测试配置
🔲 替换活动配置
🔲 遍历配置
🔲 使用 @id 标签

先决条件：

基本的终端/命令行技能
基本的 JSON 经验
caddy 和 curl 在您的 PATH 中

要启动 Caddy 守护进程，使用 run 子命令：

caddy run

此命令会永久阻塞，但它在做什么？目前...什么都没做。默认情况下，Caddy 的配置（"config"）是空白的。我们可以使用另一个终端中的管理 API来验证这一点：

curl localhost:2019/config/

我们可以通过给它一个配置来使 Caddy 变得有用。实现这一点的一种方法是向 /load 端点发出 POST 请求。就像任何 HTTP 请求一样，有很多方法可以做到这一点，但在本教程中我们将使用 curl。

您的第一个配置

要准备我们的请求，我们需要制作一个配置。Caddy 的配置只是一个 JSON 文档（或任何可以转换为 JSON 的内容）。

将以下内容保存到一个 JSON 文件中：

{
	"apps": {
		"http": {
			"servers": {
				"example": {
					"listen": [":2015"],
					"routes": [
						{
							"handle": [{
								"handler": "static_response",
								"body": "Hello, world!"
							}]
						}
					]
				}
			}
		}
	}
}

然后上传它：

curl localhost:2019/load \
	-H "Content-Type: application/json" \
	-d @caddy.json

我们可以通过另一个 GET 请求来验证 Caddy 是否应用了我们的新配置：

curl localhost:2019/config/

在浏览器中访问 localhost:2015 或使用 curl 来测试它是否工作：

curl localhost:2015
Hello, world!

如果您看到 Hello, world!，那么恭喜 -- 它正在工作！确保您的配置按预期工作总是一个好主意，特别是在部署到生产环境之前。

让我们将欢迎信息从 "Hello world!" 改为更有激励性的内容："I can do hard things."。在您的配置文件中进行此更改，使处理器对象现在看起来像这样：

{
	"handler": "static_response",
	"body": "I can do hard things."
}

保存配置文件，然后通过再次运行相同的 POST 请求来更新 Caddy 的活动配置：

curl localhost:2019/load \
	-H "Content-Type: application/json" \
	-d @caddy.json

为了稳妥起见，验证配置是否已更新：

curl localhost:2019/config/

在浏览器中刷新页面（或再次运行 curl）进行测试，您将看到一条鼓舞人心的消息！

配置遍历

让我们使用 Caddy API 的一个强大功能，在不触及配置文件的情况下进行更改，而不是为了一个小改动就上传整个配置文件。

使用请求 URI 的路径，我们可以遍历配置结构并只更新消息字符串（如果被裁剪请向右滚动）：

curl \
	localhost:2019/config/apps/http/servers/example/routes/0/handle/0/body \
	-H "Content-Type: application/json" \
	-d '"Work smarter, not harder."'

您可以使用类似的 GET 请求来验证它是否生效，例如：

curl localhost:2019/config/apps/http/servers/example/routes

您应该看到：

[{"handle":[{"body":"Work smarter, not harder.","handler":"static_response"}]}]

重要提示： 这应该很明显，但一旦您使用 API 进行的更改不在原始配置文件中，您的配置文件就会过时。有几种方法可以处理这种情况：

使用 caddy run 命令的 --resume 选项使用最后一次活动的配置。
不要混合使用配置文件和通过 API 进行的更改；保持一个真实来源。
通过后续的 GET 请求导出 Caddy 的新配置（不如前两个选项推荐）。

在 JSON 中使用 `@id`

配置遍历当然很有用，但您不觉得路径有点长吗？

我们可以给我们的处理器对象一个 @id 标签，使其更容易访问：

curl \
	localhost:2019/config/apps/http/servers/example/routes/0/handle/0/@id \
	-H "Content-Type: application/json" \
	-d '"msg"'

这会向我们的处理器对象添加一个属性："@id": "msg"，现在它看起来像这样：

{
	"@id": "msg",
	"body": "Work smarter, not harder.",
	"handler": "static_response"
}

然后我们可以直接访问它：

curl localhost:2019/id/msg

现在我们可以用更短的路径更改消息：

curl \
	localhost:2019/id/msg/body \
	-H "Content-Type: application/json" \
	-d '"Some shortcuts are good."'

再次检查：

curl localhost:2019/id/msg/body

使用 @id 标签