DEV Community: Gabriela Goudromihos Puig

🧠 From Chaos to Clean Code: My Java Refactor Journey - Part 4 of 6

Gabriela Goudromihos Puig — Tue, 08 Jul 2025 08:04:38 +0000

Now that our architecture is modular and our input/output boundaries are well-defined, it’s time to make the system more robust and less fragile.

Because clean code is not just about structure — it’s about behavior under pressure.

In this part of the journey, we’ll:

✅ Centralize error handling so unexpected exceptions don’t leak into the user’s face
✅ Add meaningful error messages and proper HTTP responses
✅ Start writing unit tests to protect behavior and refactors
✅ Learn how to test services, controllers, and edge cases confidently

We’ve cleaned up the house — now we’re adding locks to the doors and alarms to the windows.
Let’s make it reliable. 🛡️

🛡️ Step 1: Global Error Handling — Clean, Scoped & Scalable

A clean architecture doesn’t stop at structure — it must also handle errors predictably and clearly. Instead of generic stack traces or inconsistent messages, we now return standardized and meaningful responses across the entire API.

🔹 Scoped Handlers per Domain
We created three focused @ControllerAdvice classes:

com.example.spaghetti.adapter.exception
  └── ThingExceptionHandler.java ← Handles errors from the ThingController
  └── ItemExceptionHandler.java ← Handles errors from the ItemController
  └── ValidationExceptionHandler.java ← Catches validation failures and generic exceptions

This structure avoids bloated global handlers and keeps each domain's behavior isolated and easy to reason about.

📦 All handlers are placed under adapter.exception, since they're part of how the application communicates with the outside world — not core business logic.

🔹 Domain Exceptions with Meaning
We introduced custom exceptions that live in the domain layer:

com.example.spaghetti.domain.exception
  └── ThingNotFoundException.java
  └── ItemNotFoundException.java

They extend a shared base:

com.example.spaghetti.adapter.exceptionEntityNotFoundException

This allows us to:

✅ Express business rules clearly in the domain
✅ Share logic for testing and centralized error mapping
✅ Keep the application layer free of hardcoded strings and magic messages

🔹 Ready to Scale
This setup follows Clean Architecture and DDD principles:

Domain stays isolated — no HTTP, no annotations
Adapter layer deals with translation to REST responses
Each new domain can have its own exceptions and handler

💡 The result: when your app grows, your error handling doesn’t get messier — it grows with it, cleanly.

🧹 Adjusting Error Handling and Responsibilities
During the project cleanup, we removed the name validation from the ItemController:

if (!nameValidator.test(itemRequest.getName())) {
    throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Name must start with uppercase");
}

This is because this validation represents a business rule, and according to Clean Architecture and DDD principles, business rules belong in the application or domain layer, not in the controller (adapter) layer.

Now, this validation lives inside the ItemService, which throws a specific exception (InvalidItemNameException) when the rule is violated. This exception is caught by the ItemExceptionHandler and translated into the proper HTTP response.

This adjustment keeps the controller lean and centralizes business logic in the right place.

📝 What about the letter count log in the ThingController?
On the other hand, we kept the letter count logging in the ThingController:

int letterCount = utils.countLetters(thingRequest.getName());
System.out.println("Name has " + letterCount + " letters.");

This code does not affect application logic or control flow — it’s just a utility for logging or debugging, with no business impact.

Therefore, it’s fine to leave it in the controller.

🧪 What’s Next: Unit and Integration Testing, with Purpose

With error handling centralized and domain boundaries protected, our system is no longer fragile — but it’s not battle-tested yet.

In the next sessions, we’ll dedicate entire steps to testing, because clean architecture without tests is like building a fortress with no guards.

🔬 We’ll start with unit tests, focusing on services and core use cases:

Validate business logic in isolation
Protect against regressions
Speed up development with confidence

🔗 Then, we’ll move to integration tests, making sure:

Controllers, mappers, and dependencies work as a system
HTTP endpoints behave correctly under real conditions
The whole app remains stable during changes and refactors

Testing is not a checkbox — it’s part of designing resilient software.
So in the next chapters, we’ll not only write tests — we’ll structure them with the same discipline we applied to the rest of the code.

🧱 Architecture is foundation.
🛡️ Error handling is protection.
🔁 Testing is confidence.

Let’s move forward with that confidence — and make this codebase bulletproof. 💥

🧠 From Chaos to Clean Code: My Java Refactor Journey - Part 3 of 6

Gabriela Goudromihos Puig — Fri, 04 Jul 2025 17:43:28 +0000

Now that we’ve separated concerns and cleaned up the code, it’s time for the next step:
introducing Clean Architecture layers and applying DDD concepts with proper domain modeling.

Let’s make the design clearer, scalable, and truly domain-focused. 🚀

🔧 Step 1: Laying the Groundwork for Clean Architecture

Before we can apply Clean Architecture and DDD properly, we need to rethink our folder structure.

Right now, everything is grouped by technical role:

