Go 语言通过 error 类型显式处理错误，需区分运行时错误（如文件不存在、网络超时，可恢复）和逻辑错误（如非法参数、状态不一致，反映代码缺陷）；前者应包装返回并支持重试，后者应尽早暴露，避免掩盖。
Go 语言中没有异常机制，所有错误都通过 error 类型显式返回和处理。区分“运行时错误”（如文件不存在、网络超时）和“逻辑错误”（如参数非法、状态不一致）是设计健壮程序的关键——前者通常可恢复、需重试或降级；后者往往反映代码缺陷，应尽早暴露、避免掩盖。
明确两类错误的边界与典型表现
运行时错误（External/Transient Errors）：源自外部依赖或环境不确定性，不可由当前函数逻辑完全规避。例如：
- os.Open("missing.txt") 返回 os.ErrNotExist
- http.Get("https://api.example.com") 返回超时或连接拒绝
- 数据库查询因网络抖动失败
逻辑错误（Internal/Invariant Violations）：违反程序预设前提、业务规则或数据一致性约束，属于开发阶段应发现的问题。例如：
- 调用函数时传入 nil 指针且文档明确要求非空
- 用户 ID 为负数，但业务规定 ID 必须 > 0
- 状态机从 Created 直接跳转到 Archived，跳过必要中间态
用不同方式建模和返回错误
对运行时错误，使用标准 errors.New 或 fmt.Errorf，必要时包装底层错误（用 %w）以保留调用链：
-
✅ 推荐：
return fmt.Errorf("fetch user %d from DB: %w", id, err) -
✅ 推荐：定义自定义错误类型（如
type TimeoutError struct{}），实现Error()和Timeout() bool方法，便于下游判断和分类处理 -
❌ 避免：将运行时错误“吞掉”并返回
nil，或转换成 panic
对逻辑错误，优先用 panic（配合 recover 在顶层捕获）或直接返回带清晰上下文的 error，但绝不隐藏：
-
✅ 推荐（开发/测试环境）：
if id —— 快速失败，暴露缺陷 -
✅ 推荐（生产环境需可控）：
if id ，并在日志中记录 stack trace（用debug.PrintStack()或第三方库） -
❌ 避免：用
fmt.Errorf("invalid ID")不带具体值，或仅写日志却不返回错误，导致调用方无法响应
分层处理：在合适的位置做决策
错误不应在每一层都“处理”，而应在最了解上下文的那一层决定如何应对：
立即学习“go语言免费学习笔记（深入）”；
- 底层（如 DB、HTTP 客户端）：只负责传播运行时错误，不做重试或 fallback，保持职责单一
- 中间服务层（如 UserService）：识别哪些运行时错误可重试（如临时网络失败）、哪些需降级（如缓存兜底）、哪些要转为用户友好提示（如 “账号不存在”）；对逻辑错误立即返回明确 error 或 panic
- 顶层（如 HTTP handler）：统一 recover panic，记录完整 trace；将运行时错误映射为标准 HTTP 状态码（503/404/400）；对逻辑错误 panic 视为严重缺陷，记录并告警
辅助工具提升可维护性
借助静态检查和约定降低误判概率：
- 用
golang.org/x/xerrors（或 Go 1.13+ 原生errors.Is/errors.As）做错误类型断言，避免字符串匹配 - 在函数签名或注释中明确标注“本函数可能返回以下运行时错误：xxx”，或“panic 当输入违反 XXX 不变量”
- 单元测试中覆盖逻辑错误路径（如传入非法参数），验证是否 panic 或返回预期 error
- CI 中启用
staticcheck检查未处理的 error（SA1019），但对已知可忽略的运行时错误（如io.EOF）加注释说明
