AI 助理
备案控制台
开发者社区 开发与运维 文章 正文

如何规范 RESTful API 的业务错误处理

2023-06-12 1338
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
本文涉及的产品
日志服务 SLS，月写入数据量 50GB 1个月
简介： 如何规范 RESTful API 的业务错误处理

现如今，主流的 Web API 都采用 RESTful 设计风格，对于接口返回的 HTTP 状态码和响应内容都有统一的规范。针对接口错误响应，一般都会返回一个 Code（错误码）和 Message（错误消息内容），通常错误码 Code 用来定位一个唯一的错误，错误消息 Message 用来展示错误信息。

本文就来详细介绍下，如何将 RESTful API 的错误处理进行规范化。

错误码

为什么需要业务错误码

虽然 RESTful API 能够通过 HTTP 状态码来标记一个请求的成功或失败，但 HTTP 状态码作为一个通用的标准，并不能很好的表达业务错误。

比如一个 500 的错误响应，可能是由后端数据库连接异常引起的、也可能由内部代码逻辑错误引起，这些都无法通过 HTTP 状态码感知到，如果程序出现错误，不方便开发人员 Debug。

因此我们有必要设计一套用来标识业务错误的错误码，这有别于 HTTP 状态码，是跟系统具体业务息息相关的。

错误码功能

在设计错误码之前，我们需要明确下错误码应该具备哪些属性，以满足业务需要。

  • 错误码必须是唯一的。只有错误码是唯一的才方便在程序出错时快速定位问题，不然程序出错，返回错误码不唯一，想要根据错误码排查问题，就要针对这一错误码所表示的错误列表进行逐一排查。
  • 错误码需要是可阅读的。意思是说，通过错误码，我们就能快速定位到是系统的哪个组件出现了错误，并且知道错误的类型，不然也谈不上叫「业务错误码」了。一个清晰可读的错误码在微服务系统中定位问题尤其有效。
  • 通过错误码能够方便知道 HTTP 状态码。这一点往往容易被人忽略，不过我比较推荐这种做法，因为在 Review 代码时，通过返回错误码，就能很容易知道接口返回 HTTP 状态码，这不仅方便理解代码，更方便错误的统一处理。

错误码设计

错误码调研

错误码的设计我们可以参考业内使用量比较大的开放 API 设计，比较有代表性的是阿里云和新浪网的开放 API。

如以下是一个阿里云 ECS 接口错误的返回：

1
2
3
4
5
6
7
 
{
"RequestId": "5E571499-13C5-55E3-9EA6-DEFA0DBC85E4",
"HostId": "ecs-cn-hangzhou.aliyuncs.com",
"Code": "InvalidOperation.NotSupportedEndpoint",
"Message": "The specified endpoint can't operate this region. Please use API DescribeRegions to get the appropriate endpoint, or upgrade your SDK to latest version.",
"Recommend": "https://next.api.aliyun.com/troubleshoot?q=InvalidOperation.NotSupportedEndpoint&product=Ecs"
}

可以发现，Code 和 Message 都为字符串类型，并且还有 RequestId（当前请求唯一标识）、HostId（Host 唯一标识）、Recommend（错误诊断地址），可以说这个错误信息非常全面了。

再来看下新浪网开放 API 错误返回结果的设计：

1
2
3
4
5
 
{
"request": "/statuses/home_timeline.json",
"error_code": "20502",
"error": "Need you follow uid."
}

相比阿里云，新浪网的错误返回更简洁一些。其中 request 为请求路径，error_code 即为错误码 Code，error 则表示错误信息 Message。

错误代码 20502 说明如下：

2 05 02
服务级错误（1为系统级错误） 服务模块代码 具体错误代码

新浪网的错误码为数字类型的字符串，相比阿里云的错误码要简短不少，并且对程序更加友好，也是我个人更推荐的设计。

业务错误码

结合市面上这些优秀的开放 API 错误码设计，以及我在实际开发中的工作总结，我设计的错误码规则如下：

  • 业务错误码由 8 位纯数字组成，类型为 int。
  • 业务错误码示例格式：40001002。
  • 错误码说明：
1-3 位 4-5 位 6-8 位
400 01 002
HTTP 状态码 组件编号 组件内部错误码

