/goframe-v2

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
1 alert

Ask your Agent

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

This session only. Nothing lands on disk.

referencesWEB服务开发异常处理.md

12.5 KB raw

≈3.2k tokens on demand. Your agent reads this file only when SKILL.md points to it.

由于这个问题问得比较多，因此专门为大家撰写了这一章节。

基本介绍

目前大多数 Golang 的第三方 WebServer 库均没有默认对 HTTP 请求处理过程中产生的异常进行捕获，轻者错误产生后无法记录到日志造成排查错困难，重则异常造成进程直接崩溃，服务不可用。

当你选择 goframe，你很幸运。作为一款企业级的基础开发框架，默认情况下，执行过程中产生的 panic 是有被 Server 自动捕获的，产生 panic 时当前执行流程会立即中止，但是绝对不会影响进程直接崩溃。

获取异常错误

HTTP 执行流程中产生 panic 异常时，默认处理是记录到 Server 的日志文件中。当然，开发者也可以通过注册中间件方式手动捕获，然后自定义相关的错误处理。这一操作其实在中间件章节的示例中也有介绍，我们这里来再仔细说明下。

使用示例

我们这里使用一个全局的后置中间件来捕获异常，当异常产生后，捕获并写入到指定的日志文件中，返回固定友好的提示信息，避免敏感的报错信息暴露给调用端。 :::tip 需要注意的是：

即使开发者有自己捕获记录异常错误的日志，但是 Server 依旧会打印到 Server 自己的错误日志文件中。由开发者调用日志接口方法输出的日志属于业务日志（与业务相关），而 Server 自行管理的日志属于服务日志（类似于 nginx 的 error.log）。
由于 goframe 框架大部分的底层错误都包含有错误时的堆栈信息，如果对于 error 的具体堆栈信息感兴趣（具体调用链、报错文件路径、源码行号等），可以使用 gerror 来获取，具体请参考错误处理-堆栈特性章节。如果异常包含堆栈信息，默认情况下会打印到 Server 的 error 日志文件中。 :::

package main

import (
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/net/ghttp"
)

func MiddlewareErrorHandler(r *ghttp.Request) {
    r.Middleware.Next()
    if err := r.GetError(); err != nil {
        // 记录到自定义错误日志文件
        g.Log("exception").Error(err)
        //返回固定的友好信息
        r.Response.ClearBuffer()
        r.Response.Writeln("服务器居然开小差了，请稍后再试吧！")
    }
}

func main() {
    s := g.Server()
    s.Use(MiddlewareErrorHandler)
    s.Group("/api.v2", func(group *ghttp.RouterGroup) {
        group.ALL("/user/list", func(r *ghttp.Request) {
            panic("db error: sql is xxxxxxx")
        })
    })
    s.SetPort(8199)
    s.Run()
}

执行后，我们通过 curl 工具来试试吧：

