組件用法

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

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

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

• 核心：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）見以模組使用。

注意：gortexa create 產出的專案已內含框架原始碼，那種專案不要再 go get 框架；本節是給「不走 scaffold、直接把框架當 library」的用法。

完整接線

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

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