pkg/schema — Schema-first Route Registration (Multi-Protocol)

Design Philosophy

Traditional: r.POST("/api/users", createUserHandler) <- AI needs to read handler source
Schema: r.Schema(Route{...}).Handle(handler) <- AI understands directly from metadata

Quick Start

import "github.com/maoxiaoyue/hypgo/pkg/schema"
// Define request/response types
type CreateUserRequest struct {
 Name string `json:"name"`
 Email string `json:"email"`
}
type UserResponse struct {
 ID int `json:"id"`
 Name string `json:"name"`
 Email string `json:"email"`
}
// Register a route with schema
r := router.New()
r.Schema(schema.Route{
 Method: "POST",
 Path: "/api/users",
 Summary: "Create user",
 Tags: []string{"users"},
 Input: CreateUserRequest{},
 Output: UserResponse{},
 Responses: map[int]schema.ResponseSchema{
 201: {Description: "User created"},
 400: {Description: "Invalid input"},
 },
}).Handle(createUserHandler)

With Route Groups

api := r.NewGroup("/api/v1")
api.Schema(schema.Route{
 Method: "GET",
 Path: "/products",
 Summary: "Get product list",
 Tags: []string{"products"},
 Output: []ProductResponse{},
}).Handle(listProductsHandler)
// Route is automatically registered as GET /api/v1/products

Mixed Usage

r.GET("/health", healthHandler) // Traditional route -- works as usual
r.Schema(schema.Route{...}).Handle(createHandler) // Schema route -- with metadata

Multi-Protocol Schema Registration

// gRPC
schema.RegisterGRPC("UserService/CreateUser", "Create user", CreateUserReq{}, UserResp{})
// Bot (Telegram, Line, Discord, WhatsApp, etc.)
schema.RegisterBot("/start", "Start the bot", nil, WelcomeMsg{})
schema.RegisterBotPlatform("telegram", "/game", "Start game", GameOpts{}, GameState{})
schema.RegisterBotPlatform("discord", "!play", "Play music", PlayReq{}, PlayResp{})
// MCP (Model Context Protocol)
schema.RegisterMCP("search_repos", "Search repos", SearchInput{}, SearchOutput{})
// WebSocket message types
schema.RegisterWebSocket("join_room", "Join room", JoinReq{}, JoinResp{})
// CLI subcommands
schema.RegisterCLI("process", "Process data", ProcessFlags{}, ProcessResult{})

Core Types

Route (Multi-Protocol)

type Route struct {
 // Universal fields (all protocols)
 Protocol string // "rest"(default), "grpc", "bot", "mcp", "websocket", "cli"
 Command string // Non-REST command identifier
 Platform string // Bot-specific platform: "telegram", "line", "discord", "whatsapp"
 Summary string // One-line description (for AI and documentation)
 Description string // Detailed description
 Tags []string // Classification tags
 Input interface{} // Request Go struct (for validation)
 Output interface{} // Response Go struct (for validation)
 InputName string // Auto-populated, no manual setup needed
 OutputName string // Auto-populated, no manual setup needed
 // REST-specific (backward compatible)
 Method string // HTTP method (GET, POST, PUT, DELETE...)
 Path string // Route path (supports :param and *catchall)
 Params []ParamSchema // Path/query parameter descriptions
 Headers []HeaderSchema // Required header descriptions
 Responses map[int]ResponseSchema // Response descriptions per status code
}
// RouteKey() returns the Registry lookup key
// REST: "rest|POST /api/users"
// gRPC: "grpc|UserService/CreateUser"
// Bot: "bot|/start"
// MCP: "mcp|search_repos"
// IsREST() returns true if this is a REST route

Supported Protocols

ParamSchema

type ParamSchema struct {
 Name string // Parameter name
 In string // "path", "query", "header"
 Required bool // Whether required
 Type string // "string", "int", "bool"
 Desc string // Description
}

ResponseSchema

type ResponseSchema struct {
 Description string // Response description
 Type interface{} // Go struct type (for Contract Testing validation)
 TypeName string // Auto-populated
}

Registry (Global Registry)

// Query REST route (backward compatible)
route, ok := schema.Global().Get("POST", "/api/users")
// Query by full key (any protocol)
route, ok := schema.Global().GetByKey("grpc|UserService/CreateUser")
route, ok := schema.Global().GetByKey("bot|/start")
// Filter by protocol
grpcRoutes := schema.Global().GetByProtocol("grpc")
botRoutes := schema.Global().GetByProtocol("bot")
// Get all registered schemas (all protocols)
all := schema.Global().All()
// Check registered count
count := schema.Global().Len()
// Reset (for testing)
schema.Global().Reset()

Reflection Utilities

// Get type name
schema.TypeName(UserResponse{}) // -> "UserResponse"
// Get struct field information
fields := schema.FieldsOf(UserResponse{})
// -> [{Name:"id", Type:"integer", Required:true}, ...]
// Validate JSON against struct (including required field checks)
err := schema.ValidateJSON([]byte(`{"name":"alice"}`), CreateUserRequest{})
// Generate zero-value JSON (for automated testing)
data := schema.GenerateZeroJSON(CreateUserRequest{})
// -> {"name":"","email":""}

Required Field Rules

Architecture

pkg/schema/
├── schema.go Route (multi-protocol), SchemaRoute, ParamSchema type definitions
├── registry.go Global thread-safe Registry (supports RouteKey multi-protocol lookup)
├── helpers.go RegisterGRPC/Bot/MCP/WebSocket/CLI convenience functions
├── reflect.go TypeName, FieldsOf, ValidateJSON reflection utilities
└── schema_test.go Unit tests

Dependencies

pkg/schema <- Only depends on pkg/context (HandlerFunc type)
 <- Does not depend on pkg/router (avoids circular dependency)