在 go 中，仅被单一函数返回的自定义错误类型应定义在该函数所在的同一包内，无需单独拆分或提升到公共包；这是最符合封装性、可维护性和 go 惯例的做法。
在 go 中，仅被单一函数返回的自定义错误类型应定义在该函数所在的同一包内，无需单独拆分或提升到公共包；这是最符合封装性、可维护性和 go 惯例的做法。
Go 强调“最小暴露”与“就近定义”的设计哲学：错误类型本质上是函数契约的一部分，其语义和生命周期应与所服务的函数保持一致。若某个 ErrInvalidInput 或 ErrTimeoutExceeded 仅由 ParseConfig() 函数返回，且不被其他包或本包内其他函数使用，那么它就应当作为 config 包的私有实现细节存在——通常定义在同一个 .go 文件中（或至少同包的 errors.go 文件里），并以小写字母开头（如 errInvalidFormat）以限制作用域。
✅ 推荐做法示例：
// config/config.go
package config
import "fmt"
type ParseError struct {
Reason string
}
func (e *ParseError) Error() string {
return fmt.Sprintf("config parse error: %s", e.Reason)
}
func ParseConfig(data []byte) (map[string]string, error) {
if len(data) == 0 {
return nil, &ParseError{Reason: "empty config data"}
}
// ... parsing logic
return result, nil
}调用方可通过类型断言精准识别：
cfg, err := config.ParseConfig(b)
if err != nil {
var parseErr *config.ParseError
if errors.As(err, &parseErr) {
log.Printf("Parse-specific error: %v", parseErr.Reason)
return handleParseFailure()
}
return handleErrorGeneric(err)
}⚠️ 注意事项：
- 避免过早抽象：不要因“未来可能复用”而提前将错误类型移入独立包或 errors 子包——这会增加耦合，违背单一职责；待真正跨包复用时再重构更安全。
- 慎用导出类型：若错误需被外部包检查（如提供 IsParseError(err) 辅助函数），才导出类型（首字母大写），否则优先使用未导出类型 + errors.Is/errors.As 配合 fmt.Errorf(..., &err) 包装。
- 命名清晰、职责单一：错误类型名应体现语义（如 ValidationError），而非技术实现（如 CustomError）；一个函数对应一类错误即可，勿堆砌多个相似类型。
总结：Go 的错误组织不是“分类学”，而是“契约映射”。把错误类型放在它所属行为的同一包中，既是代码可读性的保障，也是 Go 工程实践成熟度的体现。
