scaffold.md

pkg/scaffold — 智慧程式碼生成

scaffold 套件提供跨平台的程式碼生成功能，自動整合 Schema-first 路由、Error Catalog、Contract Testing。支援 Web、CLI、Desktop 三種專案模式。

支援的專案類型

類型	建立方式	UI 框架	適用場景
Web	hyp new myapp	HypGo Router	HTTP API、全棧 Web 應用
CLI	hyp new cli mytool	Cobra	命令列工具、Linux/Windows 系統工具
Desktop	hyp new desktop myapp	Fyne	Windows/Mac/Linux 桌面應用（原生 GUI）

Web 專案

生成 Controller

hyp generate controller user

一次產生 4 個檔案：

app/
├── controllers/user_controller.go   ← Handler 邏輯（不含路由定義）
├── routers/
│   ├── user.go                      ← Schema 路由（Input/Output）
│   ├── router.go                    ← Setup() 總入口（首次生成）
│   └── middleware.go                ← 中間件配置（首次生成）

Controller（app/controllers/user_controller.go）：

• 只包含 handler 方法（List、Create、Get、Update、Delete）
• 引用 models.CreateUserReq、models.UserResp 作為 Input/Output
• 預定義錯誤碼（ErrUserNotFound、ErrUserInvalid）

Router（app/routers/user.go）：

• Schema-first 路由定義
• 每個路由攜帶 Input/Output 型別、Summary、Tags、Responses
• 自動引用 controller 和 models

生成 Model

hyp generate model user

產生 5 個 struct：

// DB model
type User struct { ... }

// Schema Input — POST
type CreateUserReq struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

// Schema Input — PUT
type UpdateUserReq struct { ... }

// Schema Output — 單筆
type UserResp struct { ... }

// Schema Output — 列表
type UserListResp struct {
    Data  []UserResp `json:"data"`
    Total int        `json:"total"`
}

生成 Service

hyp generate service user

包含 Error Catalog 整合：

var ErrSvcUserNotFound = errors.Define("E_svc_user_001", 404, "User not found", "user")

Web 專案推薦順序

hyp generate model user          # 1. 先定義資料結構
hyp generate controller user     # 2. 生成 handler + router
hyp generate service user        # 3. 生成業務邏輯
# 4. 編輯 app/routers/router.go → 取消註解 RegisterUserRoutes(r)
# 5. main.go → routers.Setup(srv.Router())

CLI 專案

v0.8.5+ CLI、Desktop、gRPC 專案模式為 v0.8.5 新增功能。v0.8.1 僅支援 Web 專案類型。

建立 CLI 專案

hyp new cli mytool

生成結構：

mytool/
├── app/
│   ├── commands/
│   │   └── root.go        ← Cobra rootCmd
│   ├── models/            ← 共用：資料結構
│   ├── services/          ← 共用：業務邏輯
│   └── config/
│       └── config.yaml
├── main.go                ← commands.Execute()
└── go.mod

生成 CLI 子命令

hyp generate command process
hyp generate command export

每個子命令自動：

• 定義 *Cmd 變數和 run* 函式
• 在 init() 中註冊到 rootCmd
• 含預設的 flags 註解範例

生成的程式碼：

var processCmd = &cobra.Command{
    Use:   "process",
    Short: "Process command",
    RunE:  runProcess,
}

func init() {
    rootCmd.AddCommand(processCmd)
    // processCmd.Flags().StringP("input", "i", "", "Input file path")
}

func runProcess(cmd *cobra.Command, args []string) error {
    // TODO: implement process logic
    return nil
}

CLI 專案推薦順序

hyp new cli mytool                # 1. 建立專案
cd mytool && go mod tidy
hyp generate command process      # 2. 新增子命令
hyp generate command export       # 3. 新增更多子命令
hyp generate model task           # 4. 共用的資料結構
hyp generate service worker       # 5. 共用的業務邏輯
go run .                          # 6. 執行

Desktop 專案（Fyne GUI）

v0.8.5+ Desktop 專案模式（Fyne GUI）為 v0.8.5 新增功能。

建立 Desktop 專案

hyp new desktop myapp

生成結構：

myapp/
├── app/
│   ├── views/
│   │   └── main_view.go       ← 主畫面（Fyne widget + layout）
│   ├── models/                ← 共用：資料結構
│   ├── services/              ← 共用：業務邏輯
│   └── config/
│       └── config.yaml
├── main.go                    ← Fyne app.New() + window
└── go.mod                     ← 含 fyne.io/fyne/v2 依賴

注意：Fyne 需要 C 編譯器（gcc），因為 CGO 是必要依賴。Windows 可安裝 MSYS2 或 TDM-GCC。

生成 GUI View

hyp generate view settings
hyp generate view dashboard

每個 view 自動包含：

• fyne.Window 參數
• container.NewVBox 佈局
• widget.NewLabel + widget.NewSeparator 基本結構

生成的程式碼：

func SettingsView(w fyne.Window) fyne.CanvasObject {
    title := widget.NewLabel("Settings")
    title.TextStyle = fyne.TextStyle{Bold: true}

    // TODO: implement settings view layout

    return container.NewVBox(
        title,
        widget.NewSeparator(),
        widget.NewLabel("Settings view content goes here"),
    )
}

Desktop 專案推薦順序

hyp new desktop myapp            # 1. 建立專案
cd myapp && go mod tidy
hyp generate view settings       # 2. 新增設定畫面
hyp generate view dashboard      # 3. 新增儀表板
hyp generate model config        # 4. 共用的資料結構
hyp generate service storage     # 5. 共用的業務邏輯
go run .                         # 6. 執行

三種專案共用部分

目錄	Web	CLI	Desktop	共用？
app/controllers/	Handler 邏輯	—	—	Web only
app/routers/	Schema 路由	—	—	Web only
app/commands/	—	Cobra 子命令	—	CLI only
app/views/	—	—	Fyne GUI 視圖	Desktop only
app/models/	資料結構	資料結構	資料結構	✅ 三者共用
app/services/	業務邏輯	業務邏輯	業務邏輯	✅ 三者共用
app/config/	config.yaml	config.yaml	config.yaml	✅ 三者共用

API 參考

Web 生成

scaffold.GenerateController(dir, name, moduleName string) error
scaffold.GenerateRouter(dir, name, moduleName string) error
scaffold.GenerateRouterSetup(dir, name, moduleName string) error
scaffold.GenerateMiddleware(dir string) error
scaffold.GenerateModel(dir, name string) error
scaffold.GenerateService(dir, name string) error

CLI 生成

scaffold.GenerateCLIProject(baseDir, name, moduleName string) error
scaffold.GenerateCommand(dir, name string) error

Desktop 生成

scaffold.GenerateDesktopProject(baseDir, name, moduleName string) error
scaffold.GenerateView(dir, name string) error

安全

• 名稱驗證：只允許 [a-zA-Z][a-zA-Z0-9_]*（防止路徑穿越和 code injection）
• 長度限制：最多 64 字元
• 不覆蓋已存在的檔案（防止意外覆蓋手動修改）
• Module 名稱自動從 go.mod 偵測