Documentation
¶
Overview ¶
Package apperr 是携带 fleetly 错误信封的应用错误类型。
错误信封契约（发布专项 §2.7、proto/fleetly/shared/v1/error.proto）： {code, message, stage, deployment_id, suggestion, context, docs} 七字段； code 必须来自 errcode 注册表（唯一真源，只增不复用）。gRPC 侧以 status detail（*sharedv1.ErrorResponse）携带信封；REST 侧由 gateway HTTPErrorHandler 解出信封渲染 snake_case JSON。
兜底取舍（待 T0.5 冻结确认）：无信封 detail 的错误（传输层/框架层错误） 退化为「code 留空串 + message 保底」的通用信封，HTTP 状态由 grpc code 机械映射——不发明文档外码、不挪用既有码语义。
Index ¶
- Constants
- func EnvelopeFromGRPCStatus(st *status.Status) (*sharedv1.ErrorResponse, int)
- func GRPCCodeToHTTP(c codes.Code) int
- func HTTPToGRPCCode(httpStatus int) codes.Code
- type Error
- func (e *Error) Code() string
- func (e *Error) Context() map[string]string
- func (e *Error) Envelope() *sharedv1.ErrorResponse
- func (e *Error) Error() string
- func (e *Error) GRPCStatus() *status.Status
- func (e *Error) HTTPStatus() int
- func (e *Error) Is(target error) bool
- func (e *Error) Message() string
- func (e *Error) ToGRPCStatus() *status.Status
- func (e *Error) Unwrap() error
- func (e *Error) WithCause(cause error) *Error
- func (e *Error) WithContext(key, value string) *Error
- func (e *Error) WithDeploymentID(id string) *Error
- func (e *Error) WithStage(stage string) *Error
- func (e *Error) WithSuggestion(s string) *Error
Constants ¶
const RedactedDegradedMessage = "internal error — see server logs for details (correlate by error code and timestamp)"
RedactedDegradedMessage 是 B1（出站字节出口收口）对内部类 grpc code 的 退化信封固定对外文案：无信封 detail 且 code ∈ {Unknown, Internal, FailedPrecondition} 时替换 status 原文——原文可能携带 SQL 片段、绝对 路径、git stderr 等内部细节，只进服务端 slog（gateway 错误处理器处落 日志，凭 grpc code 与时间戳关联排障）。
Variables ¶
This section is empty.
Functions ¶
func EnvelopeFromGRPCStatus ¶
func EnvelopeFromGRPCStatus(st *status.Status) (*sharedv1.ErrorResponse, int)
EnvelopeFromGRPCStatus 是 gateway 错误链的统一出口：有信封 detail 时 返回信封与 HTTP 状态——注册码（code 非空）按注册表映射；**空码 detail 信封**（X-5：api 层业务冲突通道主动构造的退化信封，如 conflict() 的 409）按传输 grpc code 机械映射（GRPCCodeToHTTP）——HTTPStatus 对空码 无从判定（回落 500），而空码信封的存在本身即证明 message 是服务端 构造的业务文案、不是底层错误透传，HTTP 语义由构造方选定的 grpc code 承载。无 detail 走退化信封——code 留空串（不发明文档外码、不挪用既有 码语义），HTTP 状态由 grpc code 机械映射。B1：内部类 code 的 message 替换为固定文案（原文由 gateway 错误处理器落 slog），业务码 （InvalidArgument/NotFound 等）原文保留——**脱敏判定只认「无 detail」 形态**（底层错误透传不携带信封 detail），携带 detail 的空码信封不脱敏。
func GRPCCodeToHTTP ¶
GRPCCodeToHTTP 是 HTTPToGRPCCode 的传输侧逆向映射（gateway 对无信封 错误的兜底；与 torchwood grpcCodeToHTTP 同形）。
func HTTPToGRPCCode ¶
HTTPToGRPCCode 把注册表 HTTP 状态机械映射为 gRPC code（信封承载契约， 传输 code 仅求稳定可逆；409/410 统一 FailedPrecondition——冲突/前置失效 语义，细分由信封 code 表达）。
Types ¶
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error 是携带完整错误信封的应用错误。零值不可用；经 New/With* 构造。
func FromGRPCStatus ¶
FromGRPCStatus 从 gRPC status 还原 *Error：找到 *sharedv1.ErrorResponse detail 时返回 (err, true)——注册码恢复注册表默认 suggestion/docs（detail 内值优先）；无 detail 返回 (nil, false)，由调用方走退化信封。
func New ¶
New 构造注册表内错误码的应用错误：suggestion/docs 取注册表默认 （可经 WithSuggestion 覆盖文案）。code 未注册时 panic（构造期 fail-fast， 保证信封 code 恒为注册表内码）；W_ 警告码同样 panic——警告是资源/计划 上的标注（HTTP=0），永不作为错误返回。
func (*Error) Envelope ¶
func (e *Error) Envelope() *sharedv1.ErrorResponse
Envelope 构造错误信封 proto（七字段；空值字段由 marshaler 语义决定 是否输出）。
func (*Error) GRPCStatus ¶
GRPCStatus 使 *Error 直接满足 gRPC 传输的错误接口（grpc status 包对 实现 GRPCStatus() *status.Status 的错误原样采用，detail 随之上线）， handler 可直接 return *Error。
func (*Error) HTTPStatus ¶
HTTPStatus 返回该错误的默认 HTTP 状态：注册码按注册表映射，无码兜底 500（退化信封在 gateway 侧另经 GRPCCodeToHTTP 机械映射）。
func (*Error) ToGRPCStatus ¶
ToGRPCStatus 转为携带信封 detail 的 gRPC status：grpc code 由注册表 HTTP 映射机械推导，detail 为 *sharedv1.ErrorResponse。
func (*Error) WithContext ¶
WithContext 附加结构化上下文键值（machine-readable，同名覆盖）。
func (*Error) WithDeploymentID ¶
WithDeploymentID 关联部署 ID。
func (*Error) WithSuggestion ¶
WithSuggestion 覆盖注册表默认建议文案。
Source Files