错误码设计为纯数字主要是为了程序中使用起来更加方便，比如根据错误码计算 HTTP 状态码，只需要通过简单的数学取模计算就能做到。

使用两位数字来标记不同组件，最多能表示 99 个组件，即使项目全部采用微服务开发，一般来说也是足够用的。

最后三位代表组件内部错误码，最多能表示 1000 个错误。其实通常来说一个组件内部是用不上这么多错误的，如果组件较小，完全可以设计成两位数字。

另外，有些厂商中还会设计一些公共的错误码，可以称为「全局错误码」，这些错误码在各组件间通用，以此来减少定义重复错误。在我们的错误码设计中，可以将组件编号为 00 的标记为全局错误码，其他组件编号从 01 开始。

错误格式

有了错误码，还需要定义错误响应格式，设计一个标准的 API 错误响应格式如下：

1
2
3
4
5
 
{
"code": 50000000,
"message": "系统错误",
"reference": "https://github.com/jianghushinian/gokit/tree/main/errors"
}

code 即为错误码，message 为错误信息，reference 则是错误文档地址，用来告知用户如何解决这个错误，对标的是阿里云错误响应中的 Recommend 字段。

错误码实现

因为每一个错误码和错误信息以及错误文档地址都是一一对应的，所以我们需要一个对象来保存这些信息，在 Go 中可以使用结构体。

可以设计如下结构体：

1
2
3
4
5
 
type apiCode struct {
	code int
	msg  string
	ref  string
}

这是一个私有结构体，外部项目要想使用，则需要一个构造函数：

1
2
3
4
5
6
7
8
9
10
11
 
funcNewAPICode(code int, message string, reference ...string)APICoder {
	ref := ""
iflen(reference) > 0 {
		ref = reference[0]
	}
return &apiCode{
		code: code,
		msg:  message,
		ref:  ref,
	}
}

其中 reference 被设计为可变参数，如果不传则默认为空。

NewAPICode 返回值 APICoder 是一个接口，这在 Go 中是一种惯用做法。通过接口可以解耦，方便依赖 apiCode 的代码编写测试，用户可以对 APICoder 进行 Mock；另一方面，我们稍后会为 apiCode 实现对应的错误包，使用接口来表示错误码可以方便用户定义自己的 apiCode 类型。

为了便于使用，apiCode 提供了如下几个能力：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
func(a *apiCode)Code()int {
return a.code
}
func(a *apiCode)Message()string {
return a.msg
}
func(a *apiCode)Reference()string {
return a.ref
}
func(a *apiCode)HTTPStatus()int {
	v := a.Code()
for v >= 1000 {
		v /= 10
	}
return v
}

至此 APICoder 接口接口的定义也就有了：

1
2
3
4
5
6
 
type APICoder interface {
	Code() int
	Message() string
	Reference() string
	HTTPStatus() int
}

apiCode 则实现了 APICoder 接口。

现在我们可以通过如下方式创建错误码结构体对象：

1
2
3
4
 
var (
	CodeBadRequest   = NewAPICode(40001001, "请求不合法")
	CodeUnknownError = NewAPICode(50001001, "系统错误", "https://github.com/jianghushinian/gokit/tree/main/errors")
)

错误包

设计好了错误码，并不能直接使用，我们还需要一个与之配套的错误包来简化错误码的使用。

错误包功能

  • 错误包要能够完美支持上面设计的错误码。所以需要使用 APICoder 来构造错误对象。
  • 错误包应该能够查看原始错误原因。这就需要实现 Unwrap 方法，Wrap/Unwrap 方法是在 Go 1.13 中被加入进 errors 包的，目的是能够处理嵌套错误。
  • 错误包应该能够支持对内对外展示不同信息。这就需要实现 Format 方法，根据需要可以将错误格式化成不同输出。
  • 错误包应该能够支持展示堆栈信息。这对 Debug 来说相当重要，也是 Go 自带的 errors 包不足的地方。
  • 为了方便在日志中记录结构化错误信息，错误包还要能够支持 JSON 序列化。这需要实现 MarshalJSON/UnmarshalJSON 两个方法。

错误包设计

一个错误对象结构体设计如下：

1
2
3
4
5
 
type apiError struct {
	coder APICoder
	cause error
	*stack
}

