Rene Nochebuena
3cc36801a1
Structured application errors with typed codes, cause chaining, key-value context fields, and zero-import logz enrichment bridge. What's included: - `*Err` type implementing error, errors.Unwrap, json.Marshaler, ErrorCode(), and ErrorContext() - Twelve typed Code constants aligned with gRPC canonical status names - New / Wrap factory constructors plus InvalidInput / NotFound / Internal convenience constructors - Builder methods WithContext and WithError for attaching structured fields and causes - Duck-typed ErrorCode() / ErrorContext() bridge so logz auto-enriches log records without an import Tested-via: todo-api POC integration Reviewed-against: docs/adr/
44 lines
1.3 KiB
Go
44 lines
1.3 KiB
Go
/*
|
|
Package xerrors provides structured application errors with stable machine-readable
|
|
codes, human-readable messages, cause chaining, and key-value context fields.
|
|
|
|
Each error carries a [Code] that maps to a well-known category (invalid input,
|
|
not found, internal, etc.) and is stable across versions — safe to persist,
|
|
transmit in API responses, or switch on programmatically.
|
|
|
|
# Basic usage
|
|
|
|
err := xerrors.New(xerrors.ErrNotFound, "user not found")
|
|
|
|
// With cause chaining
|
|
err := xerrors.Wrap(xerrors.ErrInternal, "failed to query database", dbErr)
|
|
|
|
// Convenience constructors
|
|
err := xerrors.NotFound("user %s not found", userID)
|
|
|
|
// Builder pattern
|
|
err := xerrors.New(xerrors.ErrInvalidInput, "validation failed").
|
|
WithContext("field", "email").
|
|
WithContext("tag", "required")
|
|
|
|
# Cause chaining
|
|
|
|
[Err.Unwrap] is implemented, so [errors.Is] and [errors.As] walk the full
|
|
cause chain:
|
|
|
|
if errors.Is(err, io.ErrUnexpectedEOF) { ... }
|
|
|
|
var e *xerrors.Err
|
|
if errors.As(err, &e) {
|
|
log.Println(e.Code())
|
|
}
|
|
|
|
# Structured logging (duck-typing bridge)
|
|
|
|
[Err.ErrorCode] and [Err.ErrorContext] satisfy the private interfaces that logz
|
|
defines internally. Passing an *Err to logger.Error automatically enriches the
|
|
log record with error_code and context fields — without xerrors importing logz
|
|
or logz importing xerrors.
|
|
*/
|
|
package xerrors
|