-
Notifications
You must be signed in to change notification settings - Fork 0
scaffold_en.md
maoxiaoyue edited this page May 14, 2026
·
1 revision
The scaffold package provides cross-platform code generation functionality, automatically integrating Schema-first routes, Error Catalog, and Contract Testing. Supports Web, CLI, and Desktop project modes.
| Type | Creation Method | UI Framework | Use Case |
|---|---|---|---|
| Web | hyp new myapp |
HypGo Router | HTTP API, full-stack web applications |
| CLI | hyp new cli mytool |
Cobra | Command-line tools, Linux/Windows system utilities |
| Desktop | hyp new desktop myapp |
Fyne | Windows/Mac/Linux desktop applications (native GUI) |
hyp generate controller user
Generates 4 files at once:
app/
├── controllers/user_controller.go <- Handler logic (no route definitions)
├── routers/
│ ├── user.go <- Schema routes (Input/Output)
│ ├── router.go <- Setup() main entry point (first generation only)
│ └── middleware.go <- Middleware configuration (first generation only)
Controller (app/controllers/user_controller.go):
- Contains only handler methods (List, Create, Get, Update, Delete)
- References
models.CreateUserReq,models.UserRespas Input/Output - Predefined error codes (
ErrUserNotFound,ErrUserInvalid)
Router (app/routers/user.go):
- Schema-first route definitions
- Each route carries Input/Output types, Summary, Tags, Responses
- Automatically references controller and models
hyp generate model user
Generates 5 structs:
// 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 -- single item type UserResp struct { ... } // Schema Output -- list type UserListResp struct { Data []UserResp `json:"data"` Total int `json:"total"` }
hyp generate service user
Includes Error Catalog integration:
var ErrSvcUserNotFound = errors.Define("E_svc_user_001", 404, "User not found", "user")
hyp generate model user # 1. Define data structures first hyp generate controller user # 2. Generate handler + router hyp generate service user # 3. Generate business logic # 4. Edit app/routers/router.go -> uncomment RegisterUserRoutes(r) # 5. main.go -> routers.Setup(srv.Router())
v0.8.5+CLI, Desktop, and gRPC project modes are new in v0.8.5. v0.8.1 supports Web projects only.
hyp new cli mytool
Generated structure:
mytool/
├── app/
│ ├── commands/
│ │ └── root.go <- Cobra rootCmd
│ ├── models/ <- Shared: data structures
│ ├── services/ <- Shared: business logic
│ └── config/
│ └── config.yaml
├── main.go <- commands.Execute()
└── go.mod
hyp generate command process hyp generate command export
Each subcommand automatically:
- Defines a
*Cmdvariable andrun*function - Registers with
rootCmdininit() - Includes default flag annotation examples
Generated code:
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 }
hyp new cli mytool # 1. Create project cd mytool && go mod tidy hyp generate command process # 2. Add subcommand hyp generate command export # 3. Add more subcommands hyp generate model task # 4. Shared data structures hyp generate service worker # 5. Shared business logic go run . # 6. Run
v0.8.5+Desktop project mode (Fyne GUI) is new in v0.8.5.
hyp new desktop myapp
Generated structure:
myapp/
├── app/
│ ├── views/
│ │ └── main_view.go <- Main view (Fyne widget + layout)
│ ├── models/ <- Shared: data structures
│ ├── services/ <- Shared: business logic
│ └── config/
│ └── config.yaml
├── main.go <- Fyne app.New() + window
└── go.mod <- Includes fyne.io/fyne/v2 dependency
Note: Fyne requires a C compiler (gcc) because CGO is a required dependency. On Windows, install MSYS2 or TDM-GCC.
hyp generate view settings hyp generate view dashboard
Each view automatically includes:
-
fyne.Windowparameter -
container.NewVBoxlayout -
widget.NewLabel+widget.NewSeparatorbasic structure
Generated code:
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"), ) }
hyp new desktop myapp # 1. Create project cd myapp && go mod tidy hyp generate view settings # 2. Add settings view hyp generate view dashboard # 3. Add dashboard hyp generate model config # 4. Shared data structures hyp generate service storage # 5. Shared business logic go run . # 6. Run
| Directory | Web | CLI | Desktop | Shared? |
|---|---|---|---|---|
app/controllers/ |
Handler logic | -- | -- | Web only |
app/routers/ |
Schema routes | -- | -- | Web only |
app/commands/ |
-- | Cobra subcommands | -- | CLI only |
app/views/ |
-- | -- | Fyne GUI views | Desktop only |
app/models/ |
Data structures | Data structures | Data structures | Shared across all three |
app/services/ |
Business logic | Business logic | Business logic | Shared across all three |
app/config/ |
config.yaml | config.yaml | config.yaml | Shared across all three |
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
scaffold.GenerateCLIProject(baseDir, name, moduleName string) error scaffold.GenerateCommand(dir, name string) error
scaffold.GenerateDesktopProject(baseDir, name, moduleName string) error scaffold.GenerateView(dir, name string) error
- Name validation: Only allows
[a-zA-Z][a-zA-Z0-9_]*(prevents path traversal and code injection) - Length limit: Maximum 64 characters
- Does not overwrite existing files (prevents accidental overwriting of manual modifications)
- Module name auto-detected from
go.mod
設計文件
套件
- config — 設定
- context — 請求上下文
- router — 路由器
- server — 伺服器
- middleware — 中介層
- websocket — WebSocket
- hidb — 資料庫 ORM
- hidb/cassandra — Cassandra
- logger — 日誌
- json — JSON 處理
- grpc — gRPC
AI 協作工具鏈
- schema — Schema-first 路由
- manifest — 專案 Manifest
- contract — Contract Testing
- errors — Typed Error Catalog
- migrate — Migration Diff
- scaffold — 智慧 Scaffold
- airules — AI Rules
CLI 命令
- hyp 總覽
- hyp new
- hyp api
- hyp run
- hyp restart
- hyp generate
- hyp migrate
- hyp context
- hyp ai-rules
- hyp chkcomment
- hyp impact
- hyp docker
- hyp health
- hyp version
- hyp difflog
Design Docs
Packages
- config — Configuration
- context — Request Context
- router — Router
- server — Server
- middleware — Middleware
- websocket — WebSocket
- hidb — Database ORM
- hidb/cassandra - Cassandra 5.0
- logger — Logger
- json — JSON
- grpc — gRPC
AI Collaboration Toolchain
- schema — Schema-first Routing
- manifest — Project Manifest
- contract — Contract Testing
- errors — Typed Error Catalog
- migrate — Migration Diff
- scaffold — Smart Scaffold
- airules — AI Rules
CLI Commands