其中 coder 用来保存实现了 APICoder 接口的对象，cause 用来记录错误原因，stack 用来展示错误堆栈。

错误对象的构造函数如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
 
var WrapC = NewAPIError
funcNewAPIError(coder APICoder, cause ...error)error {
var c error
iflen(cause) > 0 {
		c = cause[0]
	}
return &apiError{
		coder: coder,
		cause: c,
		stack: callers(),
	}
}

NewAPIError 通过 APICoder 来创建错误对象，第二个参数为一个可选的错误原因。

其实构造一个错误对象也就是对一个错误进行 Wrap 的过程，所以我还为构造函数 NewAPIError 定义了一个别名 WrapC，表示使用错误码将一个错误包装成一个新的错误。

一个错误对象必须要实现 Error 方法：

1
2
3
 
func(a *apiError)Error()string {
return fmt.Sprintf("[%d] - %s", a.coder.Code(), a.coder.Message())
}

默认情况下，获取到的错误内容只包含错误码 Code 和错误信息 Message。

为了方便获取被包装错误的原始错误，还要实现 Unwrap 方法：

1
2
3
 
func(a *apiError)Unwrap()error {
return a.cause
}

为了能在打印或写入日志时展示不同信息，则要实现 Format 方法：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
 
func(a *apiError)Format(s fmt.State, verb rune) {
switch verb {
case'v':
if s.Flag('+') {
			str := a.Error()
if a.Unwrap() != nil {
				str += " " + a.Unwrap().Error()
			}
			_, _ = io.WriteString(s, str)
			a.stack.Format(s, verb)
return
		}
if s.Flag('#') {
			cause := ""
if a.Unwrap() != nil {
				cause = a.Unwrap().Error()
			}
			data, _ := json.Marshal(errorMessage{
				Code:      a.coder.Code(),
				Message:   a.coder.Message(),
				Reference: a.coder.Reference(),
				Cause:     cause,
				Stack:     fmt.Sprintf("%+v", a.stack),
			})
			_, _ = io.WriteString(s, string(data))
return
		}
fallthrough
case's':
		_, _ = io.WriteString(s, a.Error())
case'q':
		_, _ = fmt.Fprintf(s, "%q", a.Error())
	}
}

Format 方法能够支持在使用 fmt.Printf("%s", apiError) 格式化输出时打印定制化的信息。

Format 方法支持的不同格式输出如下：

格式占位符 输出信息
%s 错误码、错误信息
%v 错误码、错误信息，与 %s 等价
%+v 错误码、错误信息、错误原因、错误堆栈
%#v JSON 格式的 错误码、错误信息、错误文档地址、错误原因、错误堆栈
%q 在 错误码、错误信息 外层增加了一个双引号

这些错误格式基本上能满足所有业务开发中的需求了，如果还有其他格式需要，则可以在此基础上进一步开发 Format 方法。

用来进行 JSON 序列化和反序列化的 MarshalJSON/UnmarshalJSON 方法实现如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
func(a *apiError)MarshalJSON()([]byte, error) {
return json.Marshal(&errorMessage{
		Code:      a.coder.Code(),
		Message:   a.coder.Message(),
		Reference: a.coder.Reference(),
	})
}
func(a *apiError)UnmarshalJSON(data []byte)error {
	e := &errorMessage{}
if err := json.Unmarshal(data, e); err != nil {
return err
	}
	a.coder = NewAPICode(e.Code, e.Message, e.Reference)
returnnil
}
type errorMessage struct {
	Code      int`json:"code"`
	Message   string`json:"message"`
	Reference string`json:"reference,omitempty"`
	Cause     string`json:"cause,omitempty"`
	Stack     string`json:"stack,omitempty"`
}

为了不对外部暴露敏感信息，对外的 HTTP API 只会返回 Code、Message、Reference（可选）三个字段，对内需要额外展示错误原因以及错误堆栈。所以 errorMessage 中 Reference、Cause、Stack 字段都带有 omitempty 属性，这样在 MarshalJSON 时只会序列化 Code、Message、Reference 这三个字段。

至此，我们就实现了错误包的设计。

错误码及错误包的使用

使用示例

