errors

package

v1.0.0-alpha.25 Latest Latest Go to latest Published: Jan 4, 2026 License: MIT Imports: 2 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/gocrud/csgo

Links

Open Source Insights

README ¶

错误处理系统

CSGO 框架提供了简洁、类型安全、功能强大的错误处理体系。

🎯 核心特性

✅ 简洁易用 - 预定义常用错误方法，一行代码搞定
✅ 类型安全 - 模块化设计，避免拼写错误
✅ 链式调用 - 流畅的 API，支持灵活组合
✅ 不可变 - 所有操作返回新实例，线程安全
✅ 错误链 - 完整支持 Go 1.13+ 错误包装
✅ HTTP 集成 - 自动映射合适的 HTTP 状态码

🚀 快速开始

1. 定义模块

package services

import "github.com/gocrud/csgo/errors"

// 定义各模块的错误
var (
    UserErrors  = errors.NewModule("USER")
    OrderErrors = errors.NewModule("ORDER")
    DramaErrors = errors.NewModule("DRAMA")
)

2. 使用快捷方法（最常用）

// 资源不存在
err := UserErrors.NotFound("用户不存在")
// 生成: code="USER.NOT_FOUND", httpCode=404

// 参数无效
err := OrderErrors.InvalidParam("订单金额必须大于0")
// 生成: code="ORDER.INVALID_PARAM", httpCode=400

// 权限不足
err := DramaErrors.PermissionDenied("无权访问此剧集")
// 生成: code="DRAMA.PERMISSION_DENIED", httpCode=403

3. 自定义错误码

// 支付失败
err := OrderErrors.Code("PAYMENT_FAILED").Msg("支付失败")
// 生成: code="ORDER.PAYMENT_FAILED", httpCode=400

// 格式化消息
err := OrderErrors.Code("PAYMENT_FAILED").Msgf("余额不足: %.2f", balance)

// 自定义 HTTP 状态码
err := OrderErrors.Code("PAYMENT_REQUIRED").MsgWithCode("需要支付", 402)

🎨 Module 快捷方法

方法	生成错误码	HTTP 状态码	说明
`NotFound(msg)`	`模块.NOT_FOUND`	404	资源不存在
`AlreadyExists(msg)`	`模块.ALREADY_EXISTS`	409	资源已存在
`InvalidParam(msg)`	`模块.INVALID_PARAM`	400	参数无效
`InvalidStatus(msg)`	`模块.INVALID_STATUS`	400	状态无效
`PermissionDenied(msg)`	`模块.PERMISSION_DENIED`	403	权限不足
`Unauthorized(msg)`	`模块.UNAUTHORIZED`	401	未授权
`OperationFailed(msg)`	`模块.OPERATION_FAILED`	400	操作失败
`Expired(msg)`	`模块.EXPIRED`	410	资源已过期
`Locked(msg)`	`模块.LOCKED`	423	资源已锁定
`LimitExceeded(msg)`	`模块.LIMIT_EXCEEDED`	429	超出限制
`Conflict(msg)`	`模块.CONFLICT`	409	资源冲突
`Internal(msg)`	`模块.INTERNAL_ERROR`	500	内部错误
`ServiceUnavailable(msg)`	`模块.SERVICE_UNAVAILABLE`	503	服务不可用

使用示例：

// 可以不传消息，使用默认消息
err := UserErrors.NotFound()  // message="资源不存在"

// 传入自定义消息
err := UserErrors.NotFound("用户不存在")  // message="用户不存在"

🔧 自定义错误码

基本用法

// Code().Msg() - 自定义错误码 + 消息
err := OrderErrors.Code("PAYMENT_FAILED").Msg("支付失败")

// Code().Msgf() - 格式化消息
err := OrderErrors.Code("PAYMENT_FAILED").Msgf("订单 %s 支付失败", orderID)

// Code().MsgWithCode() - 自定义 HTTP 状态码
err := OrderErrors.Code("PAYMENT_REQUIRED").MsgWithCode("需要支付", 402)

完全自定义

// Custom() - 完全控制
err := OrderErrors.Custom("RARE_ERROR", "罕见错误", 418)

