# Gortexa

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

## 特色

### 單一 port 三協定
以 Go 原生 `http.Server.Protocols` 做 h2c 多工，一個 port 同時收 gRPC、HTTP/JSON 與 MCP。

### 固定順序攔截器鏈
recover → request-id → logger → load-shed → rate-limit → circuit-breaker → auth → validation。八段順序固定，缺件即啟動失敗。

### 統一錯誤模型
單一對應表輸出 gRPC status、HTTP status 與 MCP error envelope，內部原因不外洩。

### AI tool calls 過同一條鏈
MCP `tools/call` 走 in-process loopback，AI 的呼叫和人的請求一樣要過 auth 與 validation。

### 內建元件
分層 config、三態 health、slog ＋ OTLP、pgx ＋ sqlc、cache（in-memory 預設）、NATS／JetStream。

### 可作為模組單獨引用
`go get` 直接 import 框架 package——非 AI 服務取 kernel／interceptor／mq，AI 服務加 mcp bridge 與 gortexa.ai.v1 annotations，不必走 scaffold。見[元件用法](https://gortexa.sheng.page/components/)。

## 快速開始

想讓 coding agent 從提示詞快速建立可執行服務骨架，請使用[用 AI 快速開始](https://gortexa.sheng.page/ai-quickstart/)：它固定 release、驗證 toolchain、確認 scaffold 留下的是會拒絕啟動的 placeholder secret，並在同一個 shell 做 HTTP/MCP smoke test。要自己逐步執行，請走[手動快速開始](https://gortexa.sheng.page/quickstart/)。

兩條路都只建立 prototype；production 必做事項見[部署](https://gortexa.sheng.page/deployment/)。

或把框架當 Go module 直接引用——`go get` 後直接 import 各 package，不必走 scaffold：

```bash
go get github.com/yshengliao/gortexa@latest
```

各 package 用法見[元件用法](https://gortexa.sheng.page/components/)，最小 app 見[以模組使用](https://gortexa.sheng.page/quickstart/#以模組使用不走-scaffold)。

依照其中一條流程讓伺服器起在 :8080 後，可各打一發：

```bash
curl localhost:8080/healthz                                # 200：健康檢查開放
curl -XPOST localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'      # MCP：列出 proto 定義的 AI tools
curl localhost:8080/v1/resources/x                         # 401：auth 三協定共用
```

## 常見問題

### Gortexa 是什麼？

Contract-first、batteries-included 的 Go gRPC 框架：Protobuf 是單一事實來源，一個 h2c port 同時服務 gRPC、HTTP/JSON（grpc-gateway）與 MCP，三協定共用同一條攔截器鏈、錯誤模型與 auth。

### 需要哪個 Go 版本？

目標 Go 1.27。機器上有 Go 1.21+ 即可：`GOTOOLCHAIN` 會自動下載 go1.27.0。

### 三個協定怎麼共用一個 port？

用 Go 原生 `http.Server.Protocols` 做 h2c 多工；HTTP gateway 與 MCP bridge 經 in-process loopback 回撥 gRPC server，因此 auth、rate-limit、validation 與錯誤對應三協定完全一致。

### 一定要 Redis 或 Kafka 嗎？

不用。cache 預設 process-local in-memory（可選 redis）；訊息佇列用 NATS（core，at-most-once）或 JetStream（durable，at-least-once），沒有 Kafka 依賴。

### AI agent 怎麼呼叫我的 API？

在 proto 標上 `gortexa.ai.v1` annotations，MCP bridge 就把這些 RPC 變成 MCP tools；AI 的 `tools/call` 和人的請求一樣要通過 auth 與 validation。細節見 [MCP transport](https://gortexa.sheng.page/transports/mcp/)。

### Gortexa 跟 connect-go 差在哪？

兩者都在單一 port 多工協定，但多工的協定不同：connect-go 是 Connect／gRPC／gRPC-Web，Gortexa 是 gRPC／HTTP/JSON（grpc-gateway）／MCP。差異軸在 AI：Gortexa 把標注過的 RPC 開成 MCP tools，且走同一條攔截器鏈。逐項對照見[框架比較](https://gortexa.sheng.page/comparison/)。

### 可以不建 scaffold、只用部分元件嗎？

可以。`go get github.com/yshengliao/gortexa` 之後直接 import `kernel`、`interceptor`、`mq`、`mcp` 等公開 package，逐個單獨使用。見[元件用法](https://gortexa.sheng.page/components/)。