pkg/schema — Schema-first 路由註冊(多協議)

設計理念

傳統:r.POST("/api/users", createUserHandler) ← AI 需讀 handler 原始碼
Schema:r.Schema(Route{...}).Handle(handler) ← AI 直接從 metadata 理解

快速上手

import "github.com/maoxiaoyue/hypgo/pkg/schema"
// 定義請求/回應型別
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"`
}
// 註冊帶 schema 的路由
r := router.New()
r.Schema(schema.Route{
 Method: "POST",
 Path: "/api/users",
 Summary: "建立使用者",
 Tags: []string{"users"},
 Input: CreateUserRequest{},
 Output: UserResponse{},
 Responses: map[int]schema.ResponseSchema{
 201: {Description: "User created"},
 400: {Description: "Invalid input"},
 },
}).Handle(createUserHandler)

搭配路由群組

api := r.NewGroup("/api/v1")
api.Schema(schema.Route{
 Method: "GET",
 Path: "/products",
 Summary: "取得商品列表",
 Tags: []string{"products"},
 Output: []ProductResponse{},
}).Handle(listProductsHandler)
// 路由自動註冊為 GET /api/v1/products

混合使用

r.GET("/health", healthHandler) // 傳統路由 — 照常使用
r.Schema(schema.Route{...}).Handle(createHandler) // Schema 路由 — 附帶 metadata

多協議 Schema 註冊

// gRPC
schema.RegisterGRPC("UserService/CreateUser", "Create user", CreateUserReq{}, UserResp{})
// Bot(Telegram, Line, Discord, WhatsApp 等)
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 訊息類型
schema.RegisterWebSocket("join_room", "Join room", JoinReq{}, JoinResp{})
// CLI 子命令
schema.RegisterCLI("process", "Process data", ProcessFlags{}, ProcessResult{})

核心型別

Route(支援多協議)

type Route struct {
 // 通用欄位(所有協議共用)
 Protocol string // "rest"(default), "grpc", "bot", "mcp", "websocket", "cli"
 Command string // 非 REST 命令標識(gRPC method、bot command、MCP tool...)
 Platform string // bot 專用平台:"telegram", "line", "discord", "whatsapp"
 Summary string // 一行描述(給 AI 和文件用)
 Description string // 詳細描述
 Tags []string // 分類標籤
 Input interface{} // 請求的 Go struct(用於驗證)
 Output interface{} // 回應的 Go struct(用於驗證)
 InputName string // 自動填入,無需手動設定
 OutputName string // 自動填入,無需手動設定
 // REST 專用(向後相容)
 Method string // HTTP 方法(GET, POST, PUT, DELETE...)
 Path string // 路由路徑(支援 :param 和 *catchall)
 Params []ParamSchema // 路徑/查詢參數描述
 Headers []HeaderSchema // 必要標頭描述
 Responses map[int]ResponseSchema // 各狀態碼的回應描述
}
// RouteKey() 回傳 Registry 查詢 key
// REST: "rest|POST /api/users"
// gRPC: "grpc|UserService/CreateUser"
// Bot: "bot|/start"
// MCP: "mcp|search_repos"
// IsREST() 判斷是否為 REST 路由

支援的協議

ParamSchema

type ParamSchema struct {
 Name string // 參數名稱
 In string // "path", "query", "header"
 Required bool // 是否必填
 Type string // "string", "int", "bool"
 Desc string // 描述
}

ResponseSchema

type ResponseSchema struct {
 Description string // 回應描述
 Type interface{} // Go struct type(用於 Contract Testing 驗證)
 TypeName string // 自動填入
}

Registry(全域註冊表)

// 查詢 REST 路由(向後相容)
route, ok := schema.Global().Get("POST", "/api/users")
// 根據完整 key 查詢(任何協議)
route, ok := schema.Global().GetByKey("grpc|UserService/CreateUser")
route, ok := schema.Global().GetByKey("bot|/start")
// 按協議篩選
grpcRoutes := schema.Global().GetByProtocol("grpc")
botRoutes := schema.Global().GetByProtocol("bot")
// 取得所有已註冊的 schema(所有協議)
all := schema.Global().All()
// 查看已註冊數量
count := schema.Global().Len()
// 清空(測試用)
schema.Global().Reset()

反射工具

// 取得型別名稱
schema.TypeName(UserResponse{}) // → "UserResponse"
// 取得 struct 欄位資訊
fields := schema.FieldsOf(UserResponse{})
// → [{Name:"id", Type:"integer", Required:true}, ...]
// 驗證 JSON 是否符合 struct(含必填欄位檢查)
err := schema.ValidateJSON([]byte(`{"name":"alice"}`), CreateUserRequest{})
// 生成零值 JSON(用於自動測試)
data := schema.GenerateZeroJSON(CreateUserRequest{})
// → {"name":"","email":""}

Required 判定規則

架構

pkg/schema/
├── schema.go Route(多協議)、SchemaRoute、ParamSchema 等型別定義
├── registry.go 全域 thread-safe Registry(支援 RouteKey 多協議查詢)
├── helpers.go RegisterGRPC/Bot/MCP/WebSocket/CLI 便捷函式
├── reflect.go TypeName、FieldsOf、ValidateJSON 反射工具
└── schema_test.go 單元測試

依賴關係

pkg/schema ← 僅依賴 pkg/context(HandlerFunc 型別)
 ← 不依賴 pkg/router(避免迴圈依賴)