// Customf() - 带格式化
err := OrderErrors.Customf("RARE_ERROR", 418, "错误: %s", reason)

🔗 链式调用

所有方法返回新实例，支持流畅的链式调用：

添加详细信息

err := OrderErrors.NotFound("订单不存在").
    WithDetail("orderId", "20231222001").
    WithDetail("userId", 123)

修改消息

// 创建基础错误
baseErr := OrderErrors.Code("PAYMENT_FAILED").Msg("支付失败")

// 根据条件修改消息
if networkError {
    err = baseErr.WithMsg("网络异常，请稍后重试")
} else if balanceError {
    err = baseErr.WithMsgf("余额不足: %.2f", balance)
}

// 追加消息
err := OrderErrors.NotFound("订单不存在").AppendMsg("，请联系客服")

// 前置消息
err := OrderErrors.OperationFailed("创建失败").PrependMsg("订单")
// 结果: "订单创建失败"

包装底层错误

user, err := repo.FindByID(id)
if err != nil {
    return UserErrors.NotFound("用户不存在").
        WithDetail("userId", id).
        Wrap(err)  // 包装原始错误，支持 errors.Unwrap()
}

覆盖 HTTP 状态码

err := OrderErrors.NotFound("订单不存在").
    WithHTTPCode(410)  // 覆盖默认的 404，使用 410 Gone

组合使用

err := OrderErrors.Code("PAYMENT_FAILED").
    Msgf("订单 %s 支付失败", orderID).
    WithDetail("orderId", orderID).
    WithDetail("amount", amount).
    WithDetail("reason", "余额不足").
    WithDetail("retryable", true).
    WithHTTPCode(402).
    Wrap(originalErr)

🌐 Web 层集成

错误会自动转换为标准的 API 响应格式。

Controller 中使用

func (c *UserController) GetUser(ctx *web.HttpContext) web.IActionResult {
    id := ctx.Params().Int("id").Value()
    
    user, err := c.service.GetUser(id)
    if err != nil {
        // 自动处理错误，映射到合适的 HTTP 状态码
        return ctx.Error(err)
    }
    
    return ctx.Ok(user)
}

错误响应格式

{
  "success": false,
  "error": {
    "code": "USER.NOT_FOUND",
    "message": "用户不存在",
    "details": {
      "userId": 123
    }
  }
}

HTTP 状态码映射

框架会自动根据错误码映射到合适的 HTTP 状态码：

错误码模式	HTTP 状态码
`*.NOT_FOUND`	404
`*.ALREADY_EXISTS`	409
`.INVALID_`	400
`*.PERMISSION_DENIED`	403
`*.UNAUTHORIZED`	401
`*.EXPIRED`	410
`*.LOCKED`	423
`*.LIMIT_EXCEEDED`	429
其他	400

💡 最佳实践

1. 统一定义模块错误

// services/errors.go
package services

import "github.com/gocrud/csgo/errors"

var (
    UserErrors  = errors.NewModule("USER")
    OrderErrors = errors.NewModule("ORDER")
    DramaErrors = errors.NewModule("DRAMA")
    // ... 其他模块
)

2. Service 层返回错误

func (s *OrderService) GetOrder(id string) (*Order, error) {
    order, err := s.repo.FindByID(id)
    if err != nil {
        if errors.Is(err, gorm.ErrRecordNotFound) {
            return nil, OrderErrors.NotFound("订单不存在").
                WithDetail("orderId", id)
        }
        return nil, OrderErrors.Internal("查询订单失败").Wrap(err)
    }
    
    return order, nil
}

3. 根据业务逻辑返回不同错误

func (s *OrderService) ProcessPayment(orderID string, amount float64) error {
    order, err := s.GetOrder(orderID)
    if err != nil {
        return err
    }
    
    // 检查订单状态
    if order.Status == "cancelled" {
        return OrderErrors.InvalidStatus("订单已取消，无法支付")
    }
    
    if order.Status == "paid" {
        return OrderErrors.AlreadyExists("订单已支付")
    }
    
    // 检查余额
    balance, _ := s.accountService.GetBalance(order.UserID)
    if balance < amount {
        return OrderErrors.Code("PAYMENT_FAILED").
            Msgf("余额不足，当前: %.2f，需要: %.2f", balance, amount).
            WithDetail("balance", balance).
            WithDetail("required", amount)
    }
    
    return nil
}

