示例结构

package errs

import (
	"net/http"

	brickserrs "github.com/cristiano-pacheco/bricks/pkg/errs"
)

var (
	// ErrProfileValidationFailed 在个人资料验证失败时返回。
	ErrProfileValidationFailed = brickserrs.New(
		"PROFILE_01",
		"profile validation failed",
		http.StatusBadRequest,
		nil,
	)
	// ErrProfileNotFound 在未找到个人资料时返回。
	ErrProfileNotFound = brickserrs.New("PROFILE_02", "profile not found", http.StatusNotFound, nil)
)

// NewProfileValidationError 返回一个包含字段级详细信息的结构化验证错误。
func NewProfileValidationError(details []brickserrs.Detail) *brickserrs.Error {
	return brickserrs.New(
		ErrProfileValidationFailed.Code,
		ErrProfileValidationFailed.Message,
		ErrProfileValidationFailed.Status,
		details,
	)
}

生成步骤

1. 确定错误详情：
   • 目标模块（例如：catalog、profile、ai、export）
   • 错误变量名（ErrProfileNotFound）
   • 小写消息（"profile not found"）
   • HTTP 状态码（http.StatusNotFound）
2. 查找下一个代码：
   • 打开 internal/modules/<module>/errs/errs.go
   • 提取该模块前缀的现有代码
   • 分配下一个可用的顺序代码：
     • 个位数补零：CATALOG_01、CATALOG_02、...、CATALOG_09
     • 两位数不补零：CATALOG_10、CATALOG_11、...
   • 保持模块内代码的唯一性
3. 添加新错误：
   • 插入到模块的 var (...) 代码块中
   • 保持文件中使用的领域分组顺序
   • 当文件中已有注释时，添加简短的文档注释
4. 如果需要，添加辅助构造函数：
   • 当错误是携带字段级详细信息的验证错误时，添加一个 NewXxxValidationError(details []brickserrs.Detail) *brickserrs.Error 函数
   • 重用预定义变量的 .Code、.Message 和 .Status 字段
5. 验证使用路径：
   • 确保新的/更新的用例、验证器、处理器或枚举构造函数返回新的类型化错误
   • 当存在类型化的模块错误时，不要从业务流中返回原始的 errors.New(...)
6. 更新翻译（强制）：
   • 每个新的自定义错误必须在 locales/en.json 的 "errors" 键下添加一个翻译条目
   • 使用错误代码作为键，并使用正确大写、面向用户的句子作为值："PROFILE_02": "Profile not found"
   • 如果存在其他区域设置文件（例如 locales/pt_BR.json），也在其中添加相同的键
   • 保持所有区域设置文件中的翻译键和结构一致
   • 在没有相应区域设置更新的情况下，不要合并新的自定义错误

命名约定

• 变量：Err + 清晰的领域短语（PascalCase）
  • 示例：ErrProfileNotFound、ErrAIGenerationFailed
• 代码：<MODULE>_<NN>
  • CATALOG_09、EXPORT_15、AI_07
  • 始终至少 2 位数字；个位数补零
• 消息：
  • 在 brickserrs.New() 中全部小写——区域设置文件（locales/en.json）提供面向用户的大写形式
  • 简短且具体，没有尾随标点符号
  • 示例："profile not found"、"invalid prompt type"、"ai provider unavailable"
• HTTP 状态码：
  • 验证错误：http.StatusBadRequest
  • 认证失败：http.StatusUnauthorized / http.StatusForbidden
  • 资源缺失：http.StatusNotFound
  • 冲突：http.StatusConflict
  • 速率限制：http.StatusTooManyRequests
  • 上游/AI 失败：http.StatusBadGateway
  • 容量/可用性：http.StatusServiceUnavailable
  • 基础设施/内部失败：http.StatusInternalServerError

实现检查清单

• 打开目标文件 internal/modules/<module>/errs/errs.go
• 计算下一个唯一的模块代码（补零的 2 位数字格式）
• 使用 brickserrs.New(...) 添加导出的 Err... 变量
• 使用全小写的消息字符串
• 匹配现有的领域分组排序风格
• 确保消息和状态码与领域行为一致
• 如果是验证错误，添加 NewXxxValidationError(details []brickserrs.Detail) 辅助函数
• 在调用代码中，将原始的 error 返回替换为类型化的 errs.Err...（如果适用）
• 在 locales/en.json 的 "errors" 下为新错误添加翻译，使用正确的句子大小写值
• 在每个其他现有的区域设置文件（例如 locales/pt_BR.json）中添加相同的翻译键
• 运行 make lint 以捕获样式和静态分析问题
• 运行 make nilaway 以确保没有引入空指针解引用

使用模式

if input.Phone == "" {
	return errs.ErrPhoneNumberRequired
}

if profile == nil {
	return errs.ErrProfileNotFound
}

关键规则

• 没有独立函数：当文件包含一个带有方法的结构体时，不要添加独立函数。应使用该结构体的私有方法。
• 不要创建新的错误包；使用模块本地的 internal/modules/<module>/errs
• 不要在同一模块内重复使用代码
• 当存在类型化的领域错误时，不要将持久化或基础设施特定的原始错误返回到传输层
• 一旦错误消息对外暴露，应保持稳定，除非接受迁移/兼容性影响
• 每个新的自定义错误都需要在 locales/en.json 和所有其他现有区域设置文件中添加区域设置条目
• brickserrs.New() 中的消息始终为小写；面向用户的大写形式存在于区域设置文件中

