DEV Community: keping jiang

I Built an Open-Source Starter Kit for Enterprise AI Applications with Spring Boot

keping jiang — Sat, 22 Aug 2026 07:53:50 +0000

How I Handle Global Exception Handling in a Spring Boot Application

keping jiang — Sun, 16 Aug 2026 03:31:00 +0000

How I Handle Global Exception Handling in a Spring Boot Application

Exception handling is one of those things that often starts simple and gradually becomes messy.

At the beginning of a Spring Boot application, it is common to see code like this:

try {
    userService.createUser(request);
} catch (Exception e) {
    return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body("Something went wrong");
}

This might work for a small application.

But as the application grows, repeating exception handling logic across controllers quickly becomes difficult to maintain.

In this article, I want to share a simple approach I use to structure global exception handling in a Spring Boot application.

The goals are straightforward:

Keep controllers clean
Return consistent API responses
Separate business errors from system errors
Make the application easier to maintain

The Problem with Handling Exceptions in Every Controller

Imagine an application with many endpoints.

Without centralized exception handling, you might end up with something like this:

@PostMapping("/users")
public ResponseEntity<?> createUser(
        @RequestBody CreateUserRequest request) {

    try {

        User user = userService.createUser(request);

        return ResponseEntity.ok(user);

    } catch (UserAlreadyExistsException e) {

        return ResponseEntity
                .status(HttpStatus.CONFLICT)
                .body(e.getMessage());

    } catch (Exception e) {

        return ResponseEntity
                .status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body("Internal server error");
    }
}

Then another controller might contain similar code.

And another.

Over time, this creates several problems:

Repeated code
Inconsistent error responses
Controllers become harder to read
Exception logic becomes scattered across the application

I prefer to move this responsibility into one centralized place.

1. Start with Custom Exceptions

The first step is to distinguish between different types of errors.

For example:

public class ResourceNotFoundException
        extends RuntimeException {

    public ResourceNotFoundException(String message) {
        super(message);
    }
}

Another example:

public class BusinessException
        extends RuntimeException {

    public BusinessException(String message) {
        super(message);
    }
}

For duplicate resources:

public class ResourceAlreadyExistsException
        extends RuntimeException {

    public ResourceAlreadyExistsException(String message) {
        super(message);
    }
}

These exceptions make the business logic easier to understand.

For example:

public User findById(Long id) {

    return userRepository
            .findById(id)
            .orElseThrow(() ->
                    new ResourceNotFoundException(
                            "User not found"
                    )
            );
}

The service does not need to know anything about HTTP responses.

It simply expresses what went wrong.

2. Create a Consistent Error Response

One thing I strongly recommend is using a consistent error response format.

For example:

{
  "timestamp": "2026-08-15T10:30:00",
  "status": 404,
  "error": "NOT_FOUND",
  "message": "User not found",
  "path": "/api/users/123"
}

We can represent this with a simple class:

public class ErrorResponse {

    private LocalDateTime timestamp;

    private int status;

    private String error;

    private String message;

    private String path;

    // constructors
    // getters
}

Using one standard response format makes the API easier to consume.

Clients do not need to handle a completely different error structure for every endpoint.

3. Use @RestControllerAdvice

Spring provides a very useful mechanism for centralized exception handling:

@RestControllerAdvice
public class GlobalExceptionHandler {
}

Now we can define handlers for different exceptions.

For example:

@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<ErrorResponse> handleNotFound(
        ResourceNotFoundException ex,
        HttpServletRequest request) {

    ErrorResponse response = new ErrorResponse(
            LocalDateTime.now(),
            HttpStatus.NOT_FOUND.value(),
            HttpStatus.NOT_FOUND.getReasonPhrase(),
            ex.getMessage(),
            request.getRequestURI()
    );

    return ResponseEntity
            .status(HttpStatus.NOT_FOUND)
            .body(response);
}

Now whenever a ResourceNotFoundException is thrown anywhere in the application, Spring can handle it automatically.

The controller stays clean.

4. Handle Business Exceptions Separately

Not every exception is a system failure.

Sometimes an error is part of normal business behavior.

For example:

User already exists

Or:

Account is inactive

Or:

Document processing is not allowed

These can be handled separately.

