errors_en.md

pkg/errors -- Typed Error Catalog

A predefined structured error code system, enabling both AI and humans to consistently understand and use errors.

Design Philosophy

Traditional approaches have each handler define its own error messages, making it impossible for AI to predict the response format. Typed Error Catalog defines errors as global constants with a unified format that can be cataloged by Manifest:

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

Automatically registers in the global Catalog, typically used in package-level var blocks.

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

AppError's With*() methods always return copies; the original definition is never modified:

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

Code	HTTP	Message	Category
E0001	404	Resource not found	general
E0002	400	Bad request	general
E0003	500	Internal server error	general
E0004	405	Method not allowed	general
E1001	422	Validation failed	validation
E1002	400	Missing required field	validation
E1003	400	Invalid format	validation
E2001	401	Authentication required	auth
E2002	403	Permission denied	auth
E2003	401	Token expired	auth

Architecture

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