🚀 A Cleaner Way to Handle API Responses & Exceptions in Spring Boot (Need Feedback!)

[PasinduOG]

Hi fellow developers! 👋

I've been working on a standardized API Response Wrapper and Global Exception Handler for Spring Boot applications to tackle some common pain points we all face.

😩 The Struggle

We often deal with:

• Inconsistent JSON structures across different endpoints.
• "Telescoping Constructors" when trying to build complex response objects.
• Losing track of errors in logs without a proper Trace ID in distributed systems.

💡 The Solution

I built a library that enforces a clean structure using the Builder Pattern for successes and RFC 7807 (ProblemDetail) for errors.

---

✨ Key Features

1. Fluent Builder Pattern

No more messy constructors or null passing! The API is fluent and readable.

// Simple success response
return ApiResponse.success("User fetched successfully", userDto);

// Complex response with specific status
return ApiResponse.created("User created successfully", savedUser);

2. Automatic Trace ID (MDC)

• It automatically handles traceId generation using SLF4J MDC.
• This ID is returned in the API response AND logged in the console.
• It makes debugging production issues much easier by correlating logs with specific requests.

3. Global Exception Handling (RFC 7807)

• It catches everything from MethodArgumentNotValidException to custom ApiException.
• Returns a standardized JSON format compatible with Spring Boot 3+ ProblemDetail.

---

🛠️ Usage Example

Here is how clean the Controller looks:

@GetMapping("/{id}")
public ResponseEntity<ApiResponse<UserDto>> getUser(@PathVariable Long id) {
    UserDto user = userService.findById(id);
    return ApiResponse.success("User found", user);
}

The JSON Response:

{
  "status": 200,
  "message": "User found",
  "content": {
    "id": 1,
    "name": "Pasindu"
  },
  "timestamp": "2026-02-13T10:00:00Z",
  "traceId": "a1b2c3d4-e5f6-7890"
}

---

🤔 Request for Feedback

I'd love to hear your thoughts on this approach to improve it further!

1. How do you usually handle standard API responses in your projects? Do you use a wrapper or return raw DTOs?
2. Error Handling: Do you prefer using Spring's ProblemDetail or a custom Error DTO?
3. Generics: Any suggestions to improve the generic type handling for collections (e.g., List<UserDto>)?

Check out the code snippets or the repo here: https://github.com/PasinduOG/api-response

Thanks! 🚀