All skills
gogf avatar

/goframe-v2

@911705d
by GoFramegogf/skills81 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.

Use this Skill: https://skilld.dev/gh/gogf/skills/goframe-v2

This session only. Nothing lands on disk.

referencesWEB服务开发路由管理路由管理-路由注册路由注册-规范路由规范路由-如何使用.md

路由方法定义

从上面的例子中,我们可以看到,路由方法定义使用固定的格式:

func Handler(ctx context.Context, req *Request) (res *Response, err error)

其中输入参数和输出参数都是两个,并且都是必须的一个都不能少。简单介绍下:

参数 说明 注意事项
ctx context.Context 上下文 Server 组件会自动从请求中获取并传递给接口方法
req *Request 请求对象 就算没有接收参数也要定义,因为请求结构体中不仅仅包含请求参数的定义,也包含了接口的请求定义。
res *Response 返回对象 就算没有返回参数也要定义,因为返回结构体中不仅仅包含返回参数的定义,也可以包含接口返回定义。
err error 错误对象 Server 通过该参数判断接口执行成功或失败。

路由统一注册

Group.Bind 方法

我们推荐使用对象化的方式来管理所有路由方法,并通过 分组路由 的 Bind 方法执行统一注册。需要注意的是,在规范化路由方式下,路由地址以及请求方式将由请求结构体在 g.Meta 元数据对象中通过标签定义,通过分组路由可以定义分组下的所有路由前缀。

BindHandler 方法

我们也可以通过基础的 BindHandler 方法来注册规范路由,但是该方法只能注册一个路由函数。使用示例:

s := g.Server()
s.BindHandler("/user/{uid}", func(ctx context.Context, req *SaveReq) (res *SaveRes, err error) {
    // ...
})

规范参数结构

在规范化路由注册中,非常重要的是请求/返回参数结构体的定义,在该结构体不仅仅包含了输入参数的定义,也包含了接口的定义,特别是路由地址、请求方法、接口描述等信息。通过结构体方式的数据结构参数维护,更有利于更丰富的接口能力扩展、团队间的接口交互、长期的接口维护、自动化的接口文档生成。

为保证命名规范化,输入数据结构以XxxReq方式命名,输出数据结构以XxxRes方式命名。即便输入或者输出参数为空,也需要定义相应的数据结构,这样的目的一个是便于后续扩展,另一个是便于接口信息的管理。关于结构体中涉及到 OpenAPIv3 协议的标签介绍请查看后续章节。 :::tip 请求参数自动转换到请求数据结构,字段映射转换不区分大小写,也会自动忽略特殊字符。 :::

输入数据校验

请求结构体在进入 API 接口执行前将会被自动执行校验,如果其中一条规则校验失败,那么将终止后续规则的校验(自动使用了 bail 校验修饰规则)。校验功能使用的是框架统一的校验组件,具体请参考: 数据校验 :::warning 需要特别注意:如果参数校验存在多条校验规则,并且规则中存在 required* 规则时,那么建议将 required* 校验规则放置于所有规则之前,否则规范路由中内置启用的 bail 校验规则的特性(校验失败即停止后续校验)有可能会引起后续规则的 required* 规则不生效。 :::

统一返回中间件

接口的数据返回处理需要设置 统一的后置中间件,当然也可以使用 Server 默认提供的数据返回中间件。开发者自定义中间件时可以参考 Server 默认提供的中间件 MiddlewareHandlerResponse。

这里顺便提一下,在自定义返回中间件时一个重要的方法:

// GetHandlerResponse retrieves and returns the handler response object and its error.
func (r *Request) GetHandlerResponse() interface{}

通过后置中间件执行时通过请求对象的 GetHandlerResponse 方法获取当前业务执行的结果,并根据需要做相应处理。

扩展介绍

OpenAPIv3 协议

Server 组件自动生成的接口文档使用的是最新的 OpenAPIv3 协议。更多介绍请参考章节: 接口文档

Ctx 中的 Request 对象

我们可以通过 RequestFromCtx/g.RequestFromCtx 方法从 ctx 中获取 Request 对象。

方法定义:

func RequestFromCtx(ctx context.Context) *Request

使用示例:

func (c *cHello) Hello(ctx context.Context, req *apiv1.HelloReq) (res *apiv1.HelloRes, err error) {
    g.RequestFromCtx(ctx).Response.Writeln("Hello World!")
    return
}

Source: SKILL.md on GitHub

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

Signed by skilld at 911705d. 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
  • Go
  • Database
  • goframe
  • orm
  • http
  • grpc
  • microservices
  • crud
  • scaffolding
  • middleware

README badge

README badge for gogf/skills

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.

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.