--- title: "goframe-v2 by gogf · skilld" canonical_url: "https://skilld.dev/gh/gogf/skills" meta: description: "Provides instruction and conventions for developing with GoFrame v2, a modular Go framework for building HTTP and gRPC services, microservices, and database operations using its… From gogf/skills." "og:description": "Provides instruction and conventions for developing with GoFrame v2, a modular Go framework for building HTTP and gRPC services, microservices, and database operations using its… From gogf/skills." "og:title": "goframe-v2 by gogf" "twitter:description": "Provides instruction and conventions for developing with GoFrame v2, a modular Go framework for building HTTP and gRPC services, microservices, and database operations using its… From gogf/skills." "twitter:title": "goframe-v2 by gogf" --- ` [All skills](https://skilld.dev/skills) [![gogf avatar](https://skilld.dev/_img/avatar?url=https%3A%2F%2Fgithub.com%2Fgogf.png%3Fsize%3D96)](https://skilld.dev/gh/gogf) # **/goframe-v2** [@911705d](https://github.com/gogf/skills/commit/911705dce72b18a297781c8bd0c0004018cfd4fe "Your agent reads SKILL.md at commit 911705d") by [GoFrame](https://skilld.dev/gh/gogf)· [gogf](https://skilld.dev/gh/gogf)/ [skills](https://skilld.dev/gh/gogf/skills)·81 stars 3 GoFrame v2 development skill. Use only when the target Go project uses or is explicitly adopting GoFrame v2: the nearest go.mod requires github.com/gogf/gf/v2, existing Go files import github.com/gogf/gf/v2 or any github.com/gogf/gf/v2/... component package, or the user asks to scaffold, migrate, or build with GoFrame. Trigger for GoFrame-backed Go work such as APIs/controllers/services, middleware, routing/config, ORM/DAO/DO/entity/database operations, gf CLI/codegen, HTTP/gRPC services, and microservice conventions. Do not trigger for generic Go projects without GoFrame evidence, frontend-only work, shell scripts, or unrelated infrastructure tasks. - 251 files - 1.7 MB - Apache-2 - Updated 4 months ago - [GitHub](https://github.com/gogf/skills/blob/911705dce72b18a297781c8bd0c0004018cfd4fe/skills/goframe-v2/SKILL.md "View SKILL.md on GitHub") - [1 alert](#third-party-checks "Third-party checks: 1 alert · 5 checks · Risk MEDIUM") ## SKILL.md 5.8 KB **≈168** tokens always: the name and description. **≈1.3k** when used: this file. **≈208k** more on demand in 153 files. ## Critical Conventions ### Project Development Standards - For complete projects (HTTP/microservices), install GoFrame CLI and use `gf init` to create project scaffolding. See [Project Creation - init](https://skilld.dev/gh/gogf/skills/goframe-v2/-/references/开发工具/项目创建-init.md) for details. - Auto-generated code files (dao, do, entity) MUST NOT be manually created or modified per GoFrame conventions. - Unless explicitly requested, do NOT use the `logic/` directory for business logic. Implement business logic directly in the `service/` directory. - Reference complete project examples: - HTTP service best practice: [user-http-service](https://github.com/gogf/skills/blob/main/skills/goframe-v2/examples/practices/user-http-service) - gRPC service best practice: [user-grpc-service](https://github.com/gogf/skills/blob/main/skills/goframe-v2/examples/practices/user-grpc-service) ### Component Usage Standards - Before creating new methods or variables, check if they already exist elsewhere and reuse existing implementations. - Use the `gerror` component for all error handling to ensure complete stack traces for traceability. - When exploring new components, prioritize GoFrame built-in components and reference best practice code from examples. - **Database Operations MUST use DO objects** ( `internal/model/do/`), never `g.Map` or `map[string]interface{}`. DO struct fields are `interface{}`; unset fields remain `nil` and are automatically ignored by the ORM: ``` // Good - use DO object dao.Users.Ctx(ctx).Where(cols.Id, id).Data(do.User{Uid: uid}).Update() // Good - conditional fields, unset fields are nil and ignored data := do.User{} if password != "" { data.PasswordHash = hash } if isAdmin != nil { data.IsAdmin = *isAdmin } dao.Users.Ctx(ctx).Where(cols.Id, id).Data(data).Update() // Good - explicitly set a column to NULL using gdb.Raw dao.Instances.Ctx(ctx).Where(cols.Id, id).Data(do.Instance{IdleSince: gdb.Raw("NULL")}).Update() // Bad - never use g.Map for database operations dao.Users.Ctx(ctx).Data(g.Map{cols.Uid: uid}).Update() ``` ### Code Style Standards - **Variable Declarations**: When defining multiple variables, use a `var` block to group them for better alignment and readability: ``` // Good - aligned and clean var ( authSvc *auth.Service bizCtxSvc *bizctx.Service k8sSvc *svcK8s.Service notebookSvc *notebook.Service middlewareSvc *middleware.Service ) // Avoid - scattered declarations authSvc := auth.New() bizCtxSvc := bizctx.New() k8sSvc := svcK8s.New() ``` - Apply this pattern when you have 3 or more related variable declarations in the same scope. ### Soft Delete & Time Maintenance GoFrame provides **automatic** soft delete and time maintenance features. When a table contains `created_at`, `updated_at`, or `deleted_at` fields, the ORM handles these automatically. #### Automatic Time Fields | Field | Auto Behavior | | --- | --- | | `created_at` | Auto-written on `Insert/InsertAndGetId`, never modified afterward | | `updated_at` | Auto-written on `Insert/Update/Save` | | `deleted_at` | Auto-written on `Delete` (soft delete), auto-filtered on queries | #### Critical Rules **1. NEVER manually set time fields** - GoFrame handles these automatically: ``` // WRONG - redundant manual time setting dao.User.Ctx(ctx).Data(do.User{ Name: "john", CreatedAt: gtime.Now(), // REDUNDANT! Framework handles this UpdatedAt: gtime.Now(), // REDUNDANT! Framework handles this }).Insert() // CORRECT - let framework handle time fields dao.User.Ctx(ctx).Data(do.User{ Name: "john", }).Insert() ``` **2. NEVER manually add `WhereNull(cols.DeletedAt)`** - GoFrame auto-adds soft delete filter: ``` // WRONG - redundant soft delete condition dao.User.Ctx(ctx). Where(do.User{Status: 1}). WhereNull(cols.DeletedAt). // REDUNDANT! Framework auto-adds this Scan(&list) // CORRECT - framework auto-adds deleted_at IS NULL dao.User.Ctx(ctx). Where(do.User{Status: 1}). Scan(&list) ``` **3. Use `Delete()` for soft delete** - Framework converts to `UPDATE SET deleted_at = NOW()`: ``` // CORRECT - use Delete(), framework handles soft delete dao.User.Ctx(ctx).Where(do.User{Id: id}).Delete() // Actual SQL: UPDATE `sys_user` SET `deleted_at`=NOW() WHERE `id`=? // WRONG - manual Update with deleted_at dao.User.Ctx(ctx). Where(do.User{Id: id}). Data(do.User{DeletedAt: gtime.Now()}). // REDUNDANT! Update() ``` #### Field Type Support The `deleted_at` field supports multiple types: - **DateTime/Timestamp**: Default, stores deletion time - **Integer**: Stores Unix timestamp (seconds) - **Boolean**: Stores 0/1 for deleted state #### Configuration (Optional) Time field names can be customized in `config.yaml`: ``` database: default: createdAt: "created_at" # Custom field name updatedAt: "updated_at" deletedAt: "deleted_at" timeMaintainDisabled: false # Set true to disable this feature ``` ## GoFrame Documentation Complete GoFrame development resources covering component design, usage, best practices, and considerations: [GoFrame Documentation](https://skilld.dev/gh/gogf/skills/goframe-v2/-/references/README.MD) ## GoFrame Code Examples Rich practical code examples covering HTTP services, gRPC services, and various project types: [GoFrame Examples](https://skilld.dev/gh/gogf/skills/goframe-v2/-/examples/README.MD) Source: [SKILL.md on GitHub](https://github.com/gogf/skills/blob/911705dce72b18a297781c8bd0c0004018cfd4fe/skills/goframe-v2/SKILL.md) ## Third-party checks
1 alert16d5 checks · Risk MEDIUM - Gen Agent Trust Hub16d The skill provides a comprehensive development guide and code examples for the GoFrame v2 framework. While highly informative for Go developers, it contains several examples with hardcoded placeholder secrets, tokens, and specific local file paths to sensitive configuration files (like Kubernetes credentials). These elements are provided for demonstration purposes but represent insecure practices if used in production without modification. - Socket16d 5 alerts: gptSecurity, gptAnomaly - Snyk16d Risk: LOW · No issues - Runlayer6mo 227/949 files flagged - ZeroLeaks5mo Score: 93/100 · 2 sections analyzed
## Provenance [Signed by skilld at 911705d.](https://github.com/gogf/skills/commit/911705dce72b18a297781c8bd0c0004018cfd4fe "911705dce72b18a297781c8bd0c0004018cfd4fe") This ties the file your Agent reads to that commit on GitHub. It does not review the instructions. Last checked against GitHub 4 months ago. Steadyupdated 4 months ago ## Topics - [Go](https://skilld.dev/skills/tag/go "Go-specific patterns and tooling") - [Database](https://skilld.dev/skills/tag/database "SQL/NoSQL, ORMs, migrations, query tuning") - goframe - orm - http - grpc - microservices - crud - scaffolding - middleware ## README badge ![README badge for gogf/skills](https://skilld.dev/b/gogf/skills?theme=light&label=0) ## What it does Provides instruction and conventions for developing with GoFrame v2, a modular Go framework for building HTTP and gRPC services, microservices, and database operations using its ORM, CLI tooling, and project scaffolding. Use this skill when the target project has GoFrame v2 as a dependency or when the user requests scaffolding, migrations, or service development with GoFrame conventions. Generated from the current SKILL.md. ## Frequently asked
When should I use this skill? Use this skill only when your Go project uses GoFrame v2, indicated by github.com/gogf/gf/v2 in go.mod or imports. Do not use for generic Go projects, frontend work, or infrastructure tasks unrelated to GoFrame.
Should I manually set created_at and updated_at fields? No. GoFrame automatically writes created\_at on insert and updated\_at on insert/update/save. Manually setting these fields is redundant and violates project conventions.
What should I use for database operations instead of g.Map? Always use DO objects from internal/model/do/. DO struct fields are interface{}, unset fields remain nil and are automatically ignored by the ORM.
How does soft delete work in GoFrame? Call Delete() on the DAO; GoFrame automatically converts it to UPDATE SET deleted\_at = NOW(). Queries automatically filter out soft-deleted rows without requiring manual WhereNull conditions.
Where should I implement business logic? Implement business logic directly in the service/ directory. Do not use the logic/ directory unless explicitly requested.
Generated from the current SKILL.md. These answers refresh after source changes. ## Related skills - - - - - -