通过上面的讲解，我们了解了错误码和错误包的设计规范，接下来看看如何使用它们。这里以错误码及错误包在 Gin 中的使用为例进行讲解。

使用 Gin 构建一个简单的 Web Server 如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
package main
import (
"errors"
"fmt"
"strconv"
"github.com/gin-gonic/gin"
	apierr "github.com/jianghushinian/gokit/errors"
)
var (
	ErrAccountNotFound = errors.New("account not found")
	ErrDatabase        = errors.New("database error")
)
var (
	CodeBadRequest   = NewAPICode(40001001, "请求不合法")
	CodeNotFound     = NewAPICode(40401001, "资源未找到")
	CodeUnknownError = NewAPICode(50001001, "系统错误", "https://github.com/jianghushinian/gokit/tree/main/errors")
)
type Account struct {
	ID   int`json:"id"`
	Name string`json:"name"`
}
funcAccountOne(id int)(*Account, error) {
for _, v := range accounts {
if id == v.ID {
return &v, nil
		}
	}
// 模拟返回数据库错误
if id == 500 {
returnnil, ErrDatabase
	}
returnnil, ErrAccountNotFound
}
var accounts = []Account{
	{ID: 1, Name: "account_1"},
	{ID: 2, Name: "account_2"},
	{ID: 3, Name: "account_3"},
}
funcShowAccount(c *gin.Context) {
	id := c.Param("id")
	aid, err := strconv.Atoi(id)
if err != nil {
// 将 errors 包装成 APIError 返回
		ResponseError(c, apierr.WrapC(CodeBadRequest, err))
return
	}
	account, err := AccountOne(aid)
if err != nil {
switch {
case errors.Is(err, ErrAccountNotFound):
			err = apierr.NewAPIError(CodeNotFound, err)
case errors.Is(err, ErrDatabase):
			err = apierr.NewAPIError(CodeUnknownError, fmt.Errorf("account %d: %w", aid, err))
		}
		ResponseError(c, err)
return
	}
	ResponseOK(c, account)
}
funcmain() {
	r := gin.Default()
	r.GET("/accounts/:id", ShowAccount)
if err := r.Run(":8080"); err != nil {
panic(err)
	}
}

在这个 Web Server 中定义了一个 ShowAccount 函数，用来处理获取账号逻辑，在 ShowAccount 内部程序执行成功返回 ResponseOK(c, account)，失败则返回 ResponseError(c, err)。

在处理返回失败的响应时，都会通过 apierr.WrapC 或 apierr.NewAPIError 将底层函数返回的初始错误进行一层包装，根据错误级别，包装成不同的错误码进行返回。

其中 ResponseOK 和 ResponseError 定义如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
funcResponseOK(c *gin.Context, spec interface{}) {
if spec == nil {
		c.Status(http.StatusNoContent)
return
	}
	c.JSON(http.StatusOK, spec)
}
funcResponseError(c *gin.Context, err error) {
	log(err)
	e := apierr.ParseCoder(err)
	httpStatus := e.HTTPStatus()
if httpStatus >= 500 {
// send error msg to email/feishu/sentry...
go fakeSendErrorEmail(err)
	}
	c.AbortWithStatusJSON(httpStatus, err)
}
// log 打印错误日志，输出堆栈
funclog(err error) {
	fmt.Println("========== log start ==========")
	fmt.Printf("%+v\n", err)
	fmt.Println("========== log end ==========")
}
// fakeSendErrorEmail 模拟将错误信息发送到邮件，JSON 格式
funcfakeSendErrorEmail(err error) {
	fmt.Println("========== error start ==========")
	fmt.Printf("%#v\n", err)
	fmt.Println("========== error end ==========")
}

ResponseOK 其实就是 Gin 框架的正常返回，ResponseError 则专门用来处理并返回 API 错误。

在 ResponseError 中首先通过 log(err) 来记录错误日志，在其内部使用 fmt.Printf("%+v\n", err) 进行打印。

之后我们还对 HTTP 状态码进行了判断，大于 500 的错误将会发送邮件通知，这里使用 fmt.Printf("%#v\n", err) 进行模拟。

其中 apierr.ParseCoder(err) 能够从一个错误对象中获取到实现了 APICoder 的错误码对象，实现如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
 