com.example.spaghetti
├── controller
│   └── ThingController.java
│   └── ItemController.java
├── service
│   └── ThingService.java
│   └── ItemService.java
├── repository
│   └── ThingRepository.java
│   └── ItemRepository.java
├── model
│   └── Thing.java
│   └── Item.java
├── config
│   └── MainConfig.java
├── util
│   └── Utils.java

That’s a good start — but Clean Architecture is not just about naming layers, it’s about isolating responsibilities and controlling dependencies between them.

✅ 1. Define the main layers
Here’s the structure we’re aiming for:

com.example.spaghetti
├── domain           ← business rules and core entities (pure Java)
├── application      ← use cases (calls domain logic)
├── infrastructure   ← technical details (config, persistence, utilities)
├── adapter          ← I/O layers (controllers, REST APIs, DTOs)

💡 Rule of thumb:

Domain is the core.
Application uses the domain.
Infrastructure supports them.
Adapter is how the outside world talks to the app.

✅ 2. Move your classes to the right packages
Let’s organize your existing code into those layers:

🔹 domain
Core entities and domain contracts

com.example.spaghetti.domain.model
  └── Thing.java
  └── Item.java

com.example.spaghetti.domain.repository
  └── ThingRepository.java
  └── ItemRepository.java

🔹 application
Business coordination logic

com.example.spaghetti.application.service
  └── ThingService.java
  └── ItemService.java

🔹 infrastructure
Low-level details like config and utility classes

com.example.spaghetti.infrastructure.config
  └── MainConfig.java

com.example.spaghetti.infrastructure.util
  └── Utils.java

🔹 adapter
Web interface and DTOs

com.example.spaghetti.adapter.controller
  └── ThingController.java
  └── ItemController.java

