huang
fb83c9a706
- 新增统一错误码定义和管理 (pkg/errors/codes.go) - 新增全局错误处理器和中间件 (pkg/errors/handler.go, internal/middleware/error_handler.go) - 新增错误上下文管理 (pkg/errors/context.go) - 增强 Panic 恢复中间件 (internal/middleware/recover.go) - 新增完整的单元测试和集成测试 - 新增功能文档 (docs/003-error-handling/) - 新增功能规范 (specs/003-error-handling/) - 更新 CLAUDE.md 和 README.md
563 lines
14 KiB
Markdown
563 lines
14 KiB
Markdown
# 使用指南：Fiber 错误处理集成
|
||
|
||
**功能编号**: 003-error-handling
|
||
**版本**: 1.0.0
|
||
**更新日期**: 2025-11-15
|
||
|
||
## 目录
|
||
|
||
1. [快速开始](#快速开始)
|
||
2. [错误码参考](#错误码参考)
|
||
3. [Handler 中使用错误](#handler-中使用错误)
|
||
4. [客户端错误处理](#客户端错误处理)
|
||
5. [错误日志查询](#错误日志查询)
|
||
6. [最佳实践](#最佳实践)
|
||
7. [常见问题](#常见问题)
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 1. 在 Handler 中返回错误
|
||
|
||
```go
|
||
package handler
|
||
|
||
import (
|
||
"github.com/break/junhong_cmp_fiber/pkg/errors"
|
||
"github.com/break/junhong_cmp_fiber/pkg/response"
|
||
"github.com/gofiber/fiber/v2"
|
||
)
|
||
|
||
func (h *UserHandler) GetUser(c *fiber.Ctx) error {
|
||
userID := c.Params("id")
|
||
|
||
// 参数验证失败
|
||
if userID == "" {
|
||
return errors.New(errors.CodeInvalidParam, "用户 ID 不能为空")
|
||
}
|
||
|
||
// 调用服务层
|
||
user, err := h.service.GetByID(c.Context(), userID)
|
||
if err != nil {
|
||
// 包装底层错误
|
||
return errors.Wrap(errors.CodeDatabaseError, "查询用户失败", err)
|
||
}
|
||
|
||
// 资源未找到
|
||
if user == nil {
|
||
return errors.New(errors.CodeNotFound, "用户不存在")
|
||
}
|
||
|
||
return response.Success(c, user)
|
||
}
|
||
```
|
||
|
||
### 2. 错误响应格式
|
||
|
||
所有错误自动转换为统一格式：
|
||
|
||
```json
|
||
{
|
||
"code": 1001,
|
||
"data": null,
|
||
"msg": "参数验证失败",
|
||
"timestamp": "2025-11-15T10:00:00+08:00"
|
||
}
|
||
```
|
||
|
||
HTTP Header 中包含 Request ID：
|
||
```
|
||
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
|
||
```
|
||
|
||
---
|
||
|
||
## 错误码参考
|
||
|
||
### 成功
|
||
|
||
| 错误码 | 名称 | HTTP 状态 | 消息 |
|
||
|--------|------|-----------|------|
|
||
| 0 | CodeSuccess | 200 | 操作成功 |
|
||
|
||
### 客户端错误 (1000-1999)
|
||
|
||
| 错误码 | 名称 | HTTP 状态 | 消息 | 使用场景 |
|
||
|--------|------|-----------|------|----------|
|
||
| 1001 | CodeInvalidParam | 400 | 参数验证失败 | 请求参数格式错误、必填字段缺失 |
|
||
| 1002 | CodeMissingToken | 401 | 缺少认证令牌 | 未提供 Token |
|
||
| 1003 | CodeInvalidToken | 401 | 无效的认证令牌 | Token 格式错误 |
|
||
| 1004 | CodeInvalidCredentials | 401 | 认证凭证无效 | Token 过期、验证失败 |
|
||
| 1005 | CodeForbidden | 403 | 禁止访问 | 无权限访问资源 |
|
||
| 1006 | CodeNotFound | 404 | 资源未找到 | 用户、订单等资源不存在 |
|
||
| 1007 | CodeConflict | 409 | 资源冲突 | 唯一性约束冲突 |
|
||
| 1008 | CodeTooManyRequests | 429 | 请求过多 | 触发限流 |
|
||
| 1009 | CodeRequestEntityTooLarge | 413 | 请求体过大 | 文件上传超限 |
|
||
|
||
### 服务端错误 (2000-2999)
|
||
|
||
| 错误码 | 名称 | HTTP 状态 | 消息 | 使用场景 |
|
||
|--------|------|-----------|------|----------|
|
||
| 2001 | CodeInternalError | 500 | 内部服务器错误 | 未分类的内部错误 |
|
||
| 2002 | CodeDatabaseError | 500 | 数据库错误 | 数据库连接失败、查询错误 |
|
||
| 2003 | CodeCacheError | 500 | 缓存服务错误 | Redis 连接失败 |
|
||
| 2004 | CodeServiceUnavailable | 503 | 服务暂时不可用 | 外部服务不可用 |
|
||
| 2005 | CodeTimeout | 504 | 请求超时 | 上游服务超时 |
|
||
| 2006 | CodeQueueError | 500 | 任务队列错误 | Asynq 任务投递失败 |
|
||
|
||
---
|
||
|
||
## Handler 中使用错误
|
||
|
||
### 1. 参数验证错误
|
||
|
||
```go
|
||
func (h *UserHandler) CreateUser(c *fiber.Ctx) error {
|
||
var req CreateUserRequest
|
||
if err := c.BodyParser(&req); err != nil {
|
||
return errors.New(errors.CodeInvalidParam, "请求参数格式错误")
|
||
}
|
||
|
||
// 业务验证
|
||
if len(req.Username) < 3 || len(req.Username) > 20 {
|
||
return errors.New(errors.CodeInvalidParam, "用户名长度必须在 3-20 个字符之间")
|
||
}
|
||
|
||
if !isValidEmail(req.Email) {
|
||
return errors.New(errors.CodeInvalidParam, "邮箱格式不正确")
|
||
}
|
||
|
||
// 继续处理...
|
||
}
|
||
```
|
||
|
||
### 2. 认证/授权错误
|
||
|
||
```go
|
||
func (h *OrderHandler) GetOrder(c *fiber.Ctx) error {
|
||
// 检查用户是否登录
|
||
userID := c.Locals("user_id")
|
||
if userID == nil {
|
||
return errors.New(errors.CodeMissingToken, "请先登录")
|
||
}
|
||
|
||
order, err := h.service.GetByID(c.Params("id"))
|
||
if err != nil {
|
||
return errors.Wrap(errors.CodeDatabaseError, "查询订单失败", err)
|
||
}
|
||
|
||
// 检查权限
|
||
if order.UserID != userID.(string) {
|
||
return errors.New(errors.CodeForbidden, "无权访问此订单")
|
||
}
|
||
|
||
return response.Success(c, order)
|
||
}
|
||
```
|
||
|
||
### 3. 资源未找到
|
||
|
||
```go
|
||
func (h *UserHandler) GetUser(c *fiber.Ctx) error {
|
||
user, err := h.service.GetByID(c.Params("id"))
|
||
if err != nil {
|
||
return errors.Wrap(errors.CodeDatabaseError, "查询用户失败", err)
|
||
}
|
||
|
||
if user == nil {
|
||
return errors.New(errors.CodeNotFound, fmt.Sprintf("用户 ID %s 不存在", c.Params("id")))
|
||
}
|
||
|
||
return response.Success(c, user)
|
||
}
|
||
```
|
||
|
||
### 4. 资源冲突
|
||
|
||
```go
|
||
func (h *UserHandler) CreateUser(c *fiber.Ctx) error {
|
||
var req CreateUserRequest
|
||
if err := c.BodyParser(&req); err != nil {
|
||
return errors.New(errors.CodeInvalidParam, "请求参数错误")
|
||
}
|
||
|
||
// 检查用户名是否已存在
|
||
exists, err := h.service.ExistsByUsername(req.Username)
|
||
if err != nil {
|
||
return errors.Wrap(errors.CodeDatabaseError, "检查用户名失败", err)
|
||
}
|
||
|
||
if exists {
|
||
return errors.New(errors.CodeConflict, "用户名已被使用")
|
||
}
|
||
|
||
// 创建用户...
|
||
}
|
||
```
|
||
|
||
### 5. 外部服务错误
|
||
|
||
```go
|
||
func (h *NotificationHandler) SendEmail(c *fiber.Ctx) error {
|
||
var req SendEmailRequest
|
||
if err := c.BodyParser(&req); err != nil {
|
||
return errors.New(errors.CodeInvalidParam, "请求参数错误")
|
||
}
|
||
|
||
// 调用外部邮件服务
|
||
err := h.emailService.Send(req.To, req.Subject, req.Body)
|
||
if err != nil {
|
||
// 包装外部服务错误
|
||
return errors.Wrap(errors.CodeServiceUnavailable, "邮件发送失败", err)
|
||
}
|
||
|
||
return response.Success(c, nil)
|
||
}
|
||
```
|
||
|
||
### 6. 自定义 HTTP 状态码（高级用法）
|
||
|
||
```go
|
||
func (h *Handler) SpecialCase(c *fiber.Ctx) error {
|
||
// 默认 CodeInvalidParam 映射为 400
|
||
// 但某些场景需要返回 422
|
||
appErr := errors.New(errors.CodeInvalidParam, "数据验证失败")
|
||
appErr = appErr.WithHTTPStatus(422)
|
||
return appErr
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 客户端错误处理
|
||
|
||
### JavaScript/TypeScript
|
||
|
||
```typescript
|
||
async function fetchUser(userId: string) {
|
||
try {
|
||
const response = await fetch(`/api/v1/users/${userId}`);
|
||
const data = await response.json();
|
||
|
||
// 检查业务错误码
|
||
if (data.code !== 0) {
|
||
const requestId = response.headers.get('X-Request-ID');
|
||
|
||
switch (data.code) {
|
||
// 认证错误 - 跳转登录
|
||
case 1002:
|
||
case 1003:
|
||
case 1004:
|
||
redirectToLogin();
|
||
break;
|
||
|
||
// 权限错误 - 显示无权限提示
|
||
case 1005:
|
||
showError('您没有权限访问此资源');
|
||
break;
|
||
|
||
// 资源未找到 - 显示 404 页面
|
||
case 1006:
|
||
showNotFoundPage();
|
||
break;
|
||
|
||
// 服务端错误 - 显示错误并提供 Request ID
|
||
case 2001:
|
||
case 2002:
|
||
case 2003:
|
||
case 2004:
|
||
showError(`服务器错误，请联系管理员。Request ID: ${requestId}`);
|
||
break;
|
||
|
||
// 限流错误 - 提示稍后重试
|
||
case 1008:
|
||
showError('请求过于频繁，请稍后再试');
|
||
break;
|
||
|
||
// 其他错误 - 显示错误消息
|
||
default:
|
||
showError(data.msg);
|
||
}
|
||
|
||
return null;
|
||
}
|
||
|
||
return data.data;
|
||
} catch (err) {
|
||
// 网络错误
|
||
showError('网络连接失败，请检查您的网络');
|
||
return null;
|
||
}
|
||
}
|
||
```
|
||
|
||
### Axios 拦截器
|
||
|
||
```typescript
|
||
import axios from 'axios';
|
||
|
||
const api = axios.create({
|
||
baseURL: '/api/v1',
|
||
});
|
||
|
||
// 响应拦截器
|
||
api.interceptors.response.use(
|
||
(response) => {
|
||
const { code, data, msg } = response.data;
|
||
|
||
if (code !== 0) {
|
||
const requestId = response.headers['x-request-id'];
|
||
|
||
// 根据错误码处理
|
||
if ([1002, 1003, 1004].includes(code)) {
|
||
// 认证失败，跳转登录
|
||
redirectToLogin();
|
||
return Promise.reject(new Error(msg));
|
||
}
|
||
|
||
if (code === 1005) {
|
||
// 权限不足
|
||
showError('您没有权限执行此操作');
|
||
return Promise.reject(new Error(msg));
|
||
}
|
||
|
||
if (code >= 2000) {
|
||
// 服务端错误
|
||
console.error(`Server error: ${msg}, Request ID: ${requestId}`);
|
||
showError(`服务器错误，Request ID: ${requestId}`);
|
||
return Promise.reject(new Error(msg));
|
||
}
|
||
|
||
// 其他业务错误
|
||
showError(msg);
|
||
return Promise.reject(new Error(msg));
|
||
}
|
||
|
||
return data;
|
||
},
|
||
(error) => {
|
||
// 网络错误
|
||
showError('网络连接失败');
|
||
return Promise.reject(error);
|
||
}
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 错误日志查询
|
||
|
||
### 1. 通过 Request ID 查询
|
||
|
||
```bash
|
||
# 查询特定请求的所有日志
|
||
grep "550e8400-e29b-41d4-a716-446655440000" logs/app.log
|
||
|
||
# 使用 jq 格式化 JSON 日志
|
||
grep "550e8400-e29b-41d4-a716-446655440000" logs/app.log | jq .
|
||
```
|
||
|
||
### 2. 查询特定错误码
|
||
|
||
```bash
|
||
# 查询所有参数验证失败的错误
|
||
grep '"error_code":1001' logs/app.log | jq .
|
||
|
||
# 查询所有数据库错误
|
||
grep '"error_code":2002' logs/app.log | jq .
|
||
```
|
||
|
||
### 3. 查询 Panic 堆栈
|
||
|
||
```bash
|
||
# 查询所有 panic 日志
|
||
grep "panic recovered" logs/app.log
|
||
|
||
# 查询包含堆栈的完整 panic 日志
|
||
grep -A 20 "panic recovered" logs/app.log
|
||
```
|
||
|
||
### 4. 按时间范围查询
|
||
|
||
```bash
|
||
# 查询最近 1 小时的错误日志
|
||
grep '"level":"error"' logs/app.log | grep "$(date -u -d '1 hour ago' '+%Y-%m-%dT%H')"
|
||
```
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 错误码选择
|
||
|
||
✅ **正确示例**：
|
||
```go
|
||
// 参数验证失败
|
||
return errors.New(errors.CodeInvalidParam, "用户名不能为空")
|
||
|
||
// 资源未找到
|
||
return errors.New(errors.CodeNotFound, "订单不存在")
|
||
|
||
// 数据库错误
|
||
return errors.Wrap(errors.CodeDatabaseError, "查询失败", err)
|
||
```
|
||
|
||
❌ **错误示例**：
|
||
```go
|
||
// 不要使用错误的错误码
|
||
return errors.New(errors.CodeDatabaseError, "用户名不能为空") // 应该用 CodeInvalidParam
|
||
|
||
// 不要返回空消息
|
||
return errors.New(errors.CodeNotFound, "") // 应该提供具体消息
|
||
```
|
||
|
||
### 2. 错误消息编写
|
||
|
||
✅ **正确示例**：
|
||
```go
|
||
// 清晰、具体的错误消息
|
||
errors.New(errors.CodeInvalidParam, "用户名长度必须在 3-20 个字符之间")
|
||
errors.New(errors.CodeNotFound, "用户 ID 123 不存在")
|
||
errors.New(errors.CodeConflict, "邮箱 test@example.com 已被注册")
|
||
```
|
||
|
||
❌ **错误示例**：
|
||
```go
|
||
// 不要使用模糊的消息
|
||
errors.New(errors.CodeInvalidParam, "错误")
|
||
errors.New(errors.CodeNotFound, "not found")
|
||
|
||
// 不要暴露敏感信息
|
||
errors.New(errors.CodeDatabaseError, "SQL error: SELECT * FROM users WHERE password = '...'")
|
||
```
|
||
|
||
### 3. 错误包装
|
||
|
||
✅ **正确示例**：
|
||
```go
|
||
// 包装底层错误，保留错误链
|
||
user, err := h.repo.GetByID(id)
|
||
if err != nil {
|
||
return errors.Wrap(errors.CodeDatabaseError, "查询用户失败", err)
|
||
}
|
||
```
|
||
|
||
❌ **错误示例**：
|
||
```go
|
||
// 丢失原始错误信息
|
||
user, err := h.repo.GetByID(id)
|
||
if err != nil {
|
||
return errors.New(errors.CodeDatabaseError, "查询用户失败") // 应该用 Wrap
|
||
}
|
||
```
|
||
|
||
### 4. 不要过度处理错误
|
||
|
||
✅ **正确示例**：
|
||
```go
|
||
func (h *Handler) GetUser(c *fiber.Ctx) error {
|
||
user, err := h.service.GetByID(c.Params("id"))
|
||
if err != nil {
|
||
// 直接返回错误，让 ErrorHandler 统一处理
|
||
return err
|
||
}
|
||
return response.Success(c, user)
|
||
}
|
||
```
|
||
|
||
❌ **错误示例**：
|
||
```go
|
||
func (h *Handler) GetUser(c *fiber.Ctx) error {
|
||
user, err := h.service.GetByID(c.Params("id"))
|
||
if err != nil {
|
||
// 不要在 Handler 中手动构造错误响应
|
||
return c.Status(500).JSON(fiber.Map{"error": err.Error()})
|
||
}
|
||
return response.Success(c, user)
|
||
}
|
||
```
|
||
|
||
### 5. Panic 使用建议
|
||
|
||
✅ **正确做法**：
|
||
```go
|
||
// 让代码正常返回错误，不要主动 panic
|
||
func (s *Service) Process() error {
|
||
if invalidState {
|
||
return errors.New(errors.CodeInternalError, "无效状态")
|
||
}
|
||
return nil
|
||
}
|
||
```
|
||
|
||
❌ **避免使用**：
|
||
```go
|
||
// 避免在业务代码中主动 panic
|
||
func (s *Service) Process() {
|
||
if invalidState {
|
||
panic("invalid state") // 不推荐
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意**：即使代码中有 panic，Recover 中间件也会自动捕获并转换为错误响应，确保服务不崩溃。
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 如何自定义错误消息？
|
||
|
||
A: 使用 `errors.New()` 的第二个参数：
|
||
|
||
```go
|
||
return errors.New(errors.CodeInvalidParam, "自定义错误消息")
|
||
```
|
||
|
||
### Q2: 如何查看底层错误详情？
|
||
|
||
A: 底层错误会记录在日志中，通过 Request ID 查询：
|
||
|
||
```bash
|
||
grep "<request-id>" logs/app.log | jq .
|
||
```
|
||
|
||
### Q3: 客户端如何获取 Request ID？
|
||
|
||
A: 从响应 Header 中获取：
|
||
|
||
```javascript
|
||
const requestId = response.headers.get('X-Request-ID');
|
||
```
|
||
|
||
### Q4: 错误码冲突怎么办？
|
||
|
||
A: 参考 `pkg/errors/codes.go` 中的定义，避免使用已定义的错误码。如需新增错误码，请在对应范围内添加。
|
||
|
||
### Q5: 如何测试错误处理？
|
||
|
||
A: 参考 `tests/integration/error_handler_test.go` 中的示例：
|
||
|
||
```go
|
||
resp, _ := app.Test(httptest.NewRequest("GET", "/api/v1/users/invalid", nil))
|
||
assert.Equal(t, 400, resp.StatusCode)
|
||
```
|
||
|
||
### Q6: 如何关闭堆栈跟踪？
|
||
|
||
A: 堆栈跟踪仅在 panic 时记录，无法关闭。如需调整，修改 `internal/middleware/recover.go`。
|
||
|
||
---
|
||
|
||
## 更多信息
|
||
|
||
- [功能总结](./功能总结.md) - 功能概述和技术要点
|
||
- [架构说明](./架构说明.md) - 错误处理架构设计
|
||
- [错误码定义](../../pkg/errors/codes.go) - 完整错误码列表
|
||
|
||
---
|
||
|
||
**版本历史**:
|
||
- v1.0.0 (2025-11-15): 初始版本
|