參考實施

1）目標，邊界和原則

1.給出明確的協議/speka解釋。

2.提供獨立的兼容性驗證。

3.提供客戶端/服務器/webhook的工作示例。

4.降低集成和實現成本。

• RI專註於行為正確性而不是最大性能。
• 包括最小的prod設置集（TLS、拼寫、度量、跟蹤、限制）。
• 不取代商業/產品實現，但設置「質量底板」。

• 規格第一：真相-規範（OpenAPI/AsyncAPI/Proto/JSON-Schema/IDL）。
• Deterministic&Testable：可復制的答案和虛構。
• Docs-as-Code：VCS中的所有內容，一個帶有代碼和構象測試的版本。
• Portability：容器，Helm/compose，現成的清單。

2）參考實施類型

RI-Server：規範服務器基準（REST/gRPC/GraphQL/Streaming）。
RI-Client/SDK：客戶端基準（一兩個流行的平臺）+示例。
RI-Webhook接收器：簽名的webhook處理程序（簽名驗證，轉發）。
RI-Adapters：消息代理/事件總線的適配器（Avro/Proto/JSON, Schema Registry）。
RI-Data：參考數據集、隱私概況、「黃金」狙擊手。

3） RI存儲庫體系結構

ri/
specs/        # OpenAPI/AsyncAPI/Proto/JSON-Schema server/       # эталонный сервер src/
config/
docker/
helm/
client/       # эталонный клиент/SDK + примеры js/ python/ go/
conformance/     # конформанс-раннер, тест-кейсы, золотые файлы cases/
fixtures/
golden/
samples/       # end-to-end сценарии, Postman/k6/Locust security/      # ключи тестовые, политики, пример подписи docs/        # руководство, ADR, runbook, FAQ ci/         # пайплайны, конфиги, матрица совместимости tools/        # генераторы, линтеры, проверяльщики схем

• 每個版本都有標簽'vX。Y.Z'和文物（圖像，圖表，SDK）。
• 對於每個螺紋，均為總和和簽名（供應鏈）。
• 標有「斷開」更改的CHANGELOG。

4）特價，合同和計劃

運輸：OpenAPI/REST，gRPC/Proto，SDL GraphQL，AsyncAPI。
語義：錯誤代碼,等效性,遊標/分頁,轉發,重復數據消除。
事件：類型/版本，「id」，「occurred_at_utc」，「partition_key」，順序不變量。
簽名/安全性：OIDC/JWT汙名，webhook簽名（HMAC/EdDSA），鍵輪換。

5）Conformance測試

• 符合燒結（驗證方案），
• 行為不變性（等效性，排序，遊標，TTL，回歸策略），
• 安全性（簽名、時間表、非簽名/復制保護），
• 時間方面（UTC，RFC3339，DST），
• 負面案例和邊界條件。

黃金文件（golden）：比較結果的穩定參考響應/事件。

python def run_conformance(target_url, cases, golden_dir):
for case in cases:
req = build_request(case.input)
res = http_call(target_url, req)
assert match_status(res.status, case.expect.status)
assert match_headers(res.headers, case.expect.headers)
assert match_body(res.json, golden_dir / case.id, allow_extra_fields=True)
for invariant in case.invariants:
assert invariant.holds(res, case.context)

consumer/sdk-js 1.4server 1.6, 1.7server 2.0 consumer/sdk-go 0.9server 1.5–1.7   –
webhook-receiver 1.1events v1events v2 (deprecated fields removed)

6）生產最低限度（無過量）

安全：默認的TLS，安全標題，CORS限制，限制，反重播。
觀察力：logi（結構+PD掩蓋），度量（p50/p95/p99，error rate），tracing（相關性「request_id」）。
Config：所有通過環境變量和文件,配置方案驗證。
Perf基線：穩健的池設置,連鎖定時預算,高速緩存。
穩定性：帶夾具,電路斷路器,背壓。

7） CI/CD和文物

1.Lint/組裝/unit測試。

2.Spec驗證（OpenAPI/AsyncAPI/Proto-lint）。

3.從spec生成SDK/stabs。

4.Conformans-run：「ri-server」與「cases」和「gold」。

5.映像組裝（SBOM，簽名），發布到註冊表。

6.E2E腳本（docker-compose/kind/Helm）。

7.發布塢站和示例。

• 容器圖像「ri-server」，「ri-webhook」，
• SDK包（npm/pypi/go），
• Helm圖表/復合文件，
• 帶有「金色文件」和conformance runner的zip。

8）樣本，SDK和「如何」