com.example.spaghetti.adapter.dto
  └── (we'll add DTOs in the next steps)

This new structure aligns your code with Clean Architecture principles, making it easier to scale, test, and evolve over time.

🔧 Step 2: Introducing DTOs, Mappers, and Validation for Clear Separation

After reorganizing our project structure and separating concerns, the next essential step was to make the boundary between our API and domain logic explicit — by introducing DTOs (Data Transfer Objects), validation, and mappers.

📂 Organizing DTOs and Mappers
We created dedicated packages to keep the code clean and scalable:

com.example.spaghetti.adapter.dto.request    ← Input DTOs (ThingRequest, ItemRequest)
com.example.spaghetti.adapter.dto.response   ← Output DTOs (ThingResponse, ItemResponse)
com.example.spaghetti.adapter.dto.mapper     ← Mappers to convert between DTOs and domain entities

This separation keeps the API contract clear, prevents domain leakage, and isolates transformations, following Clean Architecture’s adapter layer principle.

📄 Why DTOs?
DTOs define exactly what data enters and leaves our system. To ensure data integrity, we added validation annotations from Jakarta Validation API, such as NotBlank and NotNull, on the request DTO fields.

This guarantees that only valid and well-formed data reaches the business logic layer.

By doing this, our domain entities remain clean and focused solely on business rules — an important DDD principle to avoid coupling domain models to external layers.

🛠️ Using MapStruct for Mapping
To avoid boilerplate code when converting between DTOs and entities, we introduced MapStruct, a code generator that creates type-safe mappers automatically:

@Mapper(componentModel = "spring")
public interface ThingMapper {
    Thing toEntity(ThingRequest request);
    ThingResponse toResponse(Thing thing);
    List<ThingResponse> toResponse(List<Thing> things);
}

@Mapper(componentModel = "spring")
public interface ItemMapper {
    Item toEntity(ItemRequest request);
    ItemResponse toResponse(Item item);
    List<ItemResponse> toResponseList(List<Item> things);
}

Mappers live in the adapter layer and keep our domain pure from external concerns.

⚙️ Controller Adjustments
Controllers were updated to:

Accept validated request DTOs (annotated with Jakarta Validation constraints)
Use mappers to convert requests into domain entities
Call the service layer with domain entities
Convert service results back into response DTOs for the client
This keeps the controller’s responsibility to a simple orchestrator — no business logic inside, fully aligned with Clean Architecture.

✅ What this achieved

Clear separation of API and domain models
Early validation of input data via Jakarta Validation annotations
Reduced boilerplate with MapStruct generated code
Improved maintainability and scalability of the codebase

🧠 What’s next?

With DTOs, validation, and mapping in place, our code is now clean, scalable, and aligned with Clean Architecture and DDD principles.
Next up, we’ll focus on improving reliability by implementing global error handling and writing unit tests.

🧠 From Chaos to Clean Code: My Java Refactor Journey - Part 2 of 6

Gabriela Goudromihos Puig — Thu, 03 Jul 2025 07:25:36 +0000

🔧 Step 1: Separating Responsibilities – From Spaghetti to Structure

The first class I refactored was a typical all-in-one mess: controller, business logic, and in-memory storage were all crammed into the same place.

@RestController
@RequestMapping("/things")
public class ControllerService {
    private List<String> list = new ArrayList<>();
    // ...
}

@RestController
@RequestMapping("/items")
public class ModelRepoController {
    private Map<Long, Item> storage = new HashMap<>();
    // ...
}

This class did everything — which is exactly what we want to avoid in domain-oriented architecture.

🔄 The refactor

Split the logic into four separate components:

ThingController/ItemController: exposes the HTTP API
ThingService/ItemService: handles the business logic
ThingRepository/ItemRepository: manages data access (in-memory for now)
Thing/Item: represents the domain entity

The logic stayed the same, but now it's clean, testable, and aligned with Clean Architecture principles.

💡 Before: logic and storage were tightly coupled in the controller
💡 After: the controller simply orchestrates calls to the service

🔗 Check out the before and after in the repo.

🗂️ Project structure after the refactor:

com.example.spaghetti
├── controller
│   └── ThingController.java
│   └── ItemController.java
├── service
│   └── ThingService.java
│   └── ItemService.java
├── repository
│   └── ThingRepository.java
│   └── ItemRepository.java
├── model
│   └── Thing.java
│   └── Item.java

🔧 Step 2: From “Useless Bean” to Simple Validation

In the initial version of the code, I had a leftover bean:

@Bean
public String uselessBean() {
    return "I am a useless bean";
}

🫠 It did absolutely nothing — until now.

Instead of deleting it, I replaced it with a ✨ simple validation rule:
✅ check if a name starts with an uppercase letter.

@Bean
public Predicate<String> nameStartsWithUppercaseValidator() {
    return name -> name != null && !name.isEmpty() && Character.isUpperCase(name.charAt(0));
}

I then injected it into the controller and used it to validate input before saving a new item.
No big framework, no annotation magic — just a good old @bean doing something useful.

📦 Where should this bean live?

Since this is a generic validation, not part of the domain logic itself, I moved it to a dedicated config package:

com.example.spaghetti
├── config
│   └── MainConfig.java

According to DDD principles, reusable and infrastructure-related beans like this one shouldn't live inside your domain or application logic.
Placing it under config (or infrastructure.config) keeps your architecture clean and responsibilities well separated.

💡 Small win: the bean now enforces a business rule — and the code stays clean and reusable.

🧠 Even small refactors like this help keep things tidy and meaningful.

🔧 Step 3: Giving Purpose to the Utils Class

Previously, our Utils class had two static methods that weren’t actually used anywhere.

Now, we brought it to life by adding a new method that counts the number of letters in a given string:

public int countLetters(String input) {
    if (input == null) return 0;
    return (int) input.chars()
            .filter(Character::isLetter)
            .count();
}

This method helps us process input names more meaningfully.

In the controller, we call this method to log how many letters the submitted name has before saving it.

Small steps like this turn “unused helpers” into valuable tools for our application!

🚀 Conclusion: Setting the Stage for Clean Architecture and DDD

We’ve cleaned up the code by separating responsibilities and giving purpose to unused parts like the validation bean and utils. 🧹✨

This foundation makes our codebase cleaner and easier to maintain. 🏗️🧱

Next, we’ll introduce Clean Architecture layers and apply proper domain modeling with DDD to take our design to the next level. 📐📚

Stay tuned! 👀

Whether you’re new to server modding or just curious about how MCP works, this tutorial makes it easy to get started

Gabriela Goudromihos Puig — Wed, 02 Jul 2025 07:46:19 +0000

Debbie O'Brien

Jul 1 '25

Building Your First MCP Server: A Beginners Tutorial

#mcp #webdev #ai #typescript

146

Comments 6

9 min read

🧠 From Chaos to Clean Code: My Java Refactor Journey - Part 1 of 6

Gabriela Goudromihos Puig — Wed, 02 Jul 2025 07:36:41 +0000

I wanted to challenge myself to apply Clean Architecture and Domain-Driven Design (DDD) from the ground up — not in a greenfield project, but starting from total mess.

So I built Spaghetti API: a deliberately chaotic Spring Boot project, full of bad practices, no architecture, and zero tests.

It looks like this 👇

src/main/java/com/example/spaghetti
├── ControllerService.java     // controller acting as service
├── ModelRepoController.java   // model + repo + controller in one
├── Utils.java                 // weird helpers
├── MainConfig.java            // useless bean
├── SpaghettiApplication.java

🧩 Why?

Because most real-life projects don’t start clean — they evolve from chaos. I wanted to document how I bring order, step by step.

🛠️ My refactoring path

Separate responsibilities (controller, service, repo, model)
Introduce Clean Architecture layers
Apply DDD concepts with proper domain modeling
Add DTOs, validations, global error handling
Implement unit and integration tests

✅ Technologies

Java 17
Spring Boot 3
Maven

🔗 Source Code

👉 github.com/gabrielapuig/spaghetti-api

If you're dealing with a messy legacy codebase 🧹, or want to level up your architecture skills in Java ☕️, follow along — I’ll be sharing each refactor stage 🔄 and breaking it down step-by-step.

Ever worked on a project like this? 🤔 I'd love to hear how you handled it!