funcParseCoder(err error)APICoder {
for {
if e, ok := err.(interface {
			Coder() APICoder
		}); ok {
return e.Coder()
		}
if errors.Unwrap(err) == nil {
return CodeUnknownError
		}
		err = errors.Unwrap(err)
	}
}

这样，我们就能够通过一个简单的 Web Server 示例程序来演示如何使用错误码和错误包了。

可以通过 go run main.go 启动这个 Web Server。

先来看下在这个 Web Server 中一个正常的返回结果是什么样，使用 cURL 来发送一个请求：curl http://localhost:8080/accounts/1。

客户端得到如下响应结果：

1
2
3
4
 
{
"id": 1,
"name": "account_1"
}

服务端打印正常的请求日志：

Server Log

再来测试下请求一个不存在的账号：curl http://localhost:8080/accounts/12。

客户端得到如下响应结果：

1
2
3
4
 
{
"code": 40401001,
"message": "资源未找到"
}

返回结果中没有 reference 字段，是因为对于 reference 为空的情况，在 JSON 序列化过程中会被隐藏。

服务端打印的错误日志如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
========== log start ==========
[40401001] - 资源未找到 account not found
main.ShowAccount
        /app/errors/examples/main.go:56
github.com/gin-gonic/gin.(*Context).Next
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/context.go:174
github.com/gin-gonic/gin.CustomRecoveryWithWriter.func1
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/recovery.go:102
github.com/gin-gonic/gin.(*Context).Next
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/context.go:174
github.com/gin-gonic/gin.LoggerWithConfig.func1
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/logger.go:240
github.com/gin-gonic/gin.(*Context).Next
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/context.go:174
github.com/gin-gonic/gin.(*Engine).handleHTTPRequest
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/gin.go:620
github.com/gin-gonic/gin.(*Engine).ServeHTTP
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/gin.go:576
net/http.serverHandler.ServeHTTP
        /usr/local/go/src/net/http/server.go:2947
net/http.(*conn).serve
        /usr/local/go/src/net/http/server.go:1991
runtime.goexit
        /usr/local/go/src/runtime/asm_arm64.s:1165
========== log end ==========

可以发现，错误日志中不仅打印了错误码（[40401001]）和错误信息（资源未找到），还打印了错误原因（account not found）以及下面的错误堆栈。

如此清晰的错误日志得益于我们实现的 Format 函数的强大功能。

现在再来触发一个 HTTP 状态码为 500 的错误响应：curl http://localhost:8080/accounts/500。

客户端得到如下响应结果：

1
2
3
4
5
 
{
"code": 50001001,
"message": "系统错误",
"reference": "https://github.com/jianghushinian/gokit/tree/main/errors"
}

这次得到一个带有 reference 字段的完整错误响应。

服务端打印的错误日志如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
 
========== log start ==========
[50001001] - 系统错误 account 500: database error
main.ShowAccount
        /app/errors/examples/main.go:58
github.com/gin-gonic/gin.(*Context).Next
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/context.go:174
github.com/gin-gonic/gin.CustomRecoveryWithWriter.func1
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/recovery.go:102
github.com/gin-gonic/gin.(*Context).Next
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/context.go:174
github.com/gin-gonic/gin.LoggerWithConfig.func1
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/logger.go:240
github.com/gin-gonic/gin.(*Context).Next
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/context.go:174
github.com/gin-gonic/gin.(*Engine).handleHTTPRequest
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/gin.go:620
github.com/gin-gonic/gin.(*Engine).ServeHTTP
        /go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/gin.go:576
net/http.serverHandler.ServeHTTP
        /usr/local/go/src/net/http/server.go:2947
net/http.(*conn).serve
        /usr/local/go/src/net/http/server.go:1991
runtime.goexit
        /usr/local/go/src/runtime/asm_arm64.s:1165