4. 渐进式错误构建

func (s *OrderService) ValidateOrder(order *Order) error {
    // 基础错误
    baseErr := OrderErrors.InvalidParam()
    
    if order.Amount <= 0 {
        return baseErr.WithMsg("订单金额必须大于0").
            WithDetail("amount", order.Amount)
    }
    
    if len(order.Items) == 0 {
        return baseErr.WithMsg("订单商品不能为空")
    }
    
    return nil
}

5. 错误链追踪

func (s *OrderService) CreateOrder(req *CreateOrderRequest) error {
    // 调用多层服务
    if err := s.validateStock(req.Items); err != nil {
        return OrderErrors.OperationFailed("创建订单失败").
            WithMsg("库存不足").
            Wrap(err)  // 保留原始错误链
    }
    
    // 可以在外层判断根因
    // if errors.Is(err, StockErrors.NotEnough) { ... }
    
    return nil
}

📚 完整 API 参考

Module 方法

方法	说明
`NotFound(msg...)`	资源不存在 (404)
`AlreadyExists(msg...)`	资源已存在 (409)
`InvalidParam(msg...)`	参数无效 (400)
`InvalidStatus(msg...)`	状态无效 (400)
`PermissionDenied(msg...)`	权限不足 (403)
`Unauthorized(msg...)`	未授权 (401)
`OperationFailed(msg...)`	操作失败 (400)
`Expired(msg...)`	资源已过期 (410)
`Locked(msg...)`	资源已锁定 (423)
`LimitExceeded(msg...)`	超出限制 (429)
`Conflict(msg...)`	资源冲突 (409)
`Internal(msg...)`	内部错误 (500)
`ServiceUnavailable(msg...)`	服务不可用 (503)
`Code(code)`	自定义错误码构建器
`Custom(code, msg, httpCode)`	完全自定义错误

Error 方法

方法	说明	不可变
`WithMsg(msg)`	覆盖错误消息	✅
`WithMsgf(format, args...)`	格式化覆盖消息	✅
`AppendMsg(suffix)`	追加消息	✅
`PrependMsg(prefix)`	前置消息	✅
`WithDetail(key, value)`	添加详细信息	✅
`WithDetails(map)`	批量添加详细信息	✅
`WithHTTPCode(code)`	设置 HTTP 状态码	✅
`Wrap(err)`	包装原始错误	✅
`Error()`	实现 error 接口	-
`Unwrap()`	返回原始错误	-
`Code()`	获取错误码	-
`Message()`	获取错误消息	-
`HTTPCode()`	获取 HTTP 状态码	-
`Details()`	获取详细信息	-
`Category()`	获取错误分类	-

ErrorBuilder 方法

方法	说明
`Msg(msg)`	设置消息，返回 Error
`Msgf(format, args...)`	格式化消息，返回 Error
`MsgWithCode(msg, httpCode)`	设置消息和 HTTP 状态码

🔄 迁移指南

从旧版本迁移

1. 替换 `Business()` 为 `NewModule()`

// ❌ 旧方式
var ErrUser = errors.Business("USER")
err := ErrUser.NotFound("用户不存在")

// ✅ 新方式
var UserErrors = errors.NewModule("USER")
err := UserErrors.NotFound("用户不存在")

2. 替换 `Code().Message()` 为 `Code().Msg()`

// ❌ 旧方式
err := ErrUser.Code("CUSTOM").Message("自定义错误")

// ✅ 新方式
err := UserErrors.Code("CUSTOM").Msg("自定义错误")

3. `BizError` 改为 `Error`

// ❌ 旧方式
func GetUser(id int) (*User, *errors.BizError) {
    return nil, errors.Business("USER").NotFound("用户不存在")
}

