元件用法

框架的每個 package 都可以在 go get 之後單獨引用。先取得模組：

go get github.com/yshengliao/gortexa@v0.28.3

本節按類別列出公開元件，每個都附用途、import 路徑與一段最小用法；這些片段全部對 v0.28.3 編譯驗證過。

核心：kernel、config、interceptor、auth、apperr —— 組裝、設定、攔截器鏈、JWT 與錯誤模型。
HTTP 與 MCP：httpcompat、mcp —— grpc-gateway HTTP/JSON 層與 MCP bridge。
內建元件：mq、cache、storage、client —— 訊息、快取、資料庫池與對外 client。
可觀測性與健康：health、observability —— 三態健康與 OTLP 日誌／追蹤／指標。

只要一個最小 app（不掛 gateway／MCP）見以模組使用。

注意：本節是給「不走 scaffold、直接把框架當 library」的用法。gortexa create 產出的專案已內含一份框架原始碼；自 v0.28.0 起那種專案也能再 go get 框架而不會撞 descriptor，但等於連進兩份框架程式碼，取捨見手動快速開始末段的說明。

完整接線

框架 repo 的 cmd/server/main.go 是所有元件組成一個服務的正規範例，順序為：

config.MustBuild(...) — fail-loud 載入設定。
observability.SetupLogs／SetupTracing／SetupMetrics — 各得一個 ShutdownFunc；observability.NewGovernanceMetrics()。
auth.NewVerifier(...)。
interceptor.NewSet(interceptor.Config{...})。
kernel.New(WithConfig, WithLogger, WithInterceptors, WithStatsHandler(observability.ServerStatsHandler()), WithHTTPWrap(...), WithShutdownHook×3)。
把 service 註冊到 app.GRPCServer()；app.Health().Register(...)。
conn, err := app.Loopback() → httpcompat.NewServeMux → app.SetGateway(...)。
mcp.ServiceDescriptors(...) → mcp.NewBridge(conn, descs, apperr.Default, cfg.Observ) → app.SetMCPHandler(bridge.Handler())。
app.Run(ctx)。

app.Loopback() 必須在 kernel.New 之後、Run 之前呼叫；gateway 與 MCP bridge 都經它 dial，因而共用同一條攔截器鏈。

testutil — 測試輔助（test-only）

in-process 測試輔助：bufconn gRPC server（掛完整攔截器鏈）、golden 檔比對、goroutine leak 斷言。

import "github.com/yshengliao/gortexa/testutil"

conn := testutil.NewTestServer(t, func(s *grpc.Server) {
  pb.RegisterThingServiceServer(s, myService)
}, testutil.WithAuthSecret(secret))
// testutil.Golden(t, name, got) 比對 testdata/<name>.golden
// 設 GORTEXA_UPDATE_GOLDEN 才改寫 golden 檔（無 -update flag）