docs\en\Story.md

Why Do We Need Another Go Web Framework? The Birth of HypGo

HypGo — the name comes from Hyper + Go

In the world of Go, there is no shortage of high-performance web frameworks. From Gin's rapid routing to Echo's extensibility, the ecosystem is vibrant and diverse. However, after developing several projects, I noticed some recurring "friction points" that — especially in the AI era — not only slowed down development but also introduced technical debt in the later stages of projects.

I believe that a modern framework should not just be "usable"; it should guide developers toward a more robust and forward-thinking architecture right from the design and conceptualization phase. This is why I created HypGo.

HypGo aims to solve four core problems:

1. Absence of Modern Network Protocols: Support for HTTP/2 and HTTP/3 is nearly absent across the frameworks I've seen.
2. The "Lightweight" Paradox of Choice: The framework itself is minimal, but the burden of integrating other functionalities is left entirely to the developer.
3. A Fragmented Integration Experience: Various modules feel like a loose collection of parts rather than a tightly cohesive whole.
4. The AI Collaboration Gap: Existing frameworks never considered how to let AI tools truly understand your project.

---

1. Native HTTP/2 and HTTP/3 Support: No More Last-Minute Fixes

Months into a project, during performance testing, you realize that to fully leverage the multiplexing advantages of modern browsers, you must enable HTTP/2. Or, in pursuit of lower latency, the team decides to upgrade to HTTP/3. It's only then that you discover your current framework requires a series of complex configurations, or even third-party packages, just to get it working.

This "add-it-later" approach is fraught with risk — time-consuming and potentially conflicting with your existing architecture.

Support for modern network protocols should be a built-in capability of the framework, not a plugin. In HypGo, switching protocols is a single line in the config file:

server:
  protocol: "http3"   # http1 / http2 / http3 — available from day one

The complex underlying processes are encapsulated, allowing you to confidently adopt the most advanced network technologies from the very start.

---

2. The AI Collaboration Gap: Letting AI Truly Understand Your Project

This is the fourth problem I deeply felt from late 2025 through 2026, as AI-assisted coding emerged and clearly was not going to go away. It became the core motivation driving HypGo toward v0.8 (versions before 0.7 had no AI-human collaboration features).

AI tools (Copilot, Cursor, Codex, Gemini CLI) have become everyday partners for modern developers. But they face a fundamental challenge: they don't know what your project is doing.

Every conversation, the AI has to re-read thousands of lines of code to understand API contracts. It can't tell which packages are shared or how many tests a change will affect. It doesn't know what inputs a route accepts or what format it returns. Developers end up spending enormous token budgets repeatedly "teaching" the AI basics, instead of having it actually solve problems.

HypGo's answer: Schema-first + Manifest + AI Rules

Schema-first routing attaches every API contract directly to the route:

r.Schema(schema.Route{
    Method:  "POST",
    Path:    "/api/users",
    Summary: "Create user",
    Input:   CreateUserRequest{},
    Output:  UserResponse{},
}).Handle(createUserHandler)

// Non-REST protocols work the same way
schema.RegisterGRPC("UserService/CreateUser", "Create user", Req{}, Resp{})
schema.RegisterWebSocket("join_room", "Join room", JoinReq{}, JoinResp{})

Project Manifest automatically generates .hyp/context.yaml at server startup, compressing the entire project's routes, types, and config into ~500 tokens (vs. ~5,000 tokens the traditional way). The AI reads one file and understands all APIs.

Contract Testing lets AI-generated handlers be verified immediately:

contract.TestAll(t, router)  // One line — automatically tests all schema routes' Input/Output

The hyp CLI toolset brings AI collaboration into the daily workflow:

hyp context               # Generate .hyp/context.yaml (the AI's project map)
hyp context --llm config/llm.yaml  # Enhance with local Ollama or a cloud LLM API
hyp ai-rules              # Generate config files for Copilot, Cursor, Codex, Gemini, Windsurf
hyp chkcomment ./...      # Check @ai: annotation completeness
hyp impact pkg/errors/catalog.go  # Confirm impact scope before modifying shared packages
hyp migrate diff          # Auto-generate SQL migration from model struct changes

This creates a complete closed loop: AI understands → generates → verifies → understands again (upgrade, new version).

---

3. Building a Seamless Development Experience

A lack of integration is the inevitable result of the first two problems. When you manually piece together logging, routing, ORM, and configuration modules, they remain disconnected:

• Your ORM is unaware of the request timeout set at the routing layer.
• Your logging module doesn't know who the current user is.
• When your configuration changes, there is no smooth way to notify all corners of the application.

This leads to large amounts of boilerplate code and inconsistent behavior.

HypGo's core design philosophy is deep integration.

• Unified Context: Flows through the entire request lifecycle — from middleware and handlers to database operations, easily passing data and controlling timeouts and cancellation.
• GC Optimizations: sync.Pool manages Context, Params, WebSocket broadcast slices, and RouteCache items, significantly reducing GC pressure at 100k+ QPS.
• Secure Middleware: Rate Limiter, Circuit Breaker, JWT, and CSRF all use crypto/rand; the Rate Limiter automatically cleans up expired entries to prevent memory leaks.

In the end, what you get is not just a collection of features, but a highly cohesive, loosely coupled application platform.

---

2. From "Lightweight" to "Just Right": Say Goodbye to Analysis Paralysis

Many frameworks pride themselves on being "lightweight," which is certainly appealing at first. But "lightweight" often means "empty." When you need to handle databases, configurations, validation, logging, and other real-world business requirements, you are immediately thrown into an "ocean of choices":

• For logging, should I use logrus, zap, or zerolog?
• For an ORM, should I choose GORM, sqlx, or ent? How do they interact with the framework's Context?
• For configuration management, should I use Viper or native flags?

This model shifts the heavy responsibility of architectural integration entirely onto the developer.

HypGo chooses a different path: curated solutions, deeply integrated with AI.

• Logging: Built-in structured logging, automatically bound to the request lifecycle — every log line includes a Request-ID.
• Configuration: Powerful config module that reads from files and environment variables, available via dependency injection.
• Database: Seamless Bun ORM integration, *bun.DB directly from Context, automatic transaction management; plus a full Redis/KeyDB high-level wrapper and complete Cassandra 5.0 driver.
• Multi-Protocol Schema: REST, gRPC, Bot, MCP, WebSocket, and CLI — all six protocols managed in a single Schema Registry, with one Manifest covering all APIs.

Use the built-in solutions for out-of-the-box convenience, or swap them out if needed. The goal is to eliminate unnecessary decision fatigue.

---

Modern from the Start

A great framework should act like an experienced architect, laying out a clear path to success from the very beginning of a project.

HypGo's mission is to empower every Gopher to easily and confidently adopt better, more modern solutions right from the design and conceptualization phase — whether that's native HTTP/3, a read-write-separated database layer, or deep collaboration with AI tools — building truly future-proof applications.

We sincerely invite you to try HypGo and join our community. Whether it's submitting an Issue, opening a Pull Request, or simply giving us a star, your support means the world to us!

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