// ✅ 新方式
func GetUser(id int) (*User, error) {
    return nil, UserErrors.NotFound("用户不存在")
}

4. 字段访问改为方法调用

// ❌ 旧方式（会导致编译错误）
code := err.Code
message := err.Message

// ✅ 新方式
code := err.Code()
message := err.Message()

注意: 新版本的所有方法都返回新实例，是线程安全的！

🎉 优势总结

与旧版本相比的改进：

更简洁 - UserErrors.NotFound() vs errors.Business("USER").NotFound()
更安全 - 不可变设计，避免并发问题
更灵活 - 支持 WithMsg() 动态修改消息
更强大 - 完整的链式调用和错误链支持
更清晰 - Module 组织错误，避免全局污染

更多完整示例请查看 EXAMPLES.md

为特定错误类型注册自定义处理逻辑：

package main

import (
    "database/sql"
    "errors"
    "github.com/gocrud/csgo/web"
)

func init() {
    // 注册数据库记录不存在错误处理器
    web.RegisterErrorHandler(
        func(err error) bool {
            return errors.Is(err, sql.ErrNoRows)
        },
        func(err error, msg ...string) web.IActionResult {
            message := "记录不存在"
            if len(msg) > 0 && msg[0] != "" {
                message = msg[0]
            }
            return web.Error(404, "NOT_FOUND", message)
        },
    )
    
    // 注册超时错误处理器
    web.RegisterErrorHandler(
        func(err error) bool {
            return errors.Is(err, context.DeadlineExceeded)
        },
        func(err error, msg ...string) web.IActionResult {
            return web.Error(408, "TIMEOUT", "请求超时")
        },
    )
}

// 控制器中使用，自动应用自定义处理器
func (ctrl *UserController) GetUser(c *web.HttpContext) web.IActionResult {
    user, err := ctrl.repo.FindByID(id) // 可能返回 sql.ErrNoRows
    if err != nil {
        return c.FromError(err, "用户不存在") // 自动使用注册的处理器
    }
    return c.Ok(user)
}

错误响应格式

验证错误响应

{
  "success": false,
  "error": {
    "code": "VALIDATION.FAILED",
    "message": "验证失败",
    "fields": [
      {
        "field": "email",
        "message": "邮箱格式不正确",
        "code": "VALIDATION.EMAIL"
      },
      {
        "field": "password",
        "message": "长度不能少于 6",
        "code": "VALIDATION.MIN_LENGTH"
      }
    ]
  }
}

业务错误响应

{
  "success": false,
  "error": {
    "code": "USER.NOT_FOUND",
    "message": "用户不存在"
  }
}

验证错误

验证错误会自动使用框架定义的错误码。

验证器示例

package validators

import (
    "github.com/gocrud/csgo/validation"
)

type CreateUserRequest struct {
    Email    string `json:"email"`
    Password string `json:"password"`
    Age      int    `json:"age"`
}

func NewCreateUserValidator() *validation.AbstractValidator[CreateUserRequest] {
    v := validation.NewValidator[CreateUserRequest]()  // 快速失败模式
    
    v.Field(func(r *CreateUserRequest) string { return r.Email }).
        NotEmpty().           // 自动使用 VALIDATION.REQUIRED
        EmailAddress()        // 自动使用 VALIDATION.EMAIL
    
    v.Field(func(r *CreateUserRequest) string { return r.Password }).
        NotEmpty().           // 自动使用 VALIDATION.REQUIRED
        MinLength(6)          // 自动使用 VALIDATION.MIN_LENGTH
    
    v.FieldInt(func(r *CreateUserRequest) int { return r.Age }).
        GreaterThanOrEqual(18) // 自动使用 VALIDATION.MIN
    
    return v
}

// 注册验证器
func init() {
    validation.RegisterValidator[CreateUserRequest](NewCreateUserValidator())
}

验证模式

框架支持两种验证模式：

快速失败模式（默认，推荐）

// 创建快速失败验证器
v := validation.NewValidator[User]()
// 遇到第一个错误立即返回，性能最优
// 适合 99% 的表单验证场景

全量验证模式

