[ADP-52] API 健康檢查
指導
- API 伺服器應該(SHOULD)提供健康檢查端點，如 RFC 草案 所建議。
- API 健康檢查端點應該(SHOULD)定義為
/health。 - 健康檢查 API 的回應應該(SHOULD)使用
application/health+json格式。 - 健康檢查端點不應該(SHOULD NOT)要求認證。
- 健康檢查回應應該(SHOULD)至少包括:
status: 整體健康狀態 (PASS，FAIL，WARN)version: API 版本releaseId: 發布或構建標識符
- 可以(MAY)根據 API 的具體需求包括額外的檢查:
- 數據庫連接性
- 外部服務依賴
- 緩存可用性
- 存儲系統健康狀況
- 健康檢查端點應該(SHOULD)快速回應，通常在 100-500ms 內。
- 不得(MUST NOT)通過健康檢查端點暴露敏感資訊。
示例
基本的健康檢查回應:
json
{
"status": "PASS",
"version": "1.0.0",
"releaseId": "1.0.0-build.1",
"notes": ["數據庫連接穩定", "緩存回應正常"],
"output": "所有系統運行正常",
"checks": {
"database:responseTime": [
{
"componentType": "datastore",
"status": "PASS",
"time": "2023-05-22T15:46:09Z",
"observedValue": 23,
"observedUnit": "ms"
}
],
"externalApi:status": [
{
"componentType": "system",
"status": "PASS",
"time": "2023-05-22T15:46:09Z"
}
]
}
}OpenAPI 3.1 示例
以下是健康檢查端點的 OpenAPI 3.1 規範示例:
yaml
openapi: 3.1.0
info:
title: API 健康檢查
version: 1.0.0
paths:
/health:
get:
summary: 獲取 API 健康狀態
responses:
'200':
description: 成功的健康檢查回應
content:
application/health+json:
schema:
type: object
required:
- status
- version
- releaseId
properties:
status:
type: string
enum: [PASS, FAIL, WARN]
version:
type: string
releaseId:
type: string
notes:
type: array
items:
type: string
output:
type: string
checks:
type: object
additionalProperties:
type: array
items:
type: object
required:
- componentType
- status
- time
properties:
componentType:
type: string
status:
type: string
enum: [PASS, FAIL, WARN]
time:
type: string
format: date-time
observedValue:
type: number
observedUnit:
type: string實施考慮事項
- 緩存: 考慮短時間(例如 5-10 秒)緩存健康檢查結果，以減少後端系統的負載。
- 部分健康: 實現一種方式來報告部分健康狀態，當某些組件降級但 API 仍然可運行時。
- 監控集成: 確保健康檢查端點可以輕鬆集成到監控和警報系統中。
- 速率限制: 對健康檢查端點應用速率限制，以防止潛在的濫用。