@ExceptionHandler(BusinessException.class)
public ResponseEntity<ErrorResponse> handleBusinessException(
        BusinessException ex,
        HttpServletRequest request) {

    ErrorResponse response = new ErrorResponse(
            LocalDateTime.now(),
            HttpStatus.BAD_REQUEST.value(),
            HttpStatus.BAD_REQUEST.getReasonPhrase(),
            ex.getMessage(),
            request.getRequestURI()
    );

    return ResponseEntity
            .badRequest()
            .body(response);
}

This gives the client a predictable response.

5. Handle Validation Errors

Validation errors are another important case.

For example:

public class CreateUserRequest {

    @NotBlank
    private String username;

    @Email
    private String email;

    @NotBlank
    private String password;
}

When validation fails, Spring throws a validation exception.

We can handle it globally:

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ErrorResponse> handleValidationException(
        MethodArgumentNotValidException ex,
        HttpServletRequest request) {

    String message = ex
            .getBindingResult()
            .getFieldErrors()
            .stream()
            .map(error ->
                    error.getField()
                    + ": "
                    + error.getDefaultMessage()
            )
            .findFirst()
            .orElse("Validation failed");

    ErrorResponse response = new ErrorResponse(
            LocalDateTime.now(),
            HttpStatus.BAD_REQUEST.value(),
            HttpStatus.BAD_REQUEST.getReasonPhrase(),
            message,
            request.getRequestURI()
    );

    return ResponseEntity
            .badRequest()
            .body(response);
}

For more complex APIs, you may want to return all validation errors instead of just the first one.

For example:

{
  "timestamp": "2026-08-15T10:30:00",
  "status": 400,
  "error": "BAD_REQUEST",
  "message": "Validation failed",
  "errors": {
    "username": "must not be blank",
    "email": "must be a valid email address"
  }
}

This can provide a better experience for frontend developers and API consumers.

6. Always Have a Fallback Exception Handler

Finally, I recommend having a handler for unexpected exceptions.

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleException(
        Exception ex,
        HttpServletRequest request) {

    ErrorResponse response = new ErrorResponse(
            LocalDateTime.now(),
            HttpStatus.INTERNAL_SERVER_ERROR.value(),
            HttpStatus.INTERNAL_SERVER_ERROR.getReasonPhrase(),
            "An unexpected error occurred",
            request.getRequestURI()
    );

    return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(response);
}

However, there is an important detail here.

I generally do not return the full exception message to the client.

For example, this is usually not a good idea:

.body(ex.getMessage());

Unexpected exceptions may contain implementation details or sensitive information.

Instead:

Client receives:
An unexpected error occurred

While the actual exception should be logged internally.

For example:

log.error("Unexpected error", ex);

This keeps internal implementation details away from API clients while still making debugging possible.

7. Keep Controllers Focused on HTTP Requests

With global exception handling in place, controllers become much simpler.

Instead of this:

@PostMapping("/users")
public ResponseEntity<?> createUser(
        @RequestBody CreateUserRequest request) {

    try {

        User user = userService.createUser(request);

        return ResponseEntity.ok(user);

    } catch (Exception e) {

        return ResponseEntity
                .status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body("Something went wrong");
    }
}

We can write:

@PostMapping("/users")
public ResponseEntity<User> createUser(
        @Valid @RequestBody CreateUserRequest request) {

    User user = userService.createUser(request);

    return ResponseEntity.ok(user);
}

The controller focuses on:

HTTP Request
        ↓
Validation
        ↓
Service
        ↓
HTTP Response

Exception handling happens separately.

This makes the application easier to read and maintain.

8. My Basic Exception Structure

For a typical Spring Boot application, I like to keep the structure simple:

exception
├── BusinessException
├── ResourceNotFoundException
├── ResourceAlreadyExistsException
└── GlobalExceptionHandler

As the application grows, additional exception types can be added when they represent meaningful business concepts.

The important thing is not to create dozens of exception classes unnecessarily.

Start with a small set:

Not Found
Conflict
Business Error
Validation Error
Unexpected Error

That is often enough for many applications.

A Simple Mental Model

I think about exceptions in three categories:

Business Errors
        ↓
Expected application behavior

Validation Errors
        ↓
Invalid client input

System Errors
        ↓
Unexpected failures

Each category should have a predictable API response.

For example:

