{"id":"c2620631-6f1a-4538-affe-f7a9cae75b30","shortId":"6drWdc","kind":"skill","title":"goframe-v2","tagline":"GoFrame development skill. TRIGGER when writing/modifying Go files, implementing services, creating APIs, or database operations. DO NOT TRIGGER for frontend/shell scripts.","description":"# Critical Conventions\n\n## Project Development Standards\n- For complete projects (HTTP/microservices), install GoFrame CLI and use `gf init` to create project scaffolding. See [Project Creation - init](./references/开发工具/项目创建-init.md) for details.\n- Auto-generated code files (dao, do, entity) MUST NOT be manually created or modified per GoFrame conventions.\n- Unless explicitly requested, do NOT use the `logic/` directory for business logic. Implement business logic directly in the `service/` directory.\n- Reference complete project examples:\n  - HTTP service best practice: [user-http-service](./examples/practices/user-http-service)\n  - gRPC service best practice: [user-grpc-service](./examples/practices/user-grpc-service)\n\n## Component Usage Standards\n- Before creating new methods or variables, check if they already exist elsewhere and reuse existing implementations.\n- Use the `gerror` component for all error handling to ensure complete stack traces for traceability.\n- When exploring new components, prioritize GoFrame built-in components and reference best practice code from examples.\n- **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:\n  ```go\n  // Good - use DO object\n  dao.Users.Ctx(ctx).Where(cols.Id, id).Data(do.User{Uid: uid}).Update()\n\n  // Good - conditional fields, unset fields are nil and ignored\n  data := do.User{}\n  if password != \"\" { data.PasswordHash = hash }\n  if isAdmin != nil { data.IsAdmin = *isAdmin }\n  dao.Users.Ctx(ctx).Where(cols.Id, id).Data(data).Update()\n\n  // Good - explicitly set a column to NULL using gdb.Raw\n  dao.Instances.Ctx(ctx).Where(cols.Id, id).Data(do.Instance{IdleSince: gdb.Raw(\"NULL\")}).Update()\n\n  // Bad - never use g.Map for database operations\n  dao.Users.Ctx(ctx).Data(g.Map{cols.Uid: uid}).Update()\n  ```\n## Code Style Standards\n- **Variable Declarations**: When defining multiple variables, use a `var` block to group them for better alignment and readability:\n  ```go\n  // Good - aligned and clean\n  var (\n      authSvc       *auth.Service\n      bizCtxSvc     *bizctx.Service\n      k8sSvc        *svcK8s.Service\n      notebookSvc   *notebook.Service\n      middlewareSvc *middleware.Service\n  )\n\n  // Avoid - scattered declarations\n  authSvc := auth.New()\n  bizCtxSvc := bizctx.New()\n  k8sSvc := svcK8s.New()\n  ```\n- Apply this pattern when you have 3 or more related variable declarations in the same scope.\n\n## Soft Delete & Time Maintenance\n\nGoFrame 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.\n\n### Automatic Time Fields\n\n| Field | Auto Behavior |\n|-------|---------------|\n| `created_at` | Auto-written on `Insert/InsertAndGetId`, never modified afterward |\n| `updated_at` | Auto-written on `Insert/Update/Save` |\n| `deleted_at` | Auto-written on `Delete` (soft delete), auto-filtered on queries |\n\n### Critical Rules\n\n**1. NEVER manually set time fields** - GoFrame handles these automatically:\n```go\n// WRONG - redundant manual time setting\ndao.User.Ctx(ctx).Data(do.User{\n    Name:      \"john\",\n    CreatedAt: gtime.Now(),  // REDUNDANT! Framework handles this\n    UpdatedAt: gtime.Now(),  // REDUNDANT! Framework handles this\n}).Insert()\n\n// CORRECT - let framework handle time fields\ndao.User.Ctx(ctx).Data(do.User{\n    Name: \"john\",\n}).Insert()\n```\n\n**2. NEVER manually add `WhereNull(cols.DeletedAt)`** - GoFrame auto-adds soft delete filter:\n```go\n// WRONG - redundant soft delete condition\ndao.User.Ctx(ctx).\n    Where(do.User{Status: 1}).\n    WhereNull(cols.DeletedAt).  // REDUNDANT! Framework auto-adds this\n    Scan(&list)\n\n// CORRECT - framework auto-adds deleted_at IS NULL\ndao.User.Ctx(ctx).\n    Where(do.User{Status: 1}).\n    Scan(&list)\n```\n\n**3. Use `Delete()` for soft delete** - Framework converts to `UPDATE SET deleted_at = NOW()`:\n```go\n// CORRECT - use Delete(), framework handles soft delete\ndao.User.Ctx(ctx).Where(do.User{Id: id}).Delete()\n// Actual SQL: UPDATE `sys_user` SET `deleted_at`=NOW() WHERE `id`=?\n\n// WRONG - manual Update with deleted_at\ndao.User.Ctx(ctx).\n    Where(do.User{Id: id}).\n    Data(do.User{DeletedAt: gtime.Now()}).  // REDUNDANT!\n    Update()\n```\n\n### Field Type Support\n\nThe `deleted_at` field supports multiple types:\n- **DateTime/Timestamp**: Default, stores deletion time\n- **Integer**: Stores Unix timestamp (seconds)\n- **Boolean**: Stores 0/1 for deleted state\n\n### Configuration (Optional)\n\nTime field names can be customized in `config.yaml`:\n```yaml\ndatabase:\n  default:\n    createdAt: \"created_at\"   # Custom field name\n    updatedAt: \"updated_at\"\n    deletedAt: \"deleted_at\"\n    timeMaintainDisabled: false  # Set true to disable this feature\n```\n\n# GoFrame Documentation\nComplete GoFrame development resources covering component design, usage, best practices, and considerations: [GoFrame Documentation](./references/README.MD)\n\n# GoFrame Code Examples\nRich practical code examples covering HTTP services, gRPC services, and various project types: [GoFrame Examples](./examples/README.MD)","tags":["goframe","skills","gogf","agent","agent-skills"],"capabilities":["skill","source-gogf","skill-goframe-v2","topic-agent","topic-agent-skills","topic-goframe"],"categories":["skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/gogf/skills/goframe-v2","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add gogf/skills","source_repo":"https://github.com/gogf/skills","install_from":"skills.sh"}},"qualityScore":"0.478","qualityRationale":"deterministic score 0.48 from registry signals: · indexed on github topic:agent-skills · 56 github stars · SKILL.md body (5,227 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-23T06:56:00.952Z","embedding":null,"createdAt":"2026-04-18T20:31:47.483Z","updatedAt":"2026-04-23T06:56:00.952Z","lastSeenAt":"2026-04-23T06:56:00.952Z","tsv":"'/examples/practices/user-grpc-service':116 '/examples/practices/user-http-service':107 '/examples/readme.md':657 '/references':49 '/references/readme.md':638 '0/1':585 '1':405,477,502 '2':453 '3':326,505 'actual':534 'add':456,462,484,492 'afterward':381 'align':292,297 'alreadi':129 'api':15 'appli':320 'auth.new':315 'auth.service':302 'authsvc':301,314 'auto':58,370,375,385,392,399,461,483,491 'auto-add':460,482,490 'auto-filt':398 'auto-gener':57 'auto-written':374,384,391 'automat':192,342,365,366,414 'avoid':311 'bad':260 'behavior':371 'best':101,110,163,632 'better':291 'bizctx.new':317 'bizctx.service':304 'bizctxsvc':303,316 'block':286 'boolean':583 'built':158 'built-in':157 'busi':85,88 'check':126 'clean':299 'cli':36 'code':60,165,274,640,644 'cols.deletedat':458,479 'cols.id':205,235,252 'cols.uid':271 'column':244 'complet':31,96,146,624 'compon':117,139,154,160,629 'condit':213,471 'config.yaml':598 'configur':589 'consider':635 'contain':352 'convent':26,74 'convert':512 'correct':440,488,520 'cover':628,646 'creat':14,42,69,121,353,372,603 'createdat':427,602 'creation':47 'critic':25,403 'ctx':203,233,250,268,422,447,473,498,528,552 'custom':596,605 'dao':62 'dao.instances.ctx':249 'dao.user.ctx':421,446,472,497,527,551 'dao.users.ctx':202,232,267 'data':207,221,237,238,254,269,423,448,557 'data.isadmin':230 'data.passwordhash':225 'databas':17,168,265,600 'datetime/timestamp':573 'declar':278,313,331 'default':574,601 'defin':280 'delet':337,344,358,389,395,397,464,470,493,507,510,516,522,526,533,540,549,567,576,587,612 'deletedat':559,611 'design':630 'detail':56 'develop':5,28,626 'direct':90 'directori':83,94 'disabl':619 'do.instance':255 'do.user':208,222,424,449,475,500,530,554,558 'document':623,637 'elsewher':131 'ensur':145 'entiti':64 'error':142 'exampl':98,167,641,645,656 'exist':130,134 'explicit':76,241 'explor':152 'fals':615 'featur':348,621 'field':183,187,214,216,360,368,369,410,445,563,569,592,606 'file':11,61 'filter':400,465 'framework':430,436,442,481,489,511,523 'frontend/shell':23 'g.map':176,263,270 'gdb.raw':248,257 'generat':59 'gerror':138 'gf':39 'go':10,197,295,415,466,519 'gofram':2,4,35,73,156,340,411,459,622,625,636,639,655 'goframe-v2':1 'good':198,212,240,296 'group':288 'grpc':108,114,649 'gtime.now':428,434,560 'handl':143,363,412,431,437,443,524 'hash':226 'http':99,105,647 'http/microservices':33 'id':206,236,253,531,532,544,555,556 'idlesinc':256 'ignor':193,220 'implement':12,87,135 'init':40,48,53 'insert':439,452 'insert/insertandgetid':378 'insert/update/save':388 'instal':34 'integ':578 'interfac':180,185 'internal/model/do':174 'isadmin':228,231 'john':426,451 'k8ssvc':305,318 'let':441 'list':487,504 'logic':82,86,89 'mainten':339,347 'manual':68,407,418,455,546 'map':178 'md':54 'method':123 'middleware.service':310 'middlewaresvc':309 'modifi':71,380 'multipl':281,571 'must':65,170 'name':425,450,593,607 'never':175,261,379,406,454 'new':122,153 'nil':189,218,229 'notebook.service':308 'notebooksvc':307 'null':246,258,496 'object':173,201 'oper':18,169,266 'option':590 'orm':196,362 'password':224 'pattern':322 'per':72 'practic':102,111,164,633,643 'priorit':155 'project':27,32,43,46,97,653 'provid':341 'queri':402 'readabl':294 'redund':417,429,435,468,480,561 'refer':95,162 'relat':329 'remain':188 'request':77 'resourc':627 'reus':133 'rich':642 'rule':404 'scaffold':44 'scan':486,503 'scatter':312 'scope':335 'script':24 'second':582 'see':45 'servic':13,93,100,106,109,115,648,650 'set':242,408,420,515,539,616 'skill':6 'skill-goframe-v2' 'soft':336,343,396,463,469,509,525 'source-gogf' 'sql':535 'stack':147 'standard':29,119,276 'state':588 'status':476,501 'store':575,579,584 'string':179 'struct':182 'style':275 'support':565,570 'svck8s.new':319 'svck8s.service':306 'sys':537 'tabl':351 'time':338,346,367,409,419,444,577,591 'timemaintaindis':614 'timestamp':581 'topic-agent' 'topic-agent-skills' 'topic-goframe' 'trace':148 'traceabl':150 'trigger':7,21 'true':617 'type':564,572,654 'uid':209,210,272 'unix':580 'unless':75 'unset':186,215 'updat':211,239,259,273,355,382,514,536,547,562,609 'updatedat':433,608 'usag':118,631 'use':38,80,136,171,199,247,262,283,506,521 'user':104,113,538 'user-grpc-servic':112 'user-http-servic':103 'v2':3 'var':285,300 'variabl':125,277,282,330 'various':652 'wherenul':457,478 'writing/modifying':9 'written':376,386,393 'wrong':416,467,545 'yaml':599 '开发工具':50 '项目创建':52 '项目创建-init':51","prices":[{"id":"32ab26e6-a345-4fc8-91ee-b5d7d8b461a0","listingId":"c2620631-6f1a-4538-affe-f7a9cae75b30","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"gogf","category":"skills","install_from":"skills.sh"},"createdAt":"2026-04-18T20:31:47.483Z"}],"sources":[{"listingId":"c2620631-6f1a-4538-affe-f7a9cae75b30","source":"github","sourceId":"gogf/skills/goframe-v2","sourceUrl":"https://github.com/gogf/skills/tree/main/skills/goframe-v2","isPrimary":false,"firstSeenAt":"2026-04-18T22:14:54.758Z","lastSeenAt":"2026-04-23T06:56:00.952Z"},{"listingId":"c2620631-6f1a-4538-affe-f7a9cae75b30","source":"skills_sh","sourceId":"gogf/skills/goframe-v2","sourceUrl":"https://skills.sh/gogf/skills/goframe-v2","isPrimary":true,"firstSeenAt":"2026-04-18T20:31:47.483Z","lastSeenAt":"2026-04-23T06:40:29.977Z"}],"details":{"listingId":"c2620631-6f1a-4538-affe-f7a9cae75b30","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"gogf","slug":"goframe-v2","github":{"repo":"gogf/skills","stars":56,"topics":["agent","agent-skills","ai","goframe"],"license":null,"html_url":"https://github.com/gogf/skills","pushed_at":"2026-03-26T11:41:10Z","description":"GoFrame Agent Skills empowering AI to deeply understand GoFrame conventions and best practices, generating high-quality, production-ready code.","skill_md_sha":"535e958c8c8b4b2c0377877781396d2d96e2f4f1","skill_md_path":"skills/goframe-v2/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/gogf/skills/tree/main/skills/goframe-v2"},"layout":"multi","source":"github","category":"skills","frontmatter":{"name":"goframe-v2","license":"Apache-2.0","description":"GoFrame development skill. TRIGGER when writing/modifying Go files, implementing services, creating APIs, or database operations. DO NOT TRIGGER for frontend/shell scripts."},"skills_sh_url":"https://skills.sh/gogf/skills/goframe-v2"},"updatedAt":"2026-04-23T06:56:00.952Z"}}