========== log end ==========
[GIN] 2023/03/05 - 02:02:28 | 500 |     426.292µs |       127.0.0.1 | GET      "/accounts/500"
========== error start ==========
{"code":50001001,"message":"系统错误","reference":"https://github.com/jianghushinian/gokit/tree/main/errors","cause":"account 500: database error","stack":"\nmain.ShowAccount\n\t/app/errors/examples/main.go:58\ngithub.com/gin-gonic/gin.(*Context).Next\n\t/go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/context.go:174\ngithub.com/gin-gonic/gin.CustomRecoveryWithWriter.func1\n\t/go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/recovery.go:102\ngithub.com/gin-gonic/gin.(*Context).Next\n\t/go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/context.go:174\ngithub.com/gin-gonic/gin.LoggerWithConfig.func1\n\t/go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/logger.go:240\ngithub.com/gin-gonic/gin.(*Context).Next\n\t/go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/context.go:174\ngithub.com/gin-gonic/gin.(*Engine).handleHTTPRequest\n\t/go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/gin.go:620\ngithub.com/gin-gonic/gin.(*Engine).ServeHTTP\n\t/go/pkg/mod/github.com/gin-gonic/gin@v1.9.0/gin.go:576\nnet/http.serverHandler.ServeHTTP\n\t/usr/local/go/src/net/http/server.go:2947\nnet/http.(*conn).serve\n\t/usr/local/go/src/net/http/server.go:1991\nruntime.goexit\n\t/usr/local/go/src/runtime/asm_arm64.s:1165"}
========== error end ==========

这一次除了 log 函数打印的日志，还能看到 fakeSendErrorEmail 函数打印的日志，正是一个 JSON 格式的结构化日志。

以上便是我们设计的错误码及错误包在实际开发场景中的应用。

使用建议

根据我的经验，总结了一些错误码及错误包的使用建议，现在将其分享给你。

使用尽量少的 HTTP 状态码

HTTP 状态码大概分为 5 大类，分别是 1XX、2XX、3XX、4XX、5XX。根据我的实际工作经验，我们并不会使用全部的状态码，最常用的状态码不超过 10 个。

所以即使我们设计的业务错误码支持携带 HTTP 状态码，但也不推荐使用过多的 HTTP 状态码，以免加重前端工作量。

推荐在错误码中使用的 HTTP 状态码如下：

  • 400: 请求不合法
  • 401: 认证失败
  • 403: 授权失败
  • 404: 资源未找到
  • 500: 系统错误

其中 4XX 代表客户端错误，而如果是服务端错误，则统一使用 500 状态码，具体错误原因可以通过业务错误码定位。

使用中间件来记录错误日志

由于我们设计的错误包支持 Unwrap 操作，所以建议出现错误时的处理流程如下：

  1. 最底层代码遇到错误时通过 errors.New/fmt.Errorf 来创建一个错误对象，然后将错误返回（可选择性的记录一条日志）。
1
2
3
4
 
funcQuery(id int)(obj, error) {
// do something
returnnil, fmt.Errorf("%d not found", id)
}
  1. 中间过程中处理函数遇到下层函数返回的错误，不做任何额外处理，直接将其向上层返回。
1
2
3
 
if err != nil {
return err
}
  1. 在处理用户请求的 Handler 函数中（如 ShowAccount）通过 apierr.WrapC 将错误包装成一个 APIError 返回。
1
2
3
 
if err != nil {
return apierr.WrapC(CodeNotFound, err)
}
  1. 最上层代码通过在框架层面实现的中间件（如实现一个 after hook middleware）来统一处理错误，打印完整错误日志、发送邮件提醒等，并将安全的错误信息返回给前端。如我们实现的 ResponseError 函数功能。

总结

本篇文章讲解了如何设计一个规范的错误码以及与之配套的错误包。

我参考了一些开源的 API 错误码设计方案，并结合我自己的实际工作经验，给出了我认为比较合理的错误码设计方案。

同时也针对这个错误码方案，设计了一个配套的错误包，来简化使用过程，并给出了我的一些使用建议。

错误包中记录错误堆栈部分的代码参考了 pkg/errors 包实现，感兴趣的同学可以点击进去进行进一步学习。

本文完整代码实现我放在了 Github 上，供你参考使用。

希望本文对你有所启发，如果你有更好的错误码设计方案，欢迎一起交流讨论。

参考

阿里云 ECS 错误码：https://next.api.aliyun.com/document/Ecs/2014-05-26/errorCode

腾讯云服务器错误码：https://cloud.tencent.com/document/api/213/30435

新浪错误码：https://open.weibo.com/wiki/Error_code

pkg/errors：https://github.com/pkg/errors