$ curl -v "http://127.0.0.1:8199/api.v2/user/list"
> GET /api.v2/user/list HTTP/1.1
> Host: 127.0.0.1:8199
> User-Agent: curl/7.61.1
> Accept: */*
>
< HTTP/1.1 500 Internal Server Error
< Server: GoFrame HTTP Server
< Date: Sun, 19 Jul 2020 07:44:30 GMT
< Content-Length: 52
< Content-Type: text/plain; charset=utf-8
<
服务器居然开小差了，请稍后再试吧！

获取异常堆栈

异常堆栈信息

WebServer 本身在捕获异常时，如果抛出的异常信息并不包含堆栈内容，那么 WebServer 会自动获取抛出异常位点（即 panic 的位置）的堆栈并创建一个新的包含该堆栈信息的错误对象。我们来看一个示例。

package main

import (
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/net/ghttp"
)

func MiddlewareErrorHandler(r *ghttp.Request) {
    r.Middleware.Next()
    if err := r.GetError(); err != nil {
        r.Response.ClearBuffer()
        r.Response.Writef("%+v", err)
    }
}

func main() {
    s := g.Server()
    s.Use(MiddlewareErrorHandler)
    s.Group("/api.v2", func(group *ghttp.RouterGroup) {
        group.ALL("/user/list", func(r *ghttp.Request) {
            panic("db error: sql is xxxxxxx")
        })
    })
    s.SetPort(8199)
    s.Run()
}

可以看到，我们通过 %+v 的格式化打印来获取异常错误中的堆栈信息，具体原理请参考章节：错误处理-堆栈特性。执行后，我们通过 curl 工具来测试下：

$ curl "http://127.0.0.1:8199/api.v2/user/list"
db error: sql is xxxxxxx
1. db error: sql is xxxxxxx
   1).  main.main.func1.1
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/.example/other/test.go:25
   2).  github.com/gogf/gf/v2/net/ghttp.(*middleware).Next.func1.8
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:111
   3).  github.com/gogf/gf/v2/net/ghttp.niceCallFunc
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_func.go:46
   4).  github.com/gogf/gf/v2/net/ghttp.(*middleware).Next.func1
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:110
   5).  github.com/gogf/gf/v2/util/gutil.TryCatch
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/util/gutil/gutil.go:46
   6).  github.com/gogf/gf/v2/net/ghttp.(*middleware).Next
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:47
   7).  main.MiddlewareErrorHandler
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/.example/other/test.go:10
   8).  github.com/gogf/gf/v2/net/ghttp.(*middleware).Next.func1.9
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:117
   9).  github.com/gogf/gf/v2/net/ghttp.niceCallFunc
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_func.go:46
   10). github.com/gogf/gf/v2/net/ghttp.(*middleware).Next.func1
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:116
   11). github.com/gogf/gf/v2/util/gutil.TryCatch
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/util/gutil/gutil.go:46
   12). github.com/gogf/gf/v2/net/ghttp.(*middleware).Next
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:47
   13). github.com/gogf/gf/v2/net/ghttp.(*Server).ServeHTTP
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_server_handler.go:122

错误堆栈信息

如果抛出的异常是一个通过 gerror 组件的错误对象，或者实现堆栈打印接口的错误对象，由于该异常的错误对象已经包含了详细的堆栈信息，那么 WebServer 将会直接返回该错误对象，不会自动创建错误对象。我们来看一个示例。

package main

import (
    "github.com/gogf/gf/v2/errors/gerror"
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/net/ghttp"
)

func MiddlewareErrorHandler(r *ghttp.Request) {
    r.Middleware.Next()
    if err := r.GetError(); err != nil {
        r.Response.ClearBuffer()
        r.Response.Writef("%+v", err)
    }
}

func DbOperation() error {
    // ...
    return gerror.New("DbOperation error: sql is xxxxxxx")
}

func UpdateData() {
    err := DbOperation()
    if err != nil {
        panic(gerror.Wrap(err, "UpdateData error"))
    }
}

func main() {
    s := g.Server()
    s.Use(MiddlewareErrorHandler)
    s.Group("/api.v2", func(group *ghttp.RouterGroup) {
        group.ALL("/user/list", func(r *ghttp.Request) {
            UpdateData()
        })
    })
    s.SetPort(8199)
    s.Run()
}

执行后，我们通过 curl 工具来测试下：

$ curl "http://127.0.0.1:8199/api.v2/user/list"
UpdateData error: DbOperation error: sql is xxxxxxx
1. UpdateData error
   1).  main.UpdateData
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/.example/other/test.go:25
   2).  main.main.func1.1
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/.example/other/test.go:34
   3).  github.com/gogf/gf/v2/net/ghttp.(*middleware).Next.func1.8
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:111
   4).  github.com/gogf/gf/v2/net/ghttp.niceCallFunc
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_func.go:46
   5).  github.com/gogf/gf/v2/net/ghttp.(*middleware).Next.func1
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:110
   6).  github.com/gogf/gf/v2/util/gutil.TryCatch
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/util/gutil/gutil.go:46
   7).  github.com/gogf/gf/v2/net/ghttp.(*middleware).Next
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:47
   8).  main.MiddlewareErrorHandler
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/.example/other/test.go:10
   9).  github.com/gogf/gf/v2/net/ghttp.(*middleware).Next.func1.9
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:117
   10). github.com/gogf/gf/v2/net/ghttp.niceCallFunc
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_func.go:46
   11). github.com/gogf/gf/v2/net/ghttp.(*middleware).Next.func1
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:116
   12). github.com/gogf/gf/v2/util/gutil.TryCatch
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/util/gutil/gutil.go:46
   13). github.com/gogf/gf/v2/net/ghttp.(*middleware).Next
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:47
   14). github.com/gogf/gf/v2/net/ghttp.(*Server).ServeHTTP
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_server_handler.go:122
2. DbOperation error: sql is xxxxxxx
   1).  main.DbOperation
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/.example/other/test.go:19
   2).  main.UpdateData
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/.example/other/test.go:23
   3).  main.main.func1.1
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/.example/other/test.go:34
   4).  github.com/gogf/gf/v2/net/ghttp.(*middleware).Next.func1.8
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:111
   5).  github.com/gogf/gf/v2/net/ghttp.niceCallFunc
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_func.go:46
   6).  github.com/gogf/gf/v2/net/ghttp.(*middleware).Next.func1
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:110
   7).  github.com/gogf/gf/v2/util/gutil.TryCatch
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/util/gutil/gutil.go:46
   8).  github.com/gogf/gf/v2/net/ghttp.(*middleware).Next
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:47
   9).  main.MiddlewareErrorHandler
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/.example/other/test.go:10
   10). github.com/gogf/gf/v2/net/ghttp.(*middleware).Next.func1.9
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:117
   11). github.com/gogf/gf/v2/net/ghttp.niceCallFunc
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_func.go:46
   12). github.com/gogf/gf/v2/net/ghttp.(*middleware).Next.func1
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:116
   13). github.com/gogf/gf/v2/util/gutil.TryCatch
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/util/gutil/gutil.go:46
   14). github.com/gogf/gf/v2/net/ghttp.(*middleware).Next
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_request_middleware.go:47
   15). github.com/gogf/gf/v2/net/ghttp.(*Server).ServeHTTP
        /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/net/ghttp/ghttp_server_handler.go:122

Source: SKILL.md on GitHub

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. 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
Database
goframe
orm
http
grpc
microservices
crud
scaffolding
middleware

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.