README
¶
errorsx
Go 1.25 向けの軽量エラーライブラリ。標準 errors.Is/As/Join に準拠しつつ、
「生成時のみスタック取得＋遅延展開」「安全/開発者メッセージの二層」「定義済みエラーにメタを紐付け」
「ミドルウェアで一括 WithContext」「チェーン可能オプション」を提供します。
使い分け（最短で覚える版）
| やりたいこと | 使うもの | 補足 |
|---|---|---|
| 新規エラーを作る（スタック取得） | New("dbg", opts...) |
メッセージはここで付ける |
| 既存エラーを包む（構造付け） | Wrap(err, opts...) |
スタックは最初の1回だけ取得、Definition既定も適用 |
| 1行で包み＋メッセージ付与 | WrapMsg(err, "dbg", opts...) / Wrapf(err, "fmt %s", v) |
実運用で一番ラク |
| 文脈だけ追記（スタック不要） | Annotate(err, "dbg", opts...) |
causeはそのまま、説明だけ足す |
| コードやHTTP/gRPCを定義 | Define("CODE", Definition{...}) |
いわゆるセンチネル定義 |
| コンテキスト情報を入れる | WithContext(ctx) |
ミドルウェア境界で1回Wrapと併用 |
| 追加情報を付ける | WithMetadata/WithCode/WithHTTPStatus/WithGrpcStatus |
チェーン可能 |
ポイント:
- メッセージは基本
WrapMsg/WrapfかAnnotateで。Wrapは構造付け専用。 - Definition で決めた
Code/HTTP/GRPC/Publicは Wrap/Annotate 時に不足分へ自動適用。
クイックスタート
package main
import (
"context"
"fmt"
"errorsx"
"google.golang.org/grpc/codes"
)
// 定義済みエラー（1行）
var ErrUserNotFound = errorsx.Define("USER_NOT_FOUND", errorsx.Definition{
HTTP: 404,
GRPC: codes.NotFound,
Public: "対象のユーザーは存在しません",
})
func repo(id string) error {
if id == "" {
return errorsx.Annotate(ErrUserNotFound, "empty id", errorsx.WithMetadata("id", id))
}
return errorsx.Wrap(ErrUserNotFound, errorsx.WithMetadata("id", id))
}
func handler(ctx context.Context) error {
if err := repo("123"); err != nil {
// 境界で一括文脈付与
return errorsx.Wrap(err, errorsx.WithContext(ctx))
}
return nil
}
func main() {
err := handler(context.Background())
fmt.Println(err)
}
API 概要
// 生成/包み/注釈
func New(debugMsg string, opts ...Option) error
func Wrap(err error, opts ...Option) error
func WrapMsg(err error, debugMsg string, opts ...Option) error
func Wrapf(err error, format string, args ...any) error
func Annotate(err error, debugMsg string, opts ...Option) error
// オプション
func WithPublicMessage(s string) Option
func WithCode(c string) Option
func WithHTTPStatus(s int) Option
func WithGrpcStatus(c codes.Code) Option
func WithMetadata(k string, v any) Option
func WithContext(ctx context.Context) Option
// 定義済みエラー
type Definition struct {
Code string
HTTP int
GRPC codes.Code
Public string
}
func RegisterDefinition(defErr error, def Definition)
func Define(code string, def Definition) error
// レンダリング
func ToHTTPProblem(err error) *Problem // RFC7807
func ToGRPCStatus(err error) *status.Status // gRPC status + errdetails
スタックトレース
- スタックは
New/Wrap時に一度だけ PC を採取し、整形はResolveFrames
Documentation
¶
Index ¶
- func Annotate(err error, debugMsg string, opts ...Option) error
- func Define(code string, def Definition) error
- func New(debugMsg string, opts ...Option) error
- func RegisterContextExtractor(f func(context.Context) map[string]any)
- func RegisterDefinition(defErr error, def Definition)
- func ToGRPCStatus(err error) *status.Status
- func Wrap(err error, opts ...Option) error
- func WrapMsg(err error, debugMsg string, opts ...Option) error
- func Wrapf(err error, format string, args ...any) error
- type Definition
- type E
- func (e *E) Code() string
- func (e *E) DebugMessage() string
- func (e *E) Error() string
- func (e *E) GRPCCode() (codes.Code, bool)
- func (e *E) HTTPStatus() (int, bool)
- func (e *E) LogValue() slog.Value
- func (e *E) Metadata() map[string]any
- func (e *E) PCs() []uintptr
- func (e *E) PublicMessage() string
- func (e *E) Unwrap() error
- type Option
- type Problem
- type StackFrame
- type StackOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Annotate ¶
Annotate は新たなスタックを取得せず、文脈用の debug メッセージやメタデータのみを付与します。 cause や定義済みエラー由来の既定値は保持され、スタックは取得しません。
func Define ¶
func Define(code string, def Definition) error
Define は errors.New(code) でエラーを作成し、その定義情報を登録します（def.Code が空なら code を充当）。
func RegisterContextExtractor ¶
RegisterContextExtractor はカスタムのコンテキスト抽出器を追加します。
func RegisterDefinition ¶
func RegisterDefinition(defErr error, def Definition)
RegisterDefinition は定義済みエラーとその定義情報を関連付けます。
func ToGRPCStatus ¶
ToGRPCStatus は errorsx のメタデータから *status.Status を生成します。 Definition 由来の既定も考慮し、必要に応じて ErrorInfo（Reason=code と一部メタ）を付与します。
func Wrap ¶
Wrap は既存のエラーを包み、メタデータ等を付与します。 cause がすでにスタックを保持している場合（pc が非 nil の *E）、それを再利用し、未保持なら一度だけ取得します。
Types ¶
type E ¶
type E struct {
// contains filtered or unexported fields
}
E はこのパッケージの中核となるエラー型です。 Unwrap を通じて標準の errors.Is/As と互換性があります。 スタック（PC 群）は生成時（New/Wrap）の一度だけ取得し、整形は必要時に遅延して行います。 表示やレンダリングの責務は外部に委ね、公開 API は最小限に保ちます。
func (*E) DebugMessage ¶
DebugMessage は開発者向けメッセージ（当該フレームでの値）を返します。
func (*E) HTTPStatus ¶
HTTPStatus は HTTP ステータスを返します（未設定の場合は false）。
type Option ¶
type Option func(*E)
Option は生成時に E を設定するための関数オプションです。
func WithGrpcStatus ¶
func WithHTTPStatus ¶
func WithMetadata ¶
func WithPublicMessage ¶
type Problem ¶
type Problem struct {
Type string `json:"type,omitempty"`
Title string `json:"title,omitempty"`
Status int `json:"status,omitempty"`
Detail string `json:"detail,omitempty"`
Instance string `json:"instance,omitempty"`
Code string `json:"code,omitempty"`
Extensions map[string]any `json:"extensions,omitempty"`
}
Problem は RFC7807 の最小表現です。 拡張メンバーは簡易運用のため Extensions にネストします（トップレベル合成は行いません）。
func ToHTTPProblem ¶
ToHTTPProblem はエラーを Problem 形式に変換します（Definition の既定値も反映）。
type StackFrame ¶
StackFrame は遅延解決後の 1 フレームを表します。
func ResolveFrames ¶
func ResolveFrames(pcs []uintptr, opts ...StackOption) []StackFrame
ResolveFrames は PC 群をフレームに解決し、必要に応じてフレームフィルタを適用します。
type StackOption ¶
type StackOption func(*stackConfig)
func WithStackFilter ¶
func WithStackFilter(f func(functionName, filePath string) bool) StackOption
WithStackFilter はカスタムのフレームフィルタを設定します。true を返すとフレームを保持します。
Source Files