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!」變更為更激勵人心的話：「我可以做困難的事。」在您的設定檔中進行此變更，讓處理常式物件現在看起來像這樣

{
	"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 標籤