errors

errors —— 统一业务错误码

gobase 错误码提供极简的业务错误载体：两个字段（code + msg）+ 一个翻译查询接口 Message(code, lang)，面向 gRPC / HTTP 统一使用。

核心 API

// 结构体——字段不导出，通过 getter 访问，全局变量不可变
// 实现 error 接口，errors.Is 按业务码比较

// 创建错误——msg 自动从 i18n 填充中文
err := errors.New(errors.CodeNotFound)
err := errors.ErrNotFound // 全局变量，直接使用

// 查翻译——不创建错误对象，纯查询
msg := errors.Message("1003", i18n.LangZh) // "资源不存在"
msg := errors.Message("1003", i18n.LangEn) // "Resource not found"

错误码定义

码段划分

所有错误码为 string 类型，全部由 gobase 内置（业务禁止自定义/注册新码）：

通用错误码

业务域错误码

每个码都有对应的全局错误变量（ErrInternal、ErrNotFound、ErrUserNotFound 等），直接使用，不可变。

BizError

结构体

// 字段不导出，通过 GetCode()/GetMessage() 访问
// 全局变量 ErrXxx 不可变，多 goroutine 安全

方法

使用方式

// 创建——msg 由 i18n 自动填充中文
err := errors.New(errors.CodeNotFound)
err := errors.ErrNotFound         // 全局变量，直接使用
err := errors.ErrUserNotFound     // 每个码都有对应变量

// 错误判断
if errors.Is(err, errors.ErrNotFound) {
    // 资源不存在
}

// 读取 code/msg（通过 getter）
code := err.GetCode()     // "1003"
msg := err.GetMessage()   // "资源不存在"

Message —— 按 code + 语言查翻译

对外提供的翻译查询接口，不创建错误对象：

// 查翻译
msg := errors.Message("1003", i18n.LangZh) // "资源不存在"
msg := errors.Message("1003", i18n.LangEn) // "Resource not found"

// 查找链：指定语言 → 默认语言（zh-CN）→ CodeUnknown 兜底 → 原始 code
msg := errors.Message("99999", i18n.LangZh) // "未知错误"
msg := errors.Message("99999", i18n.LangEn) // "Unknown error"

语言常量（定义在 i18n 包，全仓库直接使用）：

翻译（i18n）体系

默认翻译

gobase 通过 go:embed 内嵌全部 48 个错误码的中英文翻译（i18n/default/zh-CN.po + en-US.po），开箱即用，无需初始化。

.po 文件格式

自定义的 key-value 行格式，key 为首个空格前内容，value 为之后内容：

0 成功
1001 系统内部错误
1003 资源不存在
1999 未知错误
4001 用户不存在

服务覆盖翻译

服务无需修改 gobase，只需在工作目录下创建 i18n/ 目录，按 code 键 覆盖即可：

your-service/
├── i18n/
│   ├── zh-CN.po
│   └── en-US.po
└── main.go

# i18n/zh-CN.po —— 只写需要覆盖的码
1001 服务器开小差了，请稍后重试
4001 该用户不存在哦

查找链

Message(code, lang):
  1. i18n.Lookup(lang, code) → 嵌入默认 + 服务文件叠加
  2. i18n.Lookup(lang, CodeUnknown) → 兜底文案
  3. 返回原始 code 字符串

使用示例

package service

import (
    "errors"
    gobaseErrors "github.com/qkja/gobase/errors"
)

func (s *Service) CreateUser(ctx context.Context, req *pb.CreateUserReq) (*pb.CreateUserResp, error) {
    if req.Username == "" {
        return nil, gobaseErrors.ErrInvalidArgument
    }

    exists, err := s.repo.ExistsByUsername(ctx, req.Username)
    if err != nil {
        return nil, gobaseErrors.ErrInternal
    }
    if exists {
        return nil, gobaseErrors.ErrUserUsernameExists
    }

    return &pb.CreateUserResp{}, nil
}

// 按请求语言返回翻译
func msgByLang(code, acceptLang string) string {
    lang := i18n.LangZh
    if acceptLang == "en" {
        lang = i18n.LangEn
    }
    return gobaseErrors.Message(code, lang)
}

设计约束

目录结构

errors/
├── code.go          # 错误码常量 + 便捷构造函数
├── code_test.go     # New / Message / ErrXxx 测试
├── errors.go        # BizError 结构体 + Message 查询
├── errors_test.go   # Error() / Is / GetCode / GetMessage 测试
└── README.md        # 本文档

i18n/
├── i18n.go          # InitI18N / T() / Tf() 全局翻译 API
├── datamap.go       # Lookup() + embed 默认 .po + 服务文件叠加
└── default/
    ├── zh-CN.po     # go:embed 内嵌中文默认翻译（48 条）
    └── en-US.po     # go:embed 内嵌英文默认翻译（48 条）