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

核心型別

Route

type Route struct {
 Method string // HTTP 方法(GET, POST, PUT, DELETE...)
 Path string // 路由路徑(支援 :param 和 *catchall)
 Summary string // 一行描述(給 AI 和文件用)
 Description string // 詳細描述
 Tags []string // 分類標籤
 Input interface{} // 請求 body 的 Go struct(用於驗證)
 Output interface{} // 回應 body 的 Go struct(用於驗證)
 InputName string // 自動填入,無需手動設定
 OutputName string // 自動填入,無需手動設定
 Params []ParamSchema // 路徑/查詢參數描述
 Headers []HeaderSchema // 必要標頭描述
 Responses map[int]ResponseSchema // 各狀態碼的回應描述
}

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(全域註冊表)

// 查詢特定路由的 schema
route, ok := schema.Global().Get("POST", "/api/users")
// 取得所有已註冊的 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
├── reflect.go TypeName、FieldsOf、ValidateJSON 反射工具
└── schema_test.go 18 個單元測試

依賴關係

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

測試

go test ./pkg/schema/... -v