Step-by-Step Tutorial: Implementing CleanHandlers in Your Next Project
In modern software development, maintaining a clean separation of concerns becomes challenging as projects scale. Controllers often become bloated with business logic, making testing and maintenance difficult. The CleanHandlers pattern solves this by isolating every request or command into its own dedicated handler.
This tutorial guides you through implementing CleanHandlers in your project to achieve a highly decoupled, testable, and maintainable codebase. What is the CleanHandlers Pattern?
The CleanHandlers pattern is an architectural approach inspired by the Mediator pattern and Command Query Responsibility Segregation (CQRS). Instead of grouping multiple actions inside a massive service or controller class, each business use case is split into an independent component. Each handler has exactly one job: Accept a specific input (Request/Command) Execute the business logic Return a specific output (Response)
This structure ensures that changes to one feature do not inadvertently break or impact another feature. Step 1: Define the Core Interfaces
To establish the pattern, you must first create the core abstractions. This requires two main interfaces: one for the request data and one for the handler logic. typescript
// The blueprint for all request data interface IRequest { readonly _responseType?: TResponse; } // The contract that every handler must implement interface IRequestHandler, TResponse> { handle(request: TRequest): Promise; } Use code with caution. Step 2: Create Your First Request and Handler
Next, implement a specific use case using the interfaces defined above. For this tutorial, we will build a feature that registers a new user. First, create the request class to hold the input data: typescript
export class RegisterUserRequest implements IRequest { constructor( public readonly email: string, public readonly username: string ) {} } Use code with caution.
Second, create the dedicated handler class to execute the business logic: typescript
export class RegisterUserHandler implements IRequestHandler { async handle(request: RegisterUserRequest): Promise { // 1. Validate the incoming request data if (!request.email.includes(“@”)) { throw new Error(“Invalid email address format.”); } // 2. Execute business logic (e.g., save to a database) console.log(Saving user ${request.username} with email ${request.email}); // 3. Return the expected response type return “User registered successfully!”; } } Use code with caution. Step 3: Set Up the Central Mediator
To prevent your entry points from tightly coupling to specific handlers, introduce a central mediator registry. This component receives any request object and automatically routes it to its corresponding handler. typescript
export class Mediator { private handlers = new Map(); // Register a handler for a specific request type register, TResponse>( requestToken: string, handler: IRequestHandler ): void { this.handlers.set(requestToken, handler); } // Send a request to its registered handler async send(requestToken: string, request: IRequest): Promise { const handler = this.handlers.get(requestToken); if (!handler) { throw new Error(No handler registered for request: ${requestToken}); } return handler.handle(request); } } Use code with caution. Step 4: Wire Everything Together
The final step is to initialize the mediator, register your handlers, and execute the request from your application entry point, such as an API controller or a CLI router. typescript
async function runApplication() { const mediator = new Mediator(); // Wire up the handlers (usually handled by Dependency Injection containers) mediator.register(“RegisterUser”, new RegisterUserHandler()); // Dispatch the request through the mediator const registrationRequest = new RegisterUserRequest(“[email protected]”, “CleanCoder”); try { const result = await mediator.send(“RegisterUser”, registrationRequest); console.log(result); // Output: User registered successfully! } catch (error) { console.error(“Request failed:”, error.message); } } runApplication(); Use code with caution. Benefits of CleanHandlers
Single Responsibility: Each handler file contains exactly one use case, making codebases easier to navigate.
Streamlined Testing: You can unit test business logic by instantiating the handler directly and passing a mock request, eliminating the need to mock complex controller HTTP contexts.
Parallel Development: Multiple developers can work on separate features simultaneously without running into merge conflicts in shared controller files.
To help optimize this setup for your specific project, tell me:
What programming language or framework (e.g., .NET, Node.js, Spring Boot) are you using?
Does your project use an existing Dependency Injection (DI) container?