每周安装数

1

仓库

cristiano-pache…ai-rules

首次出现

今天

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1

Example Structure

package errs

import (
	"net/http"

	brickserrs "github.com/cristiano-pacheco/bricks/pkg/errs"
)

var (
	// ErrProfileValidationFailed is returned when profile validation fails.
	ErrProfileValidationFailed = brickserrs.New(
		"PROFILE_01",
		"profile validation failed",
		http.StatusBadRequest,
		nil,
	)
	// ErrProfileNotFound is returned when the profile is not found.
	ErrProfileNotFound = brickserrs.New("PROFILE_02", "profile not found", http.StatusNotFound, nil)
)

// NewProfileValidationError returns a structured validation error with field-level details.
func NewProfileValidationError(details []brickserrs.Detail) *brickserrs.Error {
	return brickserrs.New(
		ErrProfileValidationFailed.Code,
		ErrProfileValidationFailed.Message,
		ErrProfileValidationFailed.Status,
		details,
	)
}

Generation Steps

1. Identify error details :

   • Target module (e.g., catalog, profile, ai, export)
   • Error variable name (ErrProfileNotFound)
   • Lowercase message ("profile not found")
   • HTTP status (http.StatusNotFound)

2. Find the next code :

   • Open internal/modules/<module>/errs/errs.go
   • Extract existing codes for that module prefix
   • Allocate the next available sequential code:
     • Single digits are zero-padded: CATALOG_01, CATALOG_02, ..., CATALOG_09
     • Double digits are not padded: CATALOG_10, CATALOG_11, ...
   • Keep code uniqueness inside the module

3. Add the new error :

   • Insert into the module var (...) block
   • Keep domain-group ordering used by the file
   • Add a short doc comment when comments are already present in the file

4. Add a helper constructor if needed :

   • When the error is a validation error that carries field-level details, add a NewXxxValidationError(details []brickserrs.Detail) *brickserrs.Error function
   • Reuse the pre-defined variable's .Code, .Message, and .Status fields

5. Validate usage path :

   • Ensure new/updated usecases, validators, handlers, or enum constructors return the new typed error
   • Do not return raw errors.New(...) from business flows when a typed module error exists

6. Update translations (mandatory) :

   • Every new custom error must add a translation entry in locales/en.json under the "errors" key
   • Use the error code as key and a properly capitalized, user-facing sentence as value: "PROFILE_02": "Profile not found"
   • If additional locale files exist (for example locales/pt_BR.json), add the same key there too
   • Keep translation keys and structure consistent across all locale files
   • Do not merge a new custom error without the corresponding locale updates

Naming Conventions

• Variable : Err + clear domain phrase in PascalCase
  • Example: ErrProfileNotFound, ErrAIGenerationFailed
• Code : <MODULE>_<NN>
  • CATALOG_09, EXPORT_15, AI_07
  • Always at least 2 digits; single digits are zero-padded
• Message :
  • All lowercase in brickserrs.New() — the locale file (locales/en.json) provides the user-facing capitalized form
  • Short and specific, no trailing punctuation
  • Examples: "profile not found", "invalid prompt type", "ai provider unavailable"
• HTTP status :
  • Validation errors: http.StatusBadRequest
  • Auth failures: http.StatusUnauthorized / http.StatusForbidden
  • Missing resources: http.StatusNotFound
  • Conflicts: http.StatusConflict
  • Rate limit: http.StatusTooManyRequests
  • Upstream/AI failures: http.StatusBadGateway
  • Capacity/availability: http.StatusServiceUnavailable
  • Infra/internal failures: http.StatusInternalServerError

Implementation Checklist

• Open target internal/modules/<module>/errs/errs.go
• Compute next unique module code (zero-padded 2-digit format)
• Add exported Err... variable with brickserrs.New(...)
• Use all-lowercase message string
• Match existing domain-group ordering style
• Ensure message and status align with domain behavior
• Add NewXxxValidationError(details []brickserrs.Detail) helper if it is a validation error
• Replace raw error returns in calling code with typed errs.Err... where applicable
• Add translation for the new error in locales/en.json under "errors" with proper sentence-case value
• Add the same translation key in every other existing locale file (e.g., locales/pt_BR.json)
• Run make lint to catch style and static analysis issues
• Run make nilaway to ensure no nil pointer dereferences are introduced

Usage Pattern

if input.Phone == "" {
	return errs.ErrPhoneNumberRequired
}

if profile == nil {
	return errs.ErrProfileNotFound
}

Critical Rules

• No standalone functions : When a file contains a struct with methods, do not add standalone functions. Use private methods on the struct instead.
• Do not create a new error package; use module-local internal/modules/<module>/errs
• Do not duplicate codes within the same module
• Do not return persistence or infrastructure-specific raw errors to transport when a typed domain error exists
• Keep error messages stable once exposed, unless migration/compatibility impact is accepted
• Every new custom error requires locale entries in locales/en.json and all other existing locale files
• Messages in brickserrs.New() are always lowercase; user-facing capitalization lives in the locale file

Weekly Installs

1

Repository

cristiano-pache…ai-rules

First Seen

Today

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

zencoder1

amp1

cline1

openclaw1

opencode1

cursor1