Input/Output 機制詳解

總覽

Input(請求合約) Output(回應合約)
 │ │
 ├→ Contract Testing 驗證請求 body ├→ Contract Testing 驗證回應 body
 ├→ Manifest 記錄 input_type ├→ Manifest 記錄 output_type
 ├→ AI 知道要傳什麼 ├→ AI 知道會收到什麼
 └→ 自動生成測試資料 └→ 自動驗證必填欄位

第一部分:定義 Input/Output

基本規則

// Input — 客戶端發送的請求 body
type CreateUserReq struct {
 Name string `json:"name"` // 必填(非 pointer、無 omitempty)
 Email string `json:"email"` // 必填
 Bio string `json:"bio,omitempty"` // 選填(有 omitempty)
 Age *int `json:"age"` // 選填(pointer)
}
// Output — 伺服器回傳的回應 body
type UserResp struct {
 ID int64 `json:"id"`
 Name string `json:"name"`
 Email string `json:"email"`
 Bio string `json:"bio,omitempty"`
 CreatedAt string `json:"created_at"`
}

必填 vs 選填的判斷規則

required := !omitempty && f.Type.Kind() != reflect.Ptr

Input ≠ Output ≠ DB Model

// ❌ 錯誤:用 DB model 當 Input
r.Schema(schema.Route{
 Input: models.User{}, // 包含 ID、CreatedAt — 客戶端不該提供
})
// ✅ 正確:分開定義
type User struct { // DB model — 對應資料庫 table
 ID int64
 Name string
 CreatedAt time.Time
}
type CreateUserReq struct { // Input — 只有客戶端可提供的欄位
 Name string `json:"name"`
 Email string `json:"email"`
}
type UserResp struct { // Output — 只有要回傳的欄位
 ID int64 `json:"id"`
 Name string `json:"name"`
 Email string `json:"email"`
}

第二部分:在 Schema 中使用 Input/Output

註冊時傳入 struct 實例

r.Schema(schema.Route{
 Method: "POST",
 Path: "/api/users",
 Summary: "Create user",
 Input: CreateUserReq{}, // ← 傳入零值實例,框架只用型別資訊
 Output: UserResp{}, // ← 傳入零值實例
}).Handle(createUserHandler)

框架在註冊時做了什麼

1. NewSchemaRoute(route, registrar)
 │
 ├─ route.Input != nil ?
 │ └─ route.InputName = TypeName(route.Input)
 │ → reflect.TypeOf(CreateUserReq{}).Name() → "CreateUserReq"
 │
 ├─ route.Output != nil ?
 │ └─ route.OutputName = TypeName(route.Output)
 │ → "UserResp"
 │
 └─ Responses 中的 Type != nil ?
 └─ resp.TypeName = TypeName(resp.Type)
2. registrar.RegisterSchema(route, handlers...)
 │
 ├─ router.addRoute(method, path, handlers) ← 正常路由註冊
 │
 └─ schema.Global().Register(route) ← 存入全域 Schema Registry
 → key = "POST /api/users"
 → value = Route{Input: CreateUserReq{}, Output: UserResp{}, ...}

Schema Registry 儲存了什麼

// 全域 Registry 結構
type Registry struct {
 schemas []Route // 有序列表
 byKey map[string]*Route // "METHOD /path" → Route
}
// 每個 Route 中與 Input/Output 相關的欄位:
type Route struct {
 Input interface{} // Go struct 零值(CreateUserReq{})
 Output interface{} // Go struct 零值(UserResp{})
 InputName string // "CreateUserReq"(自動填入)
 OutputName string // "UserResp"(自動填入)
}

第三部分:Input/Output 在各層的作用

3.1 Manifest(AI 理解層)

routes:
 - method: POST
 path: /api/users
 summary: "Create user"
 input_type: CreateUserReq # ← InputName
 output_type: UserResp # ← OutputName
 handler_names: [controllers.CreateUser]

3.2 Contract Testing(驗證層)

自動測試(TestAll)