错误包实现：https://github.com/jianghushinian/gokit/tree/main/errors

文章标签：
云服务器 ECS
日志服务
Go
前端开发
微服务
弹性计算
安全
API
中间件
数据格式
JSON
数据库连接
关键词：
API规范
Restful API
API restful
规范API
规范Restful
相关实践学习
2分钟自动化部署人生模拟器
本场景将带你借助云效流水线Flow实现人生模拟器小游戏的自动化部署
7天玩转云服务器
云服务器ECS（Elastic Compute Service）是一种弹性可伸缩的计算服务，可降低 IT 成本，提升运维效率。本课程手把手带你了解ECS、掌握基本操作、动手实操快照管理、镜像管理等。了解产品详情: https://www.aliyun.com/product/ecs
江湖十年007
目录
相关文章
技术小达人
|
5天前
|
JSON Cloud Native API
API 规范和设计
今天主要和大家分享的是如何给予 Open API 3.0 标准来设计一套 API 规范。那么整体我们在讲的过程中，大约有以下五方面。 1. 大环境介绍 2. API与服务开放 3. API定义 4. 模型 5. 总结
技术小达人
38 5
请看我回答~
|
1月前
|
JSON JavaScript 前端开发
深入浅出Node.js：从零开始构建RESTful API
在数字化时代的浪潮中，后端开发作为连接用户与数据的桥梁，扮演着至关重要的角色。本文将引导您步入Node.js的奇妙世界，通过实践操作，掌握如何使用这一强大的JavaScript运行时环境构建高效、可扩展的RESTful API。我们将一同探索Express框架的使用，学习如何设计API端点，处理数据请求，并实现身份验证机制，最终部署我们的成果到云服务器上。无论您是初学者还是有一定基础的开发者，这篇文章都将为您打开一扇通往后端开发深层知识的大门。
请看我回答~
57 12
aliyun0641063962-48771
|
2月前
|
XML JSON 缓存
深入理解RESTful API设计原则与实践
在现代软件开发中，构建高效、可扩展的应用程序接口（API）是至关重要的。本文旨在探讨RESTful API的核心设计理念，包括其基于HTTP协议的特性，以及如何在实际应用中遵循这些原则来优化API设计。我们将通过具体示例和最佳实践，展示如何创建易于理解、维护且性能优良的RESTful服务，从而提升前后端分离架构下的开发效率和用户体验。
aliyun0641063962-48771
73 10
游客762btuqu5wybw666
|
2月前
|
JSON 缓存 测试技术
构建高效RESTful API的后端实践指南####
本文将深入探讨如何设计并实现一个高效、可扩展且易于维护的RESTful API。不同于传统的摘要概述，本节将直接以行动指南的形式，列出构建RESTful API时必须遵循的核心原则与最佳实践，旨在为开发者提供一套直接可行的实施框架，快速提升API设计与开发能力。 ####
游客762btuqu5wybw666
46 4
游客kwe6k52lwpmug
|
2月前
|
JSON API 开发者
深入理解RESTful API设计原则
在数字化时代，API已成为连接不同软件应用的桥梁。本文旨在探讨RESTful API设计的基本原则和最佳实践，帮助开发者构建高效、可扩展的网络服务接口。通过解析REST架构风格的核心概念，我们将了解如何设计易于理解和使用的API，同时保证其性能和安全性。
游客kwe6k52lwpmug
37 0
zhanbao
|
2月前
|
存储 缓存 API
深入理解RESTful API设计原则
在现代软件开发中，RESTful API已成为前后端分离架构下不可或缺的通信桥梁。本文旨在探讨RESTful API的核心设计原则，包括资源导向、无状态、统一接口、以及可缓存性等，并通过实例解析如何在实际应用中遵循这些原则来构建高效、可维护的API接口。我们将深入分析每个原则背后的设计理念，提供最佳实践指导，帮助开发者优化API设计，提升系统整体性能和用户体验。
zhanbao
42 0
zhanbao
|
2月前
|
安全 测试技术 API
构建高效RESTful API：后端开发的艺术与实践####
在现代软件开发的浩瀚星空中，RESTful API如同一座桥梁，连接着前端世界的绚丽多彩与后端逻辑的深邃复杂。本文旨在探讨如何精心打造一款既高效又易于维护的RESTful API，通过深入浅出的方式，剖析其设计原则、实现技巧及最佳实践，为后端开发者提供一份实用的指南。我们不深入晦涩的理论，只聚焦于那些能够即刻提升API品质与开发效率的关键点，让你的API在众多服务中脱颖而出。 ####
zhanbao
39 0
我不是游客20240119
|
2月前
|
监控 安全 API
深入浅出：构建高效RESTful API的最佳实践
在数字化时代，API已成为连接不同软件和服务的桥梁。本文将带你深入了解如何设计和维护一个高效、可扩展且安全的RESTful API。我们将从基础概念出发，逐步深入到高级技巧，让你能够掌握创建优质API的关键要素。无论你是初学者还是有经验的开发者，这篇文章都将为你提供实用的指导和启示。让我们一起探索API设计的奥秘，打造出色的后端服务吧！
我不是游客20240119
54 8
丰宝宝
|
2月前
|
SQL 缓存 测试技术
构建高性能RESTful API：最佳实践与避坑指南###
—— 本文深入探讨了构建高性能RESTful API的关键技术要点，从设计原则、状态码使用、版本控制到安全性考虑，旨在为开发者提供一套全面的最佳实践框架。通过避免常见的设计陷阱，本文将指导你如何优化API性能，提升用户体验，确保系统的稳定性和可扩展性。 ###
丰宝宝
73 12
mrq4nk6ni2neg
|
2月前
|
JSON 缓存 API
构建高效RESTful API的最佳实践
【10月更文挑战第34天】在数字时代的浪潮中，后端开发扮演着至关重要的角色。本文将带你深入探索如何构建高效的RESTful API，从设计原则到实际编码技巧，再到性能优化和错误处理，我们将一一解锁这些技能。你将学会如何打造一个既优雅又强大的后端服务，让你的应用程序在激烈的市场竞争中脱颖而出。那么，让我们一起踏上这段精彩的旅程吧！
mrq4nk6ni2neg
42 2

