pkg/errors -- Typed Error Catalog

Design Philosophy

Bad: c.JSON(404, map[string]string{"error": "user not found"}) <- arbitrary format
Good: errors.AbortWithAppError(c, errors.ErrUserNotFound.With("id", 42)) <- structured

Quick Start

Define Error Codes

package apperrors
import "github.com/maoxiaoyue/hypgo/pkg/errors"
var (
 ErrUserNotFound = errors.Define("E1001", 404, "User not found", "users")
 ErrUserExists = errors.Define("E1002", 409, "User already exists", "users")
 ErrInvalidEmail = errors.Define("E1003", 422, "Invalid email format", "users")
)

Use in Handlers

func getUser(c *hypcontext.Context) {
 id := c.Param("id")
 user, err := userService.FindByID(id)
 if err != nil {
 errors.AbortWithAppError(c, apperrors.ErrUserNotFound.With("id", id))
 return
 }
 c.JSON(200, user)
}

Response Format

{
 "code": "E1001",
 "message": "User not found",
 "details": {
 "id": "42"
 }
}

Core API

Define -- Define an Error

errors.Define(code, httpStatus, message, category) *AppError

AppError Methods

// Attach context (returns a copy, original unchanged)
err.With("field", "email")
err.WithDetail("reason", "already exists")
err.WithDetails(map[string]any{"a": 1, "b": 2})
err.WithMessage("Custom message")
// Convert to JSON (for HTTP response)
err.JSON() // -> map[string]any{"code":"E1001","message":"...","details":{...}}
// Error comparison (compares Code only, ignores Details)
errors.Is(err1, err2) // true if same code

Context Integration

// Abort request and return structured error
errors.AbortWithAppError(c, err)
// Return error without aborting middleware chain
errors.RespondError(c, err)

Catalog Query

catalog := errors.GlobalCatalog()
// Query all defined errors
all := catalog.All()
// Look up by code
err, ok := catalog.Get("E1001")
// Look up by category
authErrors := catalog.ByCategory("auth")

Immutable Design

original := errors.Define("E1", 404, "Not found", "general")
copy1 := original.With("id", 1)
copy2 := original.With("id", 2)
// original.Details == nil (not modified)
// copy1.Details == {"id": 1}
// copy2.Details == {"id": 2}

Predefined Errors

Architecture

pkg/errors/
├── catalog.go AppError, Define(), Catalog, predefined errors
├── context.go AbortWithAppError(), RespondError()
└── catalog_test.go 19 unit tests