對每個路由:
 1. 有 Input?
 └─ generateMinimalJSON(route.Input)
 → 為每個欄位生成合理值:
 string → "test"
 int → 0
 bool → false
 slice → []
 → 結果:{"name":"test","email":"test","bio":"test"}
 2. 發送 HTTP 請求
 → method = route.Method
 → path = resolvePath(route.Path) // :id → "1"
 → body = 生成的 JSON
 3. 有 Output?
 └─ validateResponse(responseBody, route.Output)
 │
 ├─ json.Unmarshal(body, &OutputType{})
 │ → 確認 JSON 格式正確、欄位型別匹配
 │
 └─ validateRequiredFields(body, OutputType)
 → 遍歷 Output struct 的所有欄位
 → 非 pointer + 非 omitempty → 必填
 → 必填欄位不在 JSON 中 → 回報錯誤
 4. 驗證狀態碼
 → Responses 有宣告?用最小的 2xx 狀態碼
 → 沒有宣告?POST→201, DELETE→204, 其他→200

手動測試(Test)

contract.Test(t, router, contract.TestCase{
 Route: "POST /api/users",
 Input: `{"name":"alice","email":"alice@example.com"}`,
 ExpectStatus: 201,
 ExpectSchema: true, // ← 啟用 Output 驗證
})

3.3 Scaffold(生成層)

// 生成的 Input struct
type CreateUserReq struct {
 Name string `json:"name"` // 必填
 Description string `json:"description,omitempty"` // 選填
}
type UpdateUserReq struct {
 Name string `json:"name,omitempty"` // 全部選填(部分更新)
 Description string `json:"description,omitempty"`
 Active *bool `json:"active,omitempty"` // pointer = 選填
}

func (ctrl *UserController) Create(c *hypcontext.Context) {
 var req models.CreateUserReq // ← 引用 Input struct
 if err := c.ShouldBindJSON(&req); err != nil {
 errors.AbortWithAppError(c, ErrUserInvalid.With("reason", err.Error()))
 return
 }
 // ... 業務邏輯 ...
 c.JSON(201, models.UserResp{ // ← 引用 Output struct
 ID: user.ID,
 Name: req.Name,
 })
}

3.4 AI Rules(跨工具層)

## Current Routes
| Method | Path | Summary |
|--------|------|---------|
| POST | /api/users | Create user |
| GET | /api/users/:id | Get user |

第四部分:型別反射機制

TypeName — 取得型別名稱

schema.TypeName(CreateUserReq{}) → "CreateUserReq"
schema.TypeName(&CreateUserReq{}) → "CreateUserReq" // 自動解指標
schema.TypeName((*UserResp)(nil)) → "UserResp" // nil 指標也行
schema.TypeName(nil) → ""
schema.TypeName(42) → "int"

FieldsOf — 取得欄位清單

fields := schema.FieldsOf(CreateUserReq{})
// [
// {Name: "name", Type: "string", Required: true},
// {Name: "email", Type: "string", Required: true},
// {Name: "bio", Type: "string", Required: false}, // omitempty
// {Name: "age", Type: "integer", Required: false}, // pointer
// ]

ValidateJSON — 驗證 JSON 合規性

// 通過
err := schema.ValidateJSON(
 []byte(`{"name":"alice","email":"a@b.com"}`),
 CreateUserReq{},
)
// err == nil
// 失敗:缺少必填欄位
err := schema.ValidateJSON(
 []byte(`{"bio":"hello"}`),
 CreateUserReq{},
)
// err == "missing required field: name"
// 失敗:JSON 格式錯誤
err := schema.ValidateJSON(
 []byte(`{invalid json}`),
 CreateUserReq{},
)
// err == "JSON does not match schema CreateUserReq: ..."

GenerateZeroJSON — 生成零值 JSON

data := schema.GenerateZeroJSON(CreateUserReq{})
// {"name":"","email":"","bio":"","age":null}
data := schema.GenerateZeroJSON(nil)
// {}

Go 型別 → Schema 型別對照

第五部分:完整生命週期

👤 人定義 struct
 │
 ▼
┌──────────────────────────────────────────────────────┐
│ type CreateUserReq struct { │
│ Name string `json:"name"` │
│ Email string `json:"email"` │
│ } │
└──────────────────────────────────────────────────────┘
 │
 ▼
