216 lines
6.3 KiB
Markdown
216 lines
6.3 KiB
Markdown
# 用 HTTP 状态码还是自定义状态码? Go 错误处理的优雅解决方案
|
||
|
||
在开发 REST API 时，你是否遇到过这样的问题：
|
||
|
||
- 错误信息杂乱无章，难以定位问题
|
||
- 用户看到的错误提示晦涩难懂
|
||
- 生产环境暴露了敏感信息
|
||
- 错误处理代码重复且难以维护
|
||
|
||
本文将介绍一种优雅的错误处理解决方案，让你的代码更加清晰、可维护，同时提供更好的用户体验。
|
||
|
||
## 错误处理的痛点
|
||
|
||
在传统的错误处理方式中，我们常常会遇到以下问题：
|
||
|
||
1. 错误信息不统一
|
||
- 有的使用数字状态码
|
||
- 有的使用字符串描述
|
||
- 有的直接返回底层错误
|
||
|
||
2. 错误处理代码重复
|
||
- 每个接口都要写错误处理逻辑
|
||
- 日志记录分散在各处
|
||
- HTTP 状态码映射混乱
|
||
|
||
3. 用户体验差
|
||
- 错误提示不友好
|
||
- 缺乏上下文信息
|
||
- 难以定位问题
|
||
|
||
## 传统错误处理方案
|
||
|
||
让我们先看看传统的错误处理方式：
|
||
|
||
```go
|
||
// 方式一：直接返回错误
|
||
func findUser(ctx *gin.Context) {
|
||
user, err := db.FindUser()
|
||
if err != nil {
|
||
ctx.JSON(500, gin.H{"error": err.Error()})
|
||
return
|
||
}
|
||
ctx.JSON(200, user)
|
||
}
|
||
|
||
// 方式二：使用状态码
|
||
func findUser(ctx *gin.Context) {
|
||
user, err := db.FindUser()
|
||
if err != nil {
|
||
ctx.JSON(500, gin.H{
|
||
"code": 1001,
|
||
"msg": "数据库查询失败"
|
||
})
|
||
return
|
||
}
|
||
ctx.JSON(200, user)
|
||
}
|
||
```
|
||
|
||
这些方案虽然简单直接，但存在一些明显的缺陷：
|
||
|
||
1. 安全性问题
|
||
- 方式一直接将底层错误暴露给用户，可能泄露敏感信息
|
||
- 数据库错误可能包含表结构、SQL 语句等内部信息
|
||
|
||
2. 沟通复杂性
|
||
- 错误状态码 400 是 http 状态码还是自定义状态码?
|
||
- 必须对响应体反序列化，才能知道状态
|
||
- 重复定义，http 状态码 200 与自定义状态码 0 都表示成功
|
||
|
||
3. 可维护性差
|
||
- 数字错误码（如 1001）缺乏语义，难以理解
|
||
- 开发者需要查阅文档才能理解错误含义
|
||
- 错误码定义者也可能忘记具体含义
|
||
|
||
## 优雅的错误处理方案
|
||
|
||
让我们先看看优雅的错误处理方案是如何使用的：
|
||
|
||
```go
|
||
var ErrBadRequest = reason.NewError("ErrBadRequest", "请求参数有误")
|
||
|
||
func (u *UserAPI) getUser(ctx *gin.Context, _ *struct{}) (*user.UserOutput, error) {
|
||
return u.core.GetUser(in.ID)
|
||
}
|
||
|
||
// package user
|
||
func (u *Core) GetUser(id int64) (*UserOutput, error) {
|
||
// 参数校验
|
||
if err != nil {
|
||
return nil, ErrBadRequest.With(err.Error(), "xx 参数应在 10~100 之间")
|
||
}
|
||
// 正确处理逻辑...
|
||
}
|
||
```
|
||
|
||
还记得上一篇文章提到的 `web.WrapH` 函数吗? 其响应错误实际是调用的 `web.Fail(err)`，此方法会判断错误是否是 `reason.Error` 类型，如果是，则按照其定义的 http 状态码，reason, msg 等信息返回给客户端。
|
||
|
||
类似
|
||
|
||
HTTP Status Code: 400 (默认所有错误都是 400)
|
||
```json
|
||
{
|
||
"reason": "用于程序识别的错误",
|
||
"msg": "告诉用户的错误信息描述",
|
||
"details":[
|
||
"某字段传输有误",
|
||
"你可以这样修复",
|
||
"查看文档获取更多信息"
|
||
]
|
||
}
|
||
```
|
||
|
||
### 错误码设计思考
|
||
|
||
传统方案中使用数字错误码（如1001表示数据库错误）存在明显缺点：缺乏语义性，需查阅文档理解，定义者也易忘记含义。
|
||
|
||
因此，我们采用字符串作为错误码，优势明显：
|
||
|
||
1. 自解释性强
|
||
- `ErrBadRequest`比`1001`直观明了
|
||
- 错误码即文档
|
||
- 便于代码审查和调试
|
||
|
||
2. 扩展性好
|
||
- 可用模块前缀区分
|
||
- 避免错误码冲突
|
||
- 快速定位问题源
|
||
|
||
在和前端的对接过程中，某些接口出现错误了，前端会一头雾水，找服务端排查，有些可能只是参数问题，如果在响应的错误中有帮助解决的方案呢?能否简化对接复杂度?
|
||
|
||
为避免用户看到技术性错误，或者开发者缺乏上下文信息。我们将错误信息分为四个属性：
|
||
|
||
```go
|
||
type Error struct {
|
||
Reason string
|
||
Msg string
|
||
Details []string
|
||
HTTPStatus int
|
||
}
|
||
```
|
||
|
||
每个字段的作用：
|
||
|
||
1. `reason` 字段
|
||
- 使用大驼峰英语描述错误原因
|
||
- 用于程序内部判断错误类型
|
||
- 支持错误码映射到 HTTP 状态码
|
||
|
||
2. `msg` 字段
|
||
- 使用开发者母语描述错误
|
||
- 面向用户，提供友好的提示
|
||
|
||
3. `details` 字段
|
||
- 提供错误扩展信息
|
||
- 面向开发者，帮助调试
|
||
- 可在生产环境调用 `web.SetRelease()` 隐藏，避免泄露敏感信息
|
||
|
||
4. `HTTPStatus`
|
||
- http 响应状态码
|
||
- 默认为 400
|
||
- 常用状态码 200,400,401 基本就够了，保持简单，少即是多
|
||
|
||
## 使用文档
|
||
|
||
1. 使用预定义的错误类型
|
||
- `reason.ErrBadRequest`: 请求参数错误
|
||
- `reason.ErrStore`: 数据库错误
|
||
- `reason.ErrServer`: 服务器错误
|
||
|
||
2. 错误信息处理
|
||
- 使用 `SetMsg()` 方法修改用户友好提示
|
||
- 使用 `Withf()` 方法添加开发者帮助，增加错误上下文
|
||
|
||
采用一个 reason 原则，即 reason 相同则是同一个错误。
|
||
|
||
```go
|
||
// e1 和 e2 是不是同一个错误!
|
||
e1 = NewError("e1", "e1")
|
||
e2 = NewError("e2", "e1")
|
||
```
|
||
|
||
```go
|
||
// e3 与 e2 是相同的错误
|
||
e2 := NewError("e2", "e2").SetHTTPStatus(200).With("e2-1")
|
||
e3 := fmt.Errorf("e3:%w", e2)
|
||
if !errors.Is(e3, e2) {
|
||
t.Fatal("expect e3 is e2, but not")
|
||
}
|
||
```
|
||
|
||
```go
|
||
// 将错误转换为 *reason.Error 结构体
|
||
var e5 *reason.Error
|
||
if !errors.As(e4, &e5) {
|
||
t.Fatal("expect e4 as e5, but not")
|
||
}
|
||
```
|
||
|
||
## 总结
|
||
|
||
通过合理的分层和封装，我们实现了：
|
||
|
||
1. 统一的错误处理流程
|
||
2. 友好的用户提示
|
||
3. 详细的开发者信息
|
||
4. 安全的错误暴露
|
||
|
||
这种设计既保证了开发效率，又提升了用户体验。如果你正在寻找一个优雅的错误处理解决方案，不妨试试这个方案。
|
||
|
||
## 关于 goddd
|
||
|
||
本文介绍的错误处理是 [goddd](https://github.com/ixugo/goddd) 项目中的一个核心组件。goddd 是一个基于 DDD（领域驱动设计）理念的 Go 项目目标，它提供了一系列工具和最佳实践，帮助开发者构建可维护、可扩展的应用程序。
|
||
|
||
如果你对本文介绍的内容感兴趣，欢迎访问 [goddd 项目](https://github.com/ixugo/goddd) 了解更多细节。项目提供了完整的示例代码和详细的文档，可以帮助你快速上手。
|