Story.md

為何我們需要另一個 Go Web 框架？HypGo 的誕生

HypGo 的名稱來自於 Hyper + Go

在 Go 的世界裡，我們從不缺乏高效能的 Web 框架。從 Gin 的快速路由到 Echo 的可擴展性。然而，我發現了一些反覆出現的問題，這些問題在現在的AI時代，不僅拖慢了開發速度，更在專案後期埋下了技術債。

我相信，一個現代化的框架不應只是「能用」，更應該在專案的設計與構思階段就引導開發者走向更健壯、更具前瞻性的架構。這就是我打造 HypGo 的原因。

HypGo 旨在解決我們觀察到的四大核心問題：

1. 現代網路協定的缺席：HTTP/2 與 HTTP/3 支援在所見的範圍中，幾乎缺席。
2. 「輕量級」的選擇悖論：框架本身很小，但將整合其他功能的重擔完全拋給了開發者。
3. 支離破碎的整合體驗：各個模組像是一盤散沙，而非一個緊密協作的整體。
4. AI 時代的協作空白：現有框架從未考慮如何讓 AI 工具真正理解你的專案。

---

1. 原生支援 HTTP/2 與 HTTP/3：不再亡羊補牢

專案開發了數個月，效能測試時才發現，要充分利用現代瀏覽器的多路復用優勢，必須啟用 HTTP/2；或者，為了追求更低的延遲，團隊決定升級到 HTTP/3。這時，您才意識到手邊的框架需要一連串複雜的配置，甚至引入第三方 package 來啟動 http.Server 或 quic-go。

這種「後期追加」的模式充滿風險。它不僅耗時，還可能與現有架構產生衝突。

我認為，對現代網路協定的支援應該是框架的內建能力，而非一個需要額外安裝的插件。在 HypGo 中，切換協議只需修改設定檔的一行：

server:
  protocol: "http3"   # http1 / http2 / http3，從第一天起就可以選

複雜的底層處理封裝好，從專案第一天起，就能自信地採用最先進的網路技術，而不是等到出問題時才來補救。

---

2. AI 時代的協作空白：讓 AI 真正理解你的專案

這是我在 2025 年底到2026年，OpenClaw出現，深刻感受到的一個問題，使用AI的Coding是不會回頭，這也促使 HypGo 走向 v0.8 的核心動力(0.7之前並沒有人機協作)。

AI 工具（Copilot、Cursor、Codex、Gemini CLI）已經成為現代開發者的日常夥伴。但它們面臨一個根本困境：它們不知道你的專案在做什麼。

幻覺率、debug找不到問題癥結、改版的時候需求在哪? 改第二個bug後...第一個bug又再出現，這些問題變成Vibe Coding的開發者的日常。

每次對話，AI 都需要重新閱讀數千行程式碼才能理解 API 合約；它看不出哪些 package 是共享的、改動它會影響多少測試；它不知道哪個路由接受什麼輸入、回傳什麼格式。開發者不得不花大量 tokens 反覆「教」AI 基礎知識，而不是讓它真正幫你解決問題。

HypGo 的答案：Schema-first + Manifest + AI Rules

Schema-first 路由讓每個 API 合約直接附著在路由上：

r.Schema(schema.Route{
    Method:  "POST",
    Path:    "/api/users",
    Summary: "建立使用者",
    Input:   CreateUserRequest{},
    Output:  UserResponse{},
}).Handle(createUserHandler)

// 非 REST 協議也一樣
schema.RegisterGRPC("UserService/CreateUser", "建立使用者", Req{}, Resp{})
schema.RegisterWebSocket("join_room", "加入房間", JoinReq{}, JoinResp{})

Project Manifest 在伺服器啟動時自動生成 .hyp/context.yaml，將整個專案的路由、型別、設定壓縮為約 500 tokens（傳統方式需要 5,000 tokens）。AI 讀一個檔案，就能理解所有 API。

Contract Testing 讓 AI 生成的 handler 立刻可以驗證：

contract.TestAll(t, router)  // 一行，自動測試所有 schema 路由的 Input/Output

hyp CLI 工具群讓 AI 協作進入日常流程：