Error Type	HTTP Status
Resource not found	404
Invalid request	400
Resource already exists	409
Unauthorized	401
Forbidden	403
Unexpected error	500

The exact structure may vary depending on the application, but consistency is important.

Final Thoughts

Global exception handling is not one of the most exciting parts of a Spring Boot application.

But it has a big impact on the overall quality of the API.

A good exception handling strategy should:

Keep controllers clean
Separate business logic from HTTP concerns
Return consistent error responses
Avoid exposing internal implementation details
Make the application easier to maintain

My preferred starting point is simple:

Custom Exceptions
        ↓
@RestControllerAdvice
        ↓
Consistent Error Response
        ↓
Structured Logging

You do not need a complicated exception framework to get started.

A small and consistent structure is usually enough.

As the application grows, you can evolve the error model based on real requirements.

How do you handle exceptions in your Spring Boot applications?

Do you use:

@RestControllerAdvice?
Custom business exceptions?
A standard API error response?
Problem Details / RFC 9457?

I'd love to hear how other Java developers structure exception handling in production applications.

I'm building and sharing open-source projects around Java, Spring Boot, enterprise application architecture, and AI-powered applications.

My goal is to explore practical patterns and reusable tools that help developers build enterprise applications faster.

How I Structure RBAC in a Spring Boot Application

keping jiang — Sat, 15 Aug 2026 03:30:29 +0000

How I Structure RBAC in a Spring Boot Application

Role-Based Access Control (RBAC) is one of those features that looks simple at first.

You create a few roles:

ADMIN
USER
MANAGER

Then you protect endpoints with something like:

@PreAuthorize("hasRole('ADMIN')")

And everything seems fine.

Until the application grows.

Suddenly, you have dozens of roles, hundreds of permissions, different API access requirements, and business rules that are becoming difficult to manage.

In this article, I want to share a simple and scalable way to structure RBAC in a Spring Boot application.

The goal is not to build the most complicated authorization system possible.

The goal is to build something that is:

Easy to understand
Easy to extend
Easy to test
Suitable for enterprise applications

The Basic Idea

Instead of directly assigning access rules everywhere in the code, I prefer to separate the authorization model into three layers:

User
  ↓
Role
  ↓
Permission

For example:

User: john

Role:
ADMIN

Permissions:
USER_READ
USER_CREATE
USER_UPDATE
USER_DELETE

Another user might have:

User: alice

Role:
MANAGER

Permissions:
USER_READ
REPORT_VIEW

The key idea is simple:

Users receive roles, and roles receive permissions.

This creates a flexible authorization model that can grow with the application.

1. Modeling the Domain

Let's start with the three core concepts.

User

A user can have one or more roles.

@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String username;

    private String password;

    @ManyToMany(fetch = FetchType.EAGER)
    private Set<Role> roles = new HashSet<>();
}

For example:

john

Roles:
ADMIN
MANAGER

This is useful in enterprise applications where a user may have multiple responsibilities.

2. Role

A role represents a collection of permissions.

@Entity
public class Role {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    @ManyToMany(fetch = FetchType.EAGER)
    private Set<Permission> permissions = new HashSet<>();
}

Typical roles might be:

ADMIN
MANAGER
USER
AUDITOR

The role itself does not define business logic.

Its purpose is to group permissions.

3. Permission

Permissions represent specific capabilities in the system.

@Entity
public class Permission {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
}

For example:

USER_READ
USER_CREATE
USER_UPDATE
USER_DELETE

REPORT_VIEW
REPORT_EXPORT

I prefer permissions that describe a clear business action.

A simple naming convention is:

RESOURCE_ACTION

For example:

USER_READ
USER_CREATE
USER_UPDATE
USER_DELETE

Or in an AI document application:

DOCUMENT_UPLOAD
DOCUMENT_DELETE
DOCUMENT_ANALYZE

4. Why Not Only Use Roles?

For small applications, this works perfectly well:

@PreAuthorize("hasRole('ADMIN')")

But as the application grows, you may end up with roles like:

ADMIN
SUPER_ADMIN
SUPPORT_ADMIN
FINANCE_ADMIN
CONTENT_ADMIN
REPORT_ADMIN

Then authorization rules can become tightly coupled to role names.

For example:

@PreAuthorize(
    "hasRole('ADMIN') or hasRole('MANAGER') or hasRole('SUPPORT_ADMIN')"
)

