ecode

README

1. ginx/ecode 文档与测试

ginx/ecode

ecode 是一个通用错误码定义与状态码映射库。它实现了 "机制与策略分离" 的设计思想，并采用 "约定优于配置" 的策略来简化开发。

✨ 特性

• 标准结构：定义了统一的 Error 结构体 (Code, Msg, Details)。
• 链式调用：支持 WithDetails、WithCause 等链式方法，且保证不可变性。
• 智能状态码映射：
  • Level 1 (注册)：手动注册的 HTTP 状态码优先级最高 (如 404, 403)。
  • Level 2 (约定)：
    • 2xxxxxx (业务错误) -> 自动映射为 HTTP 200。
    • 1xxxxxx (系统错误) -> 自动映射为 HTTP 500。
  • Level 3 (兜底)：其他情况默认为 HTTP 500。

📦 安装

go get -u github.com/einscat/ab-go

📖 使用指南

1. 定义错误

package ecode

var (
    // 自动映射为 HTTP 200 (因为是 2 开头)
    UserDuplicate = New(2001001, "用户已存在")
    
    // 自动映射为 HTTP 500 (因为是 1 开头)
    DbError       = New(1001001, "数据库连接失败")

    // 特殊错误，稍后需要注册
    AuthFailed    = New(2001004, "认证失败")
)

2. 注册特殊状态码 (可选)

在业务模块的 init() 中注册那些不希望遵循默认规则的错误。

import "net/http"

func init() {
    // 强制指定 AuthFailed 返回 401，而不是默认的 200
    RegisterStatus(AuthFailed.Code, http.StatusUnauthorized)
}

3. 携带详情

// 返回一个新的 error 实例，包含具体的表单错误信息
err := InvalidParams.WithDetails(map[string]string{
    "email": "格式错误",
})

Documentation

Index

• Variables
• func GetStatus(code int) int
• func RegisterStatus(code int, httpStatus int)
• type Error
  • func New(code int, msg string) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
  • func (e *Error) WithCause(err error) *Error
  • func (e *Error) WithDetails(details any) *Error
  • func (e *Error) WithMsg(msg string) *Error

Variables

var (
	Success       = New(0, "成功")
	ServerError   = New(10000000, "服务内部错误") // 1开头 -> 自动 500
	InvalidParams = New(10000001, "参数错误")   // 1开头 -> 自动 500
	// 下面这些需要特殊对待，所以需要手动注册
	NotFound     = New(10000002, "资源不存在")
	Unauthorized = New(10000003, "未授权")
	Forbidden    = New(10000004, "禁止访问")
	TooManyReq   = New(10000007, "请求过多")
)

Functions

func GetStatus

func GetStatus(code int) int

GetStatus 核心方法：获取业务码对应的 HTTP 状态码

func RegisterStatus

func RegisterStatus(code int, httpStatus int)

RegisterStatus 手动注册业务码对应的 HTTP 状态码 场景：用于注册 401, 403, 404 等特殊状态

Types

type Error

type Error struct {
	Code    int    `json:"code"`
	Msg     string `json:"msg"`
	Details any    `json:"details,omitempty"`
	// contains filtered or unexported fields
}

Error 标准业务错误结构

func New

func New(code int, msg string) *Error

New 构造函数

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap 支持 errors.Is/As

func (*Error) WithCause

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

WithCause 链式调用：记录底层错误 (用于日志，不返回给前端)

func (*Error) WithDetails

func (e *Error) WithDetails(details any) *Error

WithDetails 链式调用：添加详情 (返回新实例，保证不可变性)

func (*Error) WithMsg

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

WithMsg 链式调用：临时修改提示语