// 创建全量验证器
v := validation.NewValidatorAll[User]()
// 收集所有字段的所有错误
// 适合批量数据导入、复杂表单审核等场景

注意： Web 层无需关心验证模式，注册什么模式就使用什么模式。

最佳实践

1. 错误码命名规范

模块名：使用业务领域名称，如 USER、ORDER、PAYMENT
语义描述：使用清晰的动词或状态描述，如 NOT_FOUND、INVALID_STATUS
全大写下划线：统一使用大写字母和下划线
避免重复：不要在错误码中重复模块名，如 ~~USER.USER_NOT_FOUND~~ 应为 USER.NOT_FOUND

2. 优先使用构建器

// ✅ 推荐：使用构建器
err := errors.Business("USER").NotFound("用户不存在")

// ❌ 不推荐：手动定义常量（除非有特殊需求）
const UserNotFound = "USER.NOT_FOUND"
err := &errors.BizError{Code: UserNotFound, Message: "用户不存在"}

3. 合理划分错误粒度

// ✅ 推荐：合理的粒度
errors.Business("USER").NotFound("用户不存在")
errors.Business("ORDER").NotFound("订单不存在")

// ❌ 不推荐：过细的粒度（维护成本高）
errors.Business("USER").Custom("NOT_FOUND_BY_ID", "通过ID未找到用户")
errors.Business("USER").Custom("NOT_FOUND_BY_EMAIL", "通过邮箱未找到用户")

4. 错误消息本地化

错误消息应该面向用户，考虑国际化需求：

// ✅ 推荐：用户友好的消息
errors.Business("USER").NotFound("用户不存在")

// ❌ 不推荐：技术性消息
errors.Business("USER").NotFound("User record not found in database")

5. 验证器注册

// 在 validators 包中定义和注册
package validators

func init() {
    // 快速失败模式（默认）- 适合大多数场景
    validation.RegisterValidator[CreateUserRequest](NewCreateUserValidator())
    
    // 全量验证模式 - 适合批量导入
    validation.RegisterValidator[BatchImportRequest](NewBatchImportValidator())
}

6. 统一错误处理

// 在 Controller 中统一处理错误
func (ctrl *BaseController) HandleServiceError(ctx *web.HttpContext, err error) web.IActionResult {
    if bizErr, ok := err.(*errors.BizError); ok {
        return ctx.BizError(bizErr)
    }
    
    // 记录未预期的错误
    log.Error().Err(err).Msg("Unexpected error")
    return ctx.InternalError("服务器错误")
}

错误码与 HTTP 状态码映射

框架会自动将业务错误码映射到合适的 HTTP 状态码：

错误码模式	HTTP 状态码	说明
`*.NOT_FOUND`	404	资源不存在
`*.ALREADY_EXISTS`	409	资源冲突
`*.PERMISSION_DENIED`	403	权限不足
`*.UNAUTHORIZED`	401	未授权
`.INVALID`	400	参数或状态无效
`*.EXPIRED`	410	资源已过期
`*.LOCKED`	423	资源已锁定
`*.LIMIT_EXCEEDED`	429	超出限制
其他	400	默认错误请求

如果自动映射不满足需求，可以使用 BizErrorWithStatus 手动指定状态码。

总结

CSGO 的错误处理系统设计理念：

框架负责框架的事：框架预定义验证、系统、HTTP 等框架级错误码
业务负责业务的事：业务通过构建器灵活创建业务错误码
提升开发体验：减少样板代码，专注业务逻辑
类型安全：充分利用 Go 的类型系统，编译时发现问题
统一响应格式：前后端对接更加规范

通过这套体系，您可以快速构建健壮、规范的 API 错误处理。

Documentation ¶

Index ¶

Constants
type Error
- func New(code string, message string, httpCode int) *Error
- func Newf(code string, httpCode int, format string, args ...any) *Error
type ErrorBuilder
type ErrorCategory
type Module
- func NewModule(prefix string) *Module

Constants ¶

View Source

