API 教學

本教學將示範如何使用 Caddy 的管理 API，這讓以程式化的方式自動化成為可能。

目標

🔲 執行守護進程
🔲 給予 Caddy 配置
🔲 測試配置
🔲 替換活動配置
🔲 遍歷配置
🔲 使用 @id 標籤

先決條件

基本終端機/命令列技能
基本 JSON 經驗
PATH 中有 caddy 和 curl

若要啟動 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 標籤