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 对象现在看起来像这样：

{
	"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`

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

我们可以给 handler 对象添加一个 @id 标签，以便更容易访问：

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

这会在我们的 handler 对象中添加一个属性："@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 标签