👤 人在 Schema 路由中引用
 │
 ▼
┌──────────────────────────────────────────────────────┐
│ r.Schema(schema.Route{ │
│ Input: CreateUserReq{}, ← 型別資訊進入框架 │
│ Output: UserResp{}, │
│ }).Handle(handler) │
└──────────────────────────────────────────────────────┘
 │
 ├──→ 🔧 Schema Registry 儲存型別
 │ key: "POST /api/users"
 │ Input: CreateUserReq{}(reflect.Type)
 │ InputName: "CreateUserReq"(string)
 │
 ├──→ 🔧 Manifest 輸出型別名稱
 │ input_type: CreateUserReq
 │ output_type: UserResp
 │
 ├──→ 🤖 AI 讀 manifest → 知道 Input/Output
 │ → 生成 handler 時使用正確的 struct
 │
 └──→ 🔧 Contract Testing 驗證
 TestAll()
 │
 ├─ generateMinimalJSON(CreateUserReq{})
 │ → {"name":"test","email":"test"}
 │
 ├─ 發送 POST /api/users,body = 上述 JSON
 │
 └─ validateResponse(body, UserResp{})
 → json.Unmarshal 到 UserResp
 → 檢查 id、name、email 都存在

第六部分:常見模式

列表回應(帶分頁)

type UserListResp struct {
 Data []UserResp `json:"data"`
 Total int `json:"total"`
}
r.Schema(schema.Route{
 Method: "GET",
 Path: "/api/users",
 Output: UserListResp{}, // ← 列表用 ListResp
}).Handle(ctrl.List)

部分更新(PATCH/PUT)

type UpdateUserReq struct {
 Name string `json:"name,omitempty"` // 全部 omitempty
 Email string `json:"email,omitempty"`
 Active *bool `json:"active,omitempty"` // 用 pointer 區分「沒傳」vs「傳 false」
}

無 body 的路由

// GET — 無 Input
r.Schema(schema.Route{
 Method: "GET",
 Path: "/api/users/:id",
 Output: UserResp{}, // 只有 Output
}).Handle(ctrl.Get)
// DELETE — 無 Input、無 Output
r.Schema(schema.Route{
 Method: "DELETE",
 Path: "/api/users/:id",
 // Input: nil, Output: nil
}).Handle(ctrl.Delete)

錯誤回應

// 定義錯誤碼
var ErrUserNotFound = errors.Define("E_user_001", 404, "User not found", "user")
// Handler 中使用
func (ctrl *UserController) Get(c *hypcontext.Context) {
 user := findUser(id)
 if user == nil {
 errors.AbortWithAppError(c, ErrUserNotFound.With("id", id))
 return // ← 回傳 {"code":"E_user_001","message":"User not found","details":{"id":"1"}}
 }
 c.JSON(200, UserResp{...}) // ← 回傳 Output struct
}

第七部分:除錯技巧

查看某個路由的 Input/Output

route, ok := schema.Global().Get("POST", "/api/users")
if ok {
 fmt.Printf("Input: %s\n", route.InputName) // "CreateUserReq"
 fmt.Printf("Output: %s\n", route.OutputName) // "UserResp"
 // 查看 Input 欄位
 fields := schema.FieldsOf(route.Input)
 for _, f := range fields {
 fmt.Printf(" %s (%s) required=%v\n", f.Name, f.Type, f.Required)
 }
}

手動驗證 JSON

err := schema.ValidateJSON(
 []byte(`{"name":"alice"}`), // 缺少 email
 CreateUserReq{},
)
fmt.Println(err) // "missing required field: email"

查看 Contract Testing 為某路由生成的測試資料

route := schema.Route{
 Method: "POST",
 Path: "/api/users",
 Input: CreateUserReq{},
}
// 框架內部用的是 generateMinimalJSON(unexported),但你可以用 GenerateZeroJSON
data := schema.GenerateZeroJSON(CreateUserReq{})
fmt.Println(string(data))
// {"name":"","email":"","bio":"","age":null}