hyp context               # 產出 .hyp/context.yaml（AI 的專案地圖）
hyp context --llm config/llm.yaml  # 搭配本地 Ollama 或 API 做 LLM 智慧增強
hyp ai-rules              # 為 Copilot、Cursor、Codex、Gemini、Windsurf 產出設定檔
hyp chkcomment ./...      # 檢查 @ai: 標準化註解完整性
hyp impact pkg/errors/catalog.go  # 改動前先確認影響範圍
hyp migrate diff          # 從 model struct 自動產生 SQL migration

這形成了一個完整的閉環：AI 理解 → 生成 → 驗證 → 再理解(升級、改版)。

---

3. 打造無縫的開發體驗

整合度不足是前兩個問題的必然結果。當您自行拼湊日誌、路由、ORM 和設定模組時，它們之間往往是脫節的：

• 您的 ORM 無法感知到路由層的請求超時。
• 您的日誌模組不知道目前的使用者是誰。
• 您的設定變更後，無法平滑地通知到應用程式的各個角落。

這導致了大量的樣板代碼（Boilerplate）和不一致的行為。

HypGo 的核心設計理念就是深度整合。

• 統一的 Context：貫穿請求整個生命週期，從中介層、處理函式到資料庫操作，輕易傳遞資料、控制超時與取消訊號。
• GC 優化：sync.Pool 管理 Context、Params、WebSocket broadcast slice 與 RouteCache item，在 100k+ QPS 下大幅降低 GC 壓力。
• 安全中介層：Rate Limiter、Circuit Breaker、JWT、CSRF 均使用 crypto/rand，RateLimiter 自動清理過期 entry 防止記憶體洩漏。

最終，得到的不只是一堆功能的集合，而是一個高內聚、低耦合的應用程式平台。

---

4. 告別選擇困難：從「輕量」到「恰到好處」

許多框架以「輕量」為傲，這在初期確實很有吸引力。但「輕量」往往意味著「簡單」。當您需要處理資料庫、設定檔、驗證、日誌等實際業務需求時，您會立刻陷入一個「選擇的海洋」：

• 日誌要用 logrus、zap 還是 zerolog？
• ORM 該選 GORM、sqlx 還是 ent？它們如何與框架的 Context 互動？
• 設定檔管理用 Viper 還是原生的 flag？如何優雅地載入到應用中？

這種模式將架構整合的重責大任完全推給了開發者。開發者不僅要花費大量時間研究、評估，還要親自黏合這些來自不同社群的組件，並祈禱它們能和諧共處。

HypGo 選擇了一條不同的路：提供經過挑選且與AI深度整合的推薦方案。

• 日誌：內建結構化日誌，自動與請求生命週期綁定，每條日誌都包含 Request-ID。
• 設定：強大的設定模組，能從檔案、環境變數讀取設定，並以依賴注入的方式取用。
• 資料庫：與 Bun ORM 無縫整合，從 Context 中直接獲取 *bun.DB 實例，自動管理交易；同時內建 Redis/KeyDB 高階封裝與 Cassandra 5.0 完整驅動。
• 多協議 Schema：REST、gRPC、Bot、MCP、WebSocket、CLI 六種協議，統一在一個 Schema Registry 中管理，一份 Manifest 涵蓋所有 API。

您可以選擇使用這些內建方案，享受開箱即用的便利；當然，如果有特殊需求，也可以輕易地替換。我們的目標是消除無謂的決策疲勞，讓您專注於商業邏輯。

---

從起點就現代化

一個優秀的框架應該像一位經驗豐富的架構師，在專案之初就為您規劃好一條通往成功的大道。

HypGo 的使命，是讓每一位 Gopher 都能輕鬆、自信地從設計與構思階段就採用更好、更現代化的方案——無論是原生 HTTP/3、讀寫分離的資料庫層、還是與 AI 工具的深度協作，打造出真正面向未來的應用程式。

我們誠摯地邀請您試用 HypGo，並加入我們的社群。無論是提交一個 Issue、發起一個 Pull Request，或僅僅是給我們一顆星星，都是對我們最大的支持！

HypGo v0.8.5 · HTTP/1.1 + HTTP/2 + HTTP/3 · AI-Human Collaborative Go Web Framework
go get github.com/maoxiaoyue/hypgo