Create examples directory with real-world scenarios

[RAprogramm]

Objective

Create examples/ directory with comprehensive real-world examples demonstrating masterror integration with popular frameworks and use cases.

Background

Phase 4 from KaiCode 2026 preparation (#205). Examples help users understand practical usage patterns and accelerate adoption.

Tasks

Examples Structure

examples/
├── README.md                    # Index of all examples
├── axum-rest-api/              # Axum REST API with RFC 7807
├── actix-web-service/          # Actix-web integration
├── tonic-grpc-service/         # gRPC with Tonic
├── sqlx-database/              # Database error handling
├── multi-transport/            # HTTP + gRPC service
├── custom-domain-errors/       # Derive macro usage
├── telemetry-integration/      # OpenTelemetry/tracing
└── comparison-thiserror/       # Side-by-side with thiserror

Example Requirements

Each example MUST include:

• Runnable code (cargo run --example <name>)
• README.md explaining the scenario
• Tests (cargo test --example <name>)
• Comments explaining key decisions
• Cargo.toml with minimal dependencies

High Priority Examples

1. Axum REST API (examples/axum-rest-api/)

• HTTP service with multiple endpoints
• RFC 7807 Problem Details responses
• Custom domain errors with derive macro
• Metadata attachment (request_id, user_id)
• Integration tests with axum-test

2. SQLx Database (examples/sqlx-database/)

• Database connection error handling
• Query error mapping
• Constraint violation handling
• Transaction error patterns
• Integration tests with test database

3. Multi-Transport (examples/multi-transport/)

• Shared domain errors
• HTTP REST endpoint
• gRPC endpoint
• Consistent error mapping
• Tests for both transports

4. Custom Domain Errors (examples/custom-domain-errors/)

• Payment processing errors
• Authentication/authorization errors
• Validation errors
• External service errors
• Full derive macro usage

Medium Priority Examples

5. Tonic gRPC Service (examples/tonic-grpc-service/)

• gRPC service with tonic
• Status code mapping
• Error details/metadata
• Client error handling

6. Actix-Web Service (examples/actix-web-service/)

• Actix-web HTTP service
• Middleware integration
• Custom error responses

Low Priority Examples

7. Telemetry Integration (examples/telemetry-integration/)

• OpenTelemetry spans
• Tracing integration
• Structured logging

8. Comparison with Thiserror (examples/comparison-thiserror/)

• Side-by-side implementation
• Migration guide
• Feature comparison

Success Criteria

• At least 4 working examples published
• Each example has README and tests
• All examples compile without warnings
• All tests pass
• Examples referenced in main README.md
• CI job runs example tests

Implementation Notes

• Use workspace members: members = [".", "examples/*"]
• Each example is a separate binary
• Keep dependencies minimal
• Add [[example]] sections to Cargo.toml

Priority

Low (enhances documentation but not blocking)

Related

• Prepare repository for KaiCode 2026 competition #205 KaiCode 2026 preparation
• Expand documentation wiki with guides and patterns #208 Documentation wiki