兩個流行堆棧上的迷你應用程序（例如，Node。js/Go）的步驟包括：身份驗證→ API調用→錯誤處理→ retrai → webhook。
如何進行：等效開機自檢、遊標分頁、網絡手冊簽名、429/503處理。
k6/JMeter 「smoke-perf」的配置文件（不是負載，而是基本健康）。

9）轉化與進化

SemVer：MAJOR →突破性變化；→ MINOR無切片添加；PATCH →修補程序。
分裂計劃：散文廣告，幻燈片，「影子」配對模式時期，然後是執法。
事件兼容性：用戶必須忽略不熟悉的字段。

10） RI的安全和隱私

測試密鑰和秘密-僅用於展位；在碼頭中-替換指令。
在日誌中掩蓋PD；fixtur匿名配置文件（PII →合成）。
演示環境工件壽命策略（TTL，自動清潔）。

11）RI的可觀察性和SLO

SLI/SLO RI：參考臺上的p95 <250 ms，錯誤率<0。5％，在依賴性故障下正確降解（在樣本中）。
Dashbords：latency/Throughput/Errors+構象結果。
用於簽名webhook/令牌檢查的決策邏輯（可跟蹤的故障原因）。

12）性能： 「足夠」基線

「Wrk/hey/k6」配置文件位於「熱」和「冷」軌道上。
明確位置：RI不參加最大RPS比賽，但必須經受住類型目標（例如，每t3 500 RPS。中位數為p95 <200 ms）是集成商的地標。

13）操作手冊（runbook）

本地啟動：compose/'make up'。
K8s deploy：Helm的含義，秘密，ingress，HPA。
Webhook簽名密鑰輪換（雙鍵周期）。
Trablshuting：常見錯誤及其原因（401,403,429,503）,如何閱讀標記/預告片。

14）管理與所有權

業主：雜貨店老板+平臺（電器）+安全。
發布日歷和中斷更改匹配窗口。
RFC/ADR對協議進行了有意義的更改。

15）適應語言/平臺

建議的最低限度：一個高級（JS/TS）和一個系統（Go/Java）。
類型映射：日期/現金格式/decimal/字節集如何呈現。
每個SDK中的Retrait/Taymauts/池設置指南。

16）反模式

RI=「沒有測試的沙箱」：沒有順式，沒有用。
Speka與代碼和測試「分開生活」→差異。
缺乏「黃金文件」和不變量→長笛和行為爭議。
框架依賴性：硬綁定到單個庫/雲,無需容器化。
沒有偽裝PD的邏輯,存儲庫中的密鑰。
Perf混音代替行為：嘗試衡量「誰更快」而不是「誰正確」。
一個沒有模塊化和人工制品的巨型二進制/圖像（SDK/圖表/精靈）。

17）建築師支票清單

1.Speka是規範和可驗證的嗎？(OpenAPI/Proto/AsyncAPI/JSON-Schema)

2.是否有RI-server和至少一個RI-client/SDK和完整的示例?

3.保形符、案例、「黃金文件」、底片和不變量準備就緒?

4.CI/CD收集映像，SDK，站點，啟動匹配和e2e？

5.默認安全性： TLS、簽名、限制、PD掩碼?

6.可觀察性：RI的邏輯/度量/跟蹤、行車記錄儀和SLO？
7.Perf基線是否已記錄並播放？
8.SemVer轉化，兼容性矩陣，deprecation過程？
9.Runbook和本地/群集啟動-單擊？

10.是否定義了所有者、發布日歷、RFC/ADR流?

18）迷你示例： 參照webhook（偽代碼）

python def verify_webhook(request, keys):
sig = request.headers["X-Signature"]
ts = int(request.headers["X-Timestamp"])
if abs(now_utc().epoch - ts) > 300: return 401 # replay window body = request.raw_body if not any(hmac_ok(body, ts, k, sig) for k in keys.active_and_previous()):
return 401 event = json.loads(body)
if seen(event["id"]): return 200 # idempotency handle(event)
mark_seen(event["id"])
return 200

測試案例檢查：時間窗口，簽名正確性（當前和以前的密鑰），事件平均值。id'，底片（損壞的簽名，過期的'ts'）。

二.結論

參考執行是系統行為的規範：通過代碼，測試和人工制品確認單個子宮。良好的RI可加速集成,消除協議歧義,確保可驗證的互操作性,並設置最低的安全性、可觀察性和性能標準。使它成為您的工程「骨架」的一部分-您的產品，合作夥伴和生態系統將更快，更可靠地移動。