WEB Service Development - Exception Handling - 《GoFrame v2.8 Documentation》

Introduction
Retrieving Exception Errors
- Relevant Methods
- Usage Example
Retrieving Exception Stacks
- Exception Stack Information
- Error Stack Information

As this question is frequently asked, here is a dedicated section for you.

Introduction

Most third-party WebServer libraries for Golang do not have default mechanisms to capture exceptions arising during the HTTP request handling process. Minor errors may not be recorded in logs, leading to difficulty in troubleshooting, while severe exceptions can cause the process to crash, rendering the service unavailable.

If you choose goframe, you are in luck. As an enterprise-level foundational development framework, panic incidents occurring during execution are automatically captured by the Server by default. When a panic occurs, the current execution flow is immediately halted, but it will never cause a direct process crash.

Retrieving Exception Errors

When a panic occurs during the HTTP execution process, it is logged to the Server log file by default. Developers can also manually capture it by registering middleware and customize related error handling. This operation is also explained in the examples of the middleware section, and we will elaborate on it here.

Relevant Methods

Exceptions are captured using the GetError method in the Request object.

tip

Developers cannot capture exceptions using the recover method because the Server in the goframe framework has already done so. To ensure exceptions do not crash the process by default, they are not re-thrown upwards.

// GetError returns the error that occurs during the request procedure.
// It returns nil if there's no error.
func (r *Request) GetError() error

This method is often used in flow control components, such as post-middleware or HOOK hook methods.

Usage Example

Here, we use a global post-middleware to capture exceptions. When an exception occurs, it is captured and written to a designated log file, and a fixed friendly message is returned to avoid exposing sensitive error information to the client.

tip

Please note:

Even if developers capture and log exceptions themselves, the Server will still print them to its own error log file. Logs outputted by API methods are business logs (related to the business), while self-managed logs by the Server are service logs (similar to nginx‘s error.log).
Since most low-level errors in the goframe framework include stack information of the error, if you are interested in specific stack information (call chain, error file path, source code line number, etc.), you can use gerror to retrieve it. For details, please refer to the section Error Handling - Stack. If the exception includes stack information, it is printed by default to the Server‘s error log file.

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 {
        // Log to a custom error log file
        g.Log("exception").Error(err)
        // Return a fixed friendly message
        r.Response.ClearBuffer()
        r.Response.Writeln("The server is having a hiccup. Please try again later!")
    }
}
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()
}

After execution, let’s give it a try with the curl tool:

$ 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
<
The server is having a hiccup. Please try again later!

Retrieving Exception Stacks

Exception Stack Information

When the WebServer itself captures an exception, if the thrown exception information does not include stack content, the WebServer will automatically capture the stack of the point where the exception occurred (the panic location) and create a new error object containing that stack information. Let’s look at an example.

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()
}

You can see that we use the %+v formatted print to retrieve the stack information from the exception error; for the specific principle, please refer to the chapter: Error Handling - Stack. After execution, we will test it with the curl tool:

$ 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

Error Stack Information

If the thrown exception is an error object created via the gerror component, or an error object implementing the stack print API, since the error object already contains complete stack information, the WebServer will directly return that error object and not automatically create a new error object. Let’s look at an example.

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()
}

After execution, we will test it with the curl tool:

$ 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