# 框架比較

Source: https://gortexa.sheng.page/comparison/

Gortexa 是 contract-first 的 gRPC 框架，最關鍵的取捨是**一個 h2c port 同時服務 gRPC、HTTP/JSON 與 MCP**，三者共用同一條攔截器鏈、同一張錯誤對應表與同一條 auth 路徑。以下比較都圍繞這個取捨：它換到什麼，又付出什麼。

## Gortexa vs 純 grpc-go

grpc-go 是傳輸層。它之上的一切——REST 表面、攔截器順序、錯誤對應、health 模型、MCP bridge——都得自己寫，而且要自己維持一致。

| | grpc-go | Gortexa |
| --- | --- | --- |
| gRPC server | 有 | 有（底下就是 grpc-go） |
| HTTP/JSON | 自己接 grpc-gateway | 內建，同一個 port |
| 給 AI agent 的 MCP | 自己寫 | 內建，同一個 port 與同一條鏈 |
| 攔截器順序 | 自行決定，每個服務各自為政 | 固定八段，缺席直接啟動失敗 |
| 錯誤 → HTTP/gRPC/MCP | 每個 transport 手動對應 | 一張 registry，三個 transport |
| Health、config、OTel | 自己組 | 內建 |

想要完全沒有意見的底層，或需要共用埠表達不了的傳輸功能時，直接用 grpc-go——見下方的限制段落。

## Gortexa vs connect-go

最接近的對照，也是最值得細看的一組。Connect 與 Gortexa 都在單一 port 上多工協定，但多工的是**不同**協定。

| | connect-go | Gortexa |
| --- | --- | --- |
| 單埠多工的協定 | Connect、gRPC、gRPC-Web | gRPC、HTTP/JSON（grpc-gateway）、MCP |
| 瀏覽器 client | 一等公民（Connect + gRPC-Web） | 走 HTTP/JSON |
| AI agent client | 不在範圍內 | 由 proto annotations 產生 MCP tools |
| HTTP/1.1 | 支援 | 埠本身是 h2c；JSON 表面走 HTTP/1.1 |
| 治理 | 自己組合 interceptor | 固定鏈，三個 transport 共用 |
| 定位 | 一個 RPC 函式庫 | 含 config、health、MQ、cache、storage 的框架 |

目標是瀏覽器 client 與一個簡單、不帶意見的 RPC 函式庫，選 connect-go。想要 REST 表面直接由 `google.api.http` annotations 產生，而且要 AI agent 走同一條 auth 與 validation 呼叫同一批 RPC，選 Gortexa。

## Gortexa vs 只用 grpc-gateway

這不是競爭關係：Gortexa 的 HTTP/JSON 表面**就是**用 grpc-gateway 做的。自己接 grpc-gateway 通常意味著第二個 listener 與第二道行程邊界，還得自己回答「gRPC status 要怎麼變成 HTTP status」。Gortexa 的差別在於 gateway 透過 in-process loopback 回撥 gRPC server，所以一個 JSON 請求走的是與 gRPC 請求完全相同的八段鏈，落在同一張錯誤表上。

## Gortexa vs Buf

同樣是正交關係。Buf 是 proto 工具鏈——lint、breaking change 偵測、codegen、schema registry——而 Gortexa 是它的使用者：`gortexa regen` 就是 `buf lint → buf breaking → buf generate`。已經在用 Buf 的話，Gortexa 是疊在上面，不是取代它。

## Gortexa vs Kratos、go-zero、go-kit

這些是範圍更廣的 Go 微服務框架：服務發現、設定中心、跨多種 transport 的鷹架，有些還有自己的 DSL。Gortexa 刻意更窄——一個 port、三個協定、protobuf 是唯一事實來源——但在 AI 表面上更深，那是目前這幾個框架都沒處理的。需要開箱即用的服務發現或跨機房控制平面，那些框架給得更多；想要一個小而有主見的核心、讓 LLM 的 tool call 和人的請求受完全相同的治理，Gortexa 更貼合。

## 什麼時候不該用 Gortexa

直說限制，因為決定選擇的往往是限制而不是功能：

- **你需要在對外埠上用到 grpc-go 完整的傳輸語意。** 共用 h2c 埠上的對外 gRPC 跑的是 grpc-go 的 `ServeHTTP` handler 模式，所以傳輸層選項——`KeepaliveParams`、`KeepaliveEnforcementPolicy`、`MaxStreams`、`InitialWindowSize`——在那裡是無效的。公開 gRPC 表面要做 keepalive 強制，就得把 gRPC 拆到自己的 listener。
- **你需要 gRPC-Web。** Gortexa 不多工它，connect-go 有。
- **你無法跑 Go 1.27。** 框架以它為目標（機器上有 Go 1.21+ 即可 bootstrap，其餘由 `GOTOOLCHAIN` 下載）。
- **你想自訂攔截器順序。** 八段順序是設計上固定的。你可以在鏈內加自己的 interceptor、也可以抽換 auth 段的實作，但不能重排。
- **你不想讓 protobuf 當事實來源。** 這裡每個表面都由 proto 產生；JSON-first 或手寫 handler 的服務是在跟設計對抗。

## 常見問題

### Gortexa 是要取代 grpc-go 嗎？

不是——它建立在 grpc-go 之上。Gortexa 提供的是傳輸層以上的那幾層：多工的埠、固定的攔截器鏈、共用的錯誤模型與 MCP bridge。

### 可以搭配既有的 Buf 設定嗎？

可以。Gortexa 的 codegen 流程就是呼叫 `buf lint`、`buf breaking` 與 `buf generate`，既有的 `buf.yaml` 與 BSR 流程可以直接沿用。

### Gortexa 有什麼是 connect-go 沒有的？

它把標注過的 RPC 以 MCP tools 的形式開在同一個 port 上，並且經同一條攔截器鏈派送，所以 AI agent 的 `tools/call` 通過的 auth 與 validation 和人的請求完全一樣。另外它也用 grpc-gateway 從 `google.api.http` annotations 產生 REST 表面。

### 加上 MCP 是不是等於讓 AI agent 繞過我的授權？

不是。MCP `tools/call` 透過 in-process loopback 派送回同一個 gRPC server，所以它一樣要走 recover、request-id、logging、load shedding、rate limiting、斷路器、auth 與 validation。