API 閘道
HTTP 入口：身分驗證、簽章、存取控制與可觀測性
專案背景
同一個閘道同時服務終端使用者 App、租戶/合作夥伴管理後台，後來還有一組對外的管理 API。每條路由需要不同的身分驗證、租戶解析、存取控制與可觀測性組合，而每個下游服務都需要知道呼叫者是誰，以供稽核。
架構設計
用戶端 → Gin 中介軟體鏈（日誌/復原 → 追蹤 → 指標 → 網域/租戶解析 → token 驗證 → 帳號狀態 → 黑白名單 → IP 策略）→ handler 驗證輸入、檢查權限並扇出呼叫 gRPC 服務 → 依用戶端調整回應格式。驗證中介軟體會將操作者、IP、路徑、租戶與 trace ID 寫入送出的 gRPC 中繼資料。
核心技術亮點
初版中介軟體：注入使用者 context 的 token 驗證、請求簽章驗證、多維度黑白名單、網域對應租戶解析、IP 策略、具 panic 復原的結構化日誌、OpenTelemetry 追蹤與 Prometheus 指標
後續新增：所有需驗證路由的帳號狀態守衛、各平台的網域開關，以及在每次下游 gRPC 呼叫附上操作者/租戶/trace 中繼資料
針對合作夥伴網路的階層式、欄位層級授權：操作者只能操作自己下層的帳號，敏感欄位（風險等級、綁定 IP、密碼）各有獨立權限
管理後台回應中的個資遮罩；跨服務建立帳號時的補償回滾
跨服務的清單篩選條件先解析為 ID 集合，再平行執行
核心實現
可組合的中介軟體鏈
每個橫切關注點都是獨立的 Gin 中介軟體，路由群組只啟用自己需要的策略。
Why: 終端使用者、管理後台與整合路由的安全需求各不相同；將關注點分開，handler 就能保持精簡。
每次下游呼叫都帶上呼叫者身分
通過驗證後，中介軟體會將操作者 ID、用戶端 IP、HTTP 路徑、租戶與 trace ID 作為送出的 gRPC 中繼資料附加上去。
Why: 如此一來，任何下游服務都能記錄可追溯到操作者的稽核事件或追蹤，而不必重新判斷呼叫者身分。
Result: 這成為全平台稽核軌跡的基礎（見稽核日誌服務）。
階層式授權
一套權限檢查：平台管理員可在任何範圍操作，會員一律拒絕，其他操作者只能操作合作夥伴樹中位於自己下層的帳號。主帳號與子帳號、各個敏感欄位另有獨立規則。
Why: 在多層級合作夥伴網路中，「能否編輯使用者」並不夠，真正的問題是：能編輯誰的使用者。
技術決策
| 技術決策 | 選擇 | 替代方案 | 原因 |
|---|---|---|---|
| 框架 | Gin | go-zero REST | Gin 的中介軟體鏈可依路由群組做細緻控制，在邊緣層這比程式碼產生更重要。 |
| 在哪裡解析呼叫者 | 在閘道解析一次，以 gRPC 中繼資料向下傳遞 | 每個服務各自重新驗證 token | 每個請求只驗證一次，日誌、追蹤與稽核事件使用同一個一致的身分。 |