Mastering CleanHandlers — Best Practices and Patterns
Introduction
CleanHandlers are a design approach for organizing request/response or event-handling logic so that code stays readable, testable, and maintainable. This article shows practical patterns, best practices, and refactor techniques you can apply in most languages and frameworks.
Why CleanHandlers matter
- Separation of concerns: Keep orchestration, validation, business logic, and side effects distinct.
- Testability: Small, focused handlers are easier to unit-test.
- Composability: Reusable handler building blocks simplify feature growth.
- Observability: Clear boundaries make logging, metrics, and error handling consistent.
Core principles
- Single responsibility — each handler should do one job (e.g., validate, authorize, execute use case, format response).
- Explicit inputs and outputs — avoid hidden state and globals; pass dependencies and data explicitly.
- Pure logic vs side effects — isolate pure computation from IO (DB, network, filesystem).
- Fail fast — validate and authorize early to minimize work on invalid inputs.
- Small, composable units — prefer multiple small handlers over monolithic ones.
Common handler roles and patterns
- Validator: Checks shape, types, and business preconditions. Return well-structured errors.
- Authenticator/Authorizer: Verifies identity and permissions before execution.
- Use-case (Interactor): Encapsulates application rules and orchestration of domain actions.
- Repository/Adapter: Thin layer over persistence or external APIs, invoked from use-cases.
- Responder/Serializer: Converts domain results into transport format (JSON, HTML, events).
- Error middleware: Centralizes mapping of exceptions to user-facing responses and logging.
Composition techniques
- Pipeline (middleware) pattern — chain handlers so each can modify context and decide to continue or short-circuit.
- Functional composition — pure functions composed with map/flatMap or higher-order functions.
- Decorator/wrapper — add cross-cutting concerns (logging, retries, metrics) without changing core handler code.
- Command bus — dispatch commands to dedicated handlers for complex apps with many actions.
Implementation examples (conceptual)
- HTTP request flow: Router → Auth middleware → Validation → Use-case → Repository → Responder → HTTP Response.
- Event processing: Event receiver → Deduplication → Schema validation → Use-case → Side-effect adapters → Ack/Nack.
Error handling and observability
- Normalize errors into a predictable envelope with codes, messages, and metadata.
- Use structured logging and include correlation IDs.
- Track metrics per handler (latency, error rate, throughput).
- Implement retries only in adapters; avoid hiding transient failures inside use-cases.
Testing strategies
- Unit test handlers with mocks/stubs for adapters and repositories.
- Write golden tests for serializers/responses.
- Use integration tests for pipelines and end-to-end flows, exercising real adapters when feasible.
- Property-based tests for validators and pure logic where helpful.
Performance and scalability
- Keep handlers idempotent where possible to simplify retries and scaling.
- Move expensive operations to background jobs or adapters with caching.
- Measure and profile handler latency; optimize hotspots in adapters or heavy pure computations.
Anti-patterns to avoid
- Fat handlers mixing validation, DB access, formatting, and business rules.
- Hidden global state or singletons that make handlers hard to reason about.
- Catch-and-ignore exception handling that loses context.
- Tight coupling between handler and transport (e.g., embedding HTTP details in domain logic).
Migration checklist (refactoring legacy handlers)
- Identify responsibilities in large handlers.
- Extract pure logic into use-case classes/functions.
- Introduce validators and serializers as separate modules.
- Add dependency injection for adapters/repositories.
- Replace direct side-effect calls with adapter interfaces.
- Add tests at each extraction step.
Quick code sketch (pseudocode)
handler(request, deps): auth = deps.auth.verify(request.token) if not auth: return error(401) data = validate(request.body) result = useCase.execute(data, deps.repo) return responder.format(result)Conclusion
Mastering CleanHandlers reduces technical debt and improves developer velocity. Apply the principles above: separate concerns, favor small composable units, isolate side effects, and make errors and observability explicit. Over time these patterns yield more reliable, testable, and maintainable systems.
Related search suggestions: CleanHandlers refactoring patterns (0.9), handler pipeline middleware (0.8), command bus vs mediator pattern (0.7)