This becomes difficult to maintain.

Instead, permissions allow us to express the actual capability required:

@PreAuthorize("hasAuthority('USER_DELETE')")

Now the code tells us exactly what permission is required.

That is an important distinction.

Roles may change over time.

Business capabilities are often more stable.

5. Converting Roles and Permissions into Authorities

Spring Security works with GrantedAuthority.

When loading a user, we can convert both roles and permissions into authorities.

For example:

public Collection<? extends GrantedAuthority> getAuthorities(User user) {

    Set<GrantedAuthority> authorities = new HashSet<>();

    for (Role role : user.getRoles()) {

        authorities.add(
            new SimpleGrantedAuthority(
                "ROLE_" + role.getName()
            )
        );

        for (Permission permission : role.getPermissions()) {

            authorities.add(
                new SimpleGrantedAuthority(
                    permission.getName()
                )
            );
        }
    }

    return authorities;
}

The resulting authorities might look like:

ROLE_ADMIN

USER_READ
USER_CREATE
USER_UPDATE
USER_DELETE

Now Spring Security can check both roles and permissions.

6. Protecting API Endpoints

For broad access rules, roles can still be useful:

@PreAuthorize("hasRole('ADMIN')")
@GetMapping("/admin/users")
public List<User> getUsers() {
    return userService.findAll();
}

For more specific actions, I prefer permissions:

@PreAuthorize("hasAuthority('USER_DELETE')")
@DeleteMapping("/users/{id}")
public void deleteUser(@PathVariable Long id) {
    userService.delete(id);
}

Another example:

@PreAuthorize("hasAuthority('DOCUMENT_ANALYZE')")
@PostMapping("/documents/{id}/analyze")
public AnalysisResult analyzeDocument(
        @PathVariable Long id) {

    return documentService.analyze(id);
}

The required capability is immediately clear.

7. Avoid Hardcoding Authorization Logic Everywhere

One pattern I try to avoid is spreading authorization rules throughout business logic.

For example:

if (user.hasRole("ADMIN")) {
    // do something
}

Or:

if (currentUser.getRole().equals("MANAGER")) {
    // allow access
}

Over time, these checks become difficult to track and maintain.

Instead, authorization should be centralized where possible.

For example:

@PreAuthorize("hasAuthority('REPORT_EXPORT')")

For more complex rules, a custom authorization service can be useful:

@PreAuthorize("@authorizationService.canAccessDocument(#documentId)")

For example, access might depend on:

Permission
+
Organization
+
Ownership
+
Business Rules

8. RBAC Is Only the First Layer

A useful mental model is:

Authentication
        ↓
Role
        ↓
Permission
        ↓
Business Context

For example:

Is the user authenticated?
Does the user have the required permission?
Does the user belong to the correct organization?
Does the user own or have access to the resource?

A user may have the permission:

DOCUMENT_DELETE

But they should still not necessarily be able to delete every document in the system.

They may only be allowed to delete documents belonging to their own organization.

This is where business-level authorization becomes important.

My Recommendation

For a new Spring Boot application, I recommend starting with:

User
  ↓
Role
  ↓
Permission

Use:

hasRole(...)

for broad access control, and:

hasAuthority(...)

for specific business capabilities.

As the application grows, add context-aware authorization when necessary.

For example:

Permission
+
Organization
+
Ownership
+
Business Rules

This approach keeps the authorization model simple while still allowing it to grow with the application.

Final Thoughts

RBAC is not just about creating an ADMIN role.

The real challenge is designing an authorization model that still makes sense when your application has:

Multiple teams
Multiple roles
Hundreds of permissions
Multi-tenant organizations
Complex business rules

My approach is to start simple:

User → Role → Permission

Then add complexity only when the business actually requires it.

A good authorization system should be predictable, easy to understand, and easy to extend.

That is usually better than building the most sophisticated security architecture on day one.

What does your RBAC structure look like?

Do you prefer:

User → Role

or:

User → Role → Permission

I'd love to hear how other Spring Boot developers structure authorization in their applications.

I'm building open-source projects around Java, Spring Boot, enterprise application architecture, and AI-powered applications.

My goal is to share practical implementation ideas and reusable tools that can help developers build enterprise applications faster.