const (

	// SystemInternalError 系统内部错误
	SystemInternalError = "SYSTEM.INTERNAL_ERROR"

	// SystemServiceUnavailable 服务不可用
	SystemServiceUnavailable = "SYSTEM.SERVICE_UNAVAILABLE"

	// SystemTimeout 系统超时
	SystemTimeout = "SYSTEM.TIMEOUT"

	// ValidationFailed 通用验证失败
	ValidationFailed = "VALIDATION.FAILED"

	// ValidationRequired 必填项为空
	ValidationRequired = "VALIDATION.REQUIRED"

	// ValidationMinLength 字符串长度小于最小值
	ValidationMinLength = "VALIDATION.MIN_LENGTH"

	// ValidationMaxLength 字符串长度大于最大值
	ValidationMaxLength = "VALIDATION.MAX_LENGTH"

	// ValidationLength 字符串长度不在指定范围
	ValidationLength = "VALIDATION.LENGTH"

	// ValidationMin 数值小于最小值
	ValidationMin = "VALIDATION.MIN"

	// ValidationMax 数值大于最大值
	ValidationMax = "VALIDATION.MAX"

	// ValidationRange 数值不在指定范围
	ValidationRange = "VALIDATION.RANGE"

	// ValidationEmail 邮箱格式不正确
	ValidationEmail = "VALIDATION.EMAIL"

	// ValidationUrl URL 格式不正确
	ValidationUrl = "VALIDATION.URL"

	// ValidationPattern 不匹配指定正则表达式
	ValidationPattern = "VALIDATION.PATTERN"

	// ValidationIn 值不在枚举列表中
	ValidationIn = "VALIDATION.IN"

	// ValidationNotIn 值在排除列表中
	ValidationNotIn = "VALIDATION.NOT_IN"

	// ValidationNotEmpty 集合不能为空
	ValidationNotEmpty = "VALIDATION.NOT_EMPTY"

	// ValidationMinCount 集合元素数量小于最小值
	ValidationMinCount = "VALIDATION.MIN_COUNT"

	// ValidationMaxCount 集合元素数量大于最大值
	ValidationMaxCount = "VALIDATION.MAX_COUNT"

	// ValidationInvalidInteger 无效的整数
	ValidationInvalidInteger = "VALIDATION.INVALID_INTEGER"

	// ValidationInvalidBoolean 无效的布尔值
	ValidationInvalidBoolean = "VALIDATION.INVALID_BOOLEAN"

	// ValidationInvalidNumber 无效的数字
	ValidationInvalidNumber = "VALIDATION.INVALID_NUMBER"

	// ValidationPositive 必须是正数
	ValidationPositive = "VALIDATION.POSITIVE"

	// ValidationNonNegative 不能是负数
	ValidationNonNegative = "VALIDATION.NON_NEGATIVE"

	// ValidationEnum 枚举值验证失败
	ValidationEnum = "VALIDATION.ENUM"

	// HttpBadRequest 错误的请求
	HttpBadRequest = "HTTP.BAD_REQUEST"

	// HttpUnauthorized 未授权
	HttpUnauthorized = "HTTP.UNAUTHORIZED"

	// HttpForbidden 禁止访问
	HttpForbidden = "HTTP.FORBIDDEN"

	// HttpNotFound 资源不存在
	HttpNotFound = "HTTP.NOT_FOUND"

	// HttpConflict 资源冲突
	HttpConflict = "HTTP.CONFLICT"

	// HttpMethodNotAllowed 方法不允许
	HttpMethodNotAllowed = "HTTP.METHOD_NOT_ALLOWED"

	// AuthTokenExpired 令牌已过期
	AuthTokenExpired = "AUTH.TOKEN_EXPIRED"

	// AuthTokenInvalid 令牌无效
	AuthTokenInvalid = "AUTH.TOKEN_INVALID"

	// AuthPermissionDenied 权限不足
	AuthPermissionDenied = "AUTH.PERMISSION_DENIED"

	// AuthCredentialsInvalid 凭证无效
	AuthCredentialsInvalid = "AUTH.CREDENTIALS_INVALID"
)

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type Error ¶

type Error struct {
	// contains filtered or unexported fields
}

Error 表示一个结构化的错误

func New ¶

func New(code string, message string, httpCode int) *Error

New 创建自定义错误

func Newf ¶

func Newf(code string, httpCode int, format string, args ...any) *Error

Newf 使用格式化消息创建自定义错误

func (*Error) AppendMsg ¶

func (e *Error) AppendMsg(suffix string) *Error

AppendMsg 追加消息（返回新实例）

func (*Error) Category ¶

func (e *Error) Category() ErrorCategory

Category 返回错误分类

func (*Error) Code ¶

func (e *Error) Code() string

Code 返回错误码

func (*Error) Details ¶

func (e *Error) Details() map[string]any

Details 返回详细信息

func (*Error) Error ¶

func (e *Error) Error() string

Error 实现 error 接口

func (*Error) HTTPCode ¶

func (e *Error) HTTPCode() int

HTTPCode 返回 HTTP 状态码

func (*Error) Message ¶

func (e *Error) Message() string

Message 返回错误消息

func (*Error) PrependMsg ¶

func (e *Error) PrependMsg(prefix string) *Error

PrependMsg 前置消息（返回新实例）

func (*Error) Unwrap ¶

func (e *Error) Unwrap() error

Unwrap 实现 Go 1.13+ 错误链支持

func (*Error) WithDetail ¶

func (e *Error) WithDetail(key string, value any) *Error

WithDetail 添加单个详细信息（返回新实例）

func (*Error) WithDetails ¶

func (e *Error) WithDetails(details map[string]any) *Error

WithDetails 批量添加详细信息（返回新实例）

func (*Error) WithHTTPCode ¶

func (e *Error) WithHTTPCode(code int) *Error

WithHTTPCode 设置 HTTP 状态码（返回新实例）

func (*Error) WithMsg ¶

func (e *Error) WithMsg(message string) *Error

WithMsg 覆盖错误消息（返回新实例）

func (*Error) WithMsgf ¶

func (e *Error) WithMsgf(format string, args ...any) *Error

WithMsgf 使用格式化字符串覆盖错误消息（返回新实例）

func (*Error) Wrap ¶

func (e *Error) Wrap(err error) *Error

Wrap 包装原始错误（返回新实例）

type ErrorBuilder ¶

type ErrorBuilder struct {
	// contains filtered or unexported fields
}

ErrorBuilder 错误码构建器

func (*ErrorBuilder) Msg ¶

func (b *ErrorBuilder) Msg(msg string) *Error

Msg 设置错误消息并返回 Error（默认 400 状态码）

func (*ErrorBuilder) MsgWithCode ¶

func (b *ErrorBuilder) MsgWithCode(msg string, httpCode int) *Error

MsgWithCode 设置错误消息和 HTTP 状态码

func (*ErrorBuilder) Msgf ¶

func (b *ErrorBuilder) Msgf(format string, args ...any) *Error

Msgf 使用格式化字符串设置错误消息

type ErrorCategory ¶

type ErrorCategory string

ErrorCategory 错误分类

const (
	CategoryBusiness   ErrorCategory = "BUSINESS"   // 业务错误
	CategorySystem     ErrorCategory = "SYSTEM"     // 系统错误
	CategoryValidation ErrorCategory = "VALIDATION" // 验证错误
	CategoryAuth       ErrorCategory = "AUTH"       // 认证授权错误
)

type Module ¶

type Module struct {
	// contains filtered or unexported fields
}

Module 表示一个错误模块，提供模块化的错误创建

func NewModule ¶

func NewModule(prefix string) *Module

NewModule 创建一个新的错误模块 prefix 将自动转换为大写，如 "user" -> "USER"

func (*Module) AlreadyExists ¶

func (m *Module) AlreadyExists(msg ...string) *Error

AlreadyExists 资源已存在（409）

func (*Module) Code ¶

func (m *Module) Code(code string) *ErrorBuilder

Code 创建自定义错误码构建器用法: module.Code("PAYMENT_FAILED").Msg("支付失败")

func (*Module) Conflict ¶

func (m *Module) Conflict(msg ...string) *Error