热门文章

最新文章

  • 1
    PHP 中基于 Casbin 做 RBAC + RESTful 权限控制
  • 2
    实战阿里qwen2.5-coder 32B，如何配置Cline的Ollama API接口。
  • 3
    OpenAI API深度解析：参数、Token、计费与多种调用方式
  • 4
    自学记录鸿蒙API 13：实现多目标识别Object Detection
  • 5
    API接口是什么？(一篇文章全知道)
  • 6
    AgentScope：阿里开源多智能体低代码开发平台，支持一键导出源码、多种模型API和本地模型部署
  • 7
    DeepSeek Engineer：集成 DeepSeek API 的开源 AI 编程助手，支持文件读取、编辑并生成结构化响应
  • 8
    介绍几个常用的电商API接口及其应用场景。（一篇文章全清楚）
  • 9
    自学记录鸿蒙 API 13：骨骼点检测应用Core Vision Skeleton Detection
  • 10
    1688APP原数据API接口的开发、应用与收益（一篇文章全明白）
  • 1
    创建一个随机图片API
    154
  • 2
    MaxCompute产品使用合集之DataWorks中如何根据MC数据源做成api
    41
  • 3
    阿里云云效操作报错合集之直接用API调用可以使用，但是本地用Go代码调用失败，是什么导致的？
    73
  • 4
    阿里云云效操作报错合集之API返回的错误信息，错误码为"Operate.NoPermission"，该如何解决
    98
  • 5
    微店商品详情数据接口（micro.item_get）丨微店API接口指南
    184
  • 6
    Nest.js 实战 (三)：使用 Swagger 优雅地生成 API 文档
    172
  • 7
    阿里云微服务引擎及 API 网关 2024 年 6 月产品动态
    167
  • 8
    探索微服务架构中的API网关模式
    62
  • 9
    Node.js搭建REST API实战：从基础到部署
    99
  • 10
    构建高效后端API的五大原则
    52

    • 相关电子书

    更多
  • Spring Boot2.0实战Redis分布式缓存
  • CUDA MATH API
  • API PLAYBOOK

    • 相关实验场景

    更多
  • 基于Assistant Api的旅游助手
  • 快速体验智能体API应用
    • 下一篇
    阿里云开通OSS存储服务详细流程