Errors
约 2018 字大约 7 分钟
2025-09-04
错误类型
声明错误的选项很少。 在选择最适合您的用例的选项之前,请考虑以下事项。
- 调用者是否需要匹配错误以便他们可以处理它? 如果是,我们必须通过声明顶级错误变量或自定义类型来支持
errors.Is或errors.As函数。 - 错误消息是否为静态字符串,还是需要上下文信息的动态字符串? 如果是静态字符串,我们可以使用
errors.New,但对于后者,我们必须使用fmt.Errorf或自定义错误类型。 - 我们是否正在传递由下游函数返回的新错误? 如果是这样,请参阅错误包装部分。
| 错误匹配? | 错误消息 | 指导 |
|---|---|---|
| No | static | errors.New |
| No | dynamic | fmt.Errorf |
| Yes | static | top-level var with errors.New |
| Yes | dynamic | custom error type |
例如, 使用 errors.New 表示带有静态字符串的错误。 如果调用者需要匹配并处理此错误,则将此错误导出为变量以支持将其与 errors.Is 匹配。
| 无错误匹配 | 错误匹配 |
|---|---|
| |
对于动态字符串的错误, 如果调用者不需要匹配它,则使用 fmt.Errorf, 如果调用者确实需要匹配它,则自定义 error。
| 无错误匹配 | 错误匹配 |
|---|---|
| |
请注意,如果您从包中导出错误变量或类型, 它们将成为包的公共 API 的一部分。
错误包装
如果调用其他方法时出现错误,通常有三种处理方式可以选择:
- 将原始错误原样返回
- 使用
fmt.Errorf搭配%w将错误添加进上下文后返回 - 使用
fmt.Errorf搭配%v将错误添加进上下文后返回
如果没有要添加的其他上下文,则按原样返回原始错误。 这将保留原始错误类型和消息。 这非常适合底层错误消息有足够的信息来追踪它来自哪里的错误。
否则,尽可能在错误消息中添加上下文 这样就不会出现诸如“连接被拒绝”之类的模糊错误, 您会收到更多有用的错误,例如“调用服务 foo:连接被拒绝”。
使用 fmt.Errorf 为你的错误添加上下文, 根据调用者是否应该能够匹配和提取根本原因,在 %w 或 %v 动词之间进行选择。
- 如果调用者应该可以访问底层错误,请使用
%w。 对于大多数包装错误,这是一个很好的默认值, 但请注意,调用者可能会开始依赖此行为。因此,对于包装错误是已知var或类型的情况,请将其作为函数契约的一部分进行记录和测试。 - 使用
%v来混淆底层错误。 调用者将无法匹配它,但如果需要,您可以在将来切换到%w。
在为返回的错误添加上下文时,通过避免使用"failed to"之类的短语来保持上下文简洁,当错误通过堆栈向上渗透时,它会一层一层被堆积起来:
| Bad | Good |
|---|---|
| |
| |
然而,一旦错误被发送到另一个系统,应该清楚消息是一个错误(例如err 标签或日志中的"Failed"前缀)。
另见 不要只检查错误,优雅地处理它们。
错误命名
对于存储为全局变量的错误值, 根据是否导出,使用前缀 Err 或 err。 请看指南 对于未导出的顶层常量和变量,使用_作为前缀。
var (
// 导出以下两个错误,以便此包的用户可以将它们与 errors.Is 进行匹配。
ErrBrokenLink = errors.New("link is broken")
ErrCouldNotOpen = errors.New("could not open")
// 这个错误没有被导出,因为我们不想让它成为我们公共 API 的一部分。我们可能仍然在带有错误的包内使用它。
errNotFound = errors.New("not found")
)对于自定义错误类型,请改用后缀 Error。
// 同样,这个错误被导出,以便这个包的用户可以将它与 errors.As 匹配。
type NotFoundError struct {
File string
}
func (e *NotFoundError) Error() string {
return fmt.Sprintf("file %q not found", e.File)
}
// 并且这个错误没有被导出,因为我们不想让它成为公共 API 的一部分。我们仍然可以在带有 errors.As 的包中使用它。
type resolveError struct {
Path string
}
func (e *resolveError) Error() string {
return fmt.Sprintf("resolve %q", e.Path)
}一次处理错误
当调用方从被调用方接收到错误时,它可以根据对错误的了解,以各种不同的方式进行处理。
其中包括但不限于:
- 如果被调用者约定定义了特定的错误,则将错误与
errors.Is或errors.As匹配,并以不同的方式处理分支 - 如果错误是可恢复的,则记录错误并正常降级
- 如果该错误表示特定于域的故障条件,则返回定义明确的错误
- 返回错误,无论是 wrapped 还是逐字逐句
无论调用方如何处理错误,它通常都应该只处理每个错误一次。例如,调用方不应该记录错误然后返回,因为its调用方也可能处理错误。
例如,考虑以下情况:
| Description | Code |
|---|---|
Bad: 记录错误并将其返回 堆栈中的调用程序可能会对该错误采取类似的操作。这样做会在应用程序日志中造成大量噪音,但收效甚微。 | |
Good: 将错误换行并返回 堆栈中更靠上的调用程序将处理该错误。使用 | |
Good: 记录错误并正常降级 如果操作不是绝对必要的,我们可以通过从中恢复来提供降级但不间断的体验。 | |
Good: 匹配错误并适当降级 如果被调用者在其约定中定义了一个特定的错误,并且失败是可恢复的,则匹配该错误案例并正常降级。对于所有其他案例,请包装错误并返回。 堆栈中更靠上的调用程序将处理其他错误。 | |
更新日志
a059b-新增Uber的Go语言规范于