Conflict 资源冲突（409）

func (*Module) Custom ¶

func (m *Module) Custom(code string, msg string, httpCode int) *Error

Custom 创建完全自定义的错误

func (*Module) Customf ¶

func (m *Module) Customf(code string, httpCode int, format string, args ...any) *Error

Customf 使用格式化消息创建完全自定义的错误

func (*Module) Expired ¶

func (m *Module) Expired(msg ...string) *Error

Expired 资源已过期（410）

func (*Module) Internal ¶

func (m *Module) Internal(msg ...string) *Error

Internal 内部错误（500）

func (*Module) InvalidParam ¶

func (m *Module) InvalidParam(msg ...string) *Error

InvalidParam 参数无效（400）

func (*Module) InvalidStatus ¶

func (m *Module) InvalidStatus(msg ...string) *Error

InvalidStatus 状态无效（400）

func (*Module) LimitExceeded ¶

func (m *Module) LimitExceeded(msg ...string) *Error

LimitExceeded 超出限制（429）

func (*Module) Locked ¶

func (m *Module) Locked(msg ...string) *Error

Locked 资源已锁定（423）

func (*Module) NotFound ¶

func (m *Module) NotFound(msg ...string) *Error

NotFound 资源不存在（404）

func (*Module) OperationFailed ¶

func (m *Module) OperationFailed(msg ...string) *Error

OperationFailed 操作失败（400）

func (*Module) PermissionDenied ¶

func (m *Module) PermissionDenied(msg ...string) *Error

PermissionDenied 权限不足（403）

func (*Module) Prefix ¶

func (m *Module) Prefix() string

Prefix 返回模块前缀

func (*Module) ServiceUnavailable ¶

func (m *Module) ServiceUnavailable(msg ...string) *Error

ServiceUnavailable 服务不可用（503）

func (*Module) Unauthorized ¶

func (m *Module) Unauthorized(msg ...string) *Error

Unauthorized 未授权（401）

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

错误处理系统

🎯 核心特性

📖 目录

🚀 快速开始

1. 定义模块

2. 使用快捷方法（最常用）

3. 自定义错误码

🎨 Module 快捷方法

🔧 自定义错误码

基本用法

完全自定义

🔗 链式调用

添加详细信息

修改消息

包装底层错误

覆盖 HTTP 状态码

组合使用

🌐 Web 层集成

Controller 中使用

错误响应格式

HTTP 状态码映射

💡 最佳实践

1. 统一定义模块错误

2. Service 层返回错误

3. 根据业务逻辑返回不同错误

4. 渐进式错误构建

5. 错误链追踪

📚 完整 API 参考

Module 方法

Error 方法

ErrorBuilder 方法

🔄 迁移指南

从旧版本迁移

1. 替换 Business() 为 NewModule()

2. 替换 Code().Message() 为 Code().Msg()

3. BizError 改为 Error

4. 字段访问改为方法调用

🎉 优势总结

错误响应格式

验证错误响应

业务错误响应

验证错误

验证器示例

验证模式

快速失败模式（默认，推荐）

全量验证模式

最佳实践

1. 错误码命名规范

2. 优先使用构建器

3. 合理划分错误粒度

4. 错误消息本地化

5. 验证器注册

6. 统一错误处理

错误码与 HTTP 状态码映射

总结

Documentation ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

Types ¶

type Error ¶

func New ¶

func Newf ¶

func (*Error) AppendMsg ¶

func (*Error) Category ¶

func (*Error) Code ¶

func (*Error) Details ¶

func (*Error) Error ¶

func (*Error) HTTPCode ¶

func (*Error) Message ¶

func (*Error) PrependMsg ¶

func (*Error) Unwrap ¶

func (*Error) WithDetail ¶

func (*Error) WithDetails ¶

func (*Error) WithHTTPCode ¶

func (*Error) WithMsg ¶

func (*Error) WithMsgf ¶

func (*Error) Wrap ¶

1. 替换 `Business()` 为 `NewModule()`

2. 替换 `Code().Message()` 为 `Code().Msg()`

3. `BizError` 改为 `Error`