DEV Community: Gianfranco Coppola

Transactions in Spring Boot: What `@Transactional` Really Does (and Why It Matters)

Gianfranco Coppola — Sun, 01 Feb 2026 21:47:54 +0000

1. Introduction: Why Transactions Matter More Than You Think

If you’ve been working with Spring Boot for a while, chances are you’ve already used @Transactional.

Maybe you added it because “that’s what everyone does”, or because a tutorial told you so.

And most of the time… things seem to work.

Until one day:

a payment is charged but the order is not created
a user is created, but their profile is missing
a retry suddenly creates duplicate data
or worse: production data ends up in an inconsistent state

That’s usually the moment when you realize that transactions are not just a database feature — they are a core business concept.

In backend development, especially in stateful systems, partial success is often worse than total failure.

A transaction is what allows you to say:

“Either everything succeeds, or nothing does.”

Spring Boot makes transactions easy to use, but also easy to misunderstand.

And misunderstanding them can lead to subtle bugs that are extremely hard to debug.

In this article, we’ll start from the basics:

what a transaction really is
why it is fundamental in backend systems
and how this concept maps to Spring Boot and @Transactional

Before touching any annotation, we need to get the mental model right.

2. What Is a Transaction? (The Basics, Done Right)

At its core, a transaction is a logical unit of work.

It groups multiple operations into a single, indivisible action.

Think about a very common backend use case:

create an order
decrease product stock
save a payment record

If one of these steps fails, the system should not be left in a half-completed state.

Without transactions, your system might end up like this:

✔ Order created
✔ Payment saved
✘ Stock update failed

That’s not a technical issue.

That’s a business problem.

The ACID Properties

Transactions are usually described using the ACID acronym. You’ve probably heard of it, but let’s translate it into practical backend terms.

Atomicity

“All or nothing.”

Either all operations inside the transaction succeed, or all of them are rolled back.

No partial updates, no “we’ll fix it later”.

Consistency

The system moves from one valid state to another valid state.

Constraints, invariants, and business rules must always hold — before and after the transaction.

Isolation

Concurrent transactions should not step on each other’s toes.

What one transaction sees (or doesn’t see) from another transaction is controlled and predictable.

This is where things start getting tricky — and interesting.

Durability

Once a transaction is committed, it stays committed.

Even if the application crashes right after, the data is there.

Transactions Are Not Just About Databases

This is an important point that often gets overlooked.

Transactions:

are implemented by the database
but defined by your business logic

The database doesn’t know what an “order” or a “payment” is.

It only knows rows, tables, and constraints.

It’s the backend application that decides:

what belongs together
where the transactional boundary starts
and where it ends

This is exactly why frameworks like Spring exist:

to help you define transactional boundaries in your application code, not in SQL scripts.

Why Transactions Are Fundamental in Backend Systems

Modern backend systems are:

concurrent
stateful
failure-prone by nature
- Networks fail.
- Databases timeout.
- External services go down.

Transactions are your last line of defense against data corruption.

They don’t make failures disappear — but they make failures safe.

And that’s the key idea we’ll carry into Spring Boot and @Transactional.

3. Transactions in Spring Boot: The Big Picture

Before diving deeper into @Transactional, it’s important to understand how Spring manages transactions at a high level.

Not the full internal implementation — just enough to avoid the most common (and painful) mistakes.

Because with transactions in Spring, the “how” matters almost as much as the “what”.

Declarative vs Programmatic Transactions

Spring supports two ways of managing transactions:

1. Programmatic transactions

You explicitly start, commit, and rollback a transaction in code.

TransactionStatus status = transactionManager.getTransaction(definition);
try {
    // business logic
    transactionManager.commit(status);
} catch (Exception ex) {
    transactionManager.rollback(status);
    throw ex;
}

This works, but:

it’s verbose
it mixes infrastructure concerns with business logic
it doesn’t scale well in complex services

You can use it, but in most Spring Boot applications, you shouldn’t.

2. Declarative transactions (the Spring way)

This is where @Transactional comes in.

You declare what should be transactional, not how to manage the transaction.

@Transactional
public void placeOrder() {
    // business logic
}

Spring takes care of:

opening the transaction
committing it if everything goes well
rolling it back if something goes wrong

This separation of concerns is one of the reasons why Spring-based backends are so readable and maintainable.

The Role of `PlatformTransactionManager`

At runtime, Spring delegates all transaction operations to a PlatformTransactionManager.

Think of it as an abstraction layer between:

your application
and the actual transaction implementation

Depending on what you use, Spring will plug in a different implementation:

DataSourceTransactionManager → JDBC
JpaTransactionManager → JPA / Hibernate
ReactiveTransactionManager → reactive stacks

This abstraction is what allows you to write framework-agnostic transactional code, while still being tightly integrated with your persistence technology.

You almost never interact with it directly — but it’s always there.

4. What Actually Happens When You Use `@Transactional`

At first glance, @Transactional looks deceptively simple.

You put it on a method, and magically:

a transaction starts
your logic runs
everything is committed or rolled back

And in happy-path demos, that’s exactly what happens.

In real-world applications, however, where and how you use @Transactional makes a huge difference.

Let’s break it down.

The Simplest (and Most Common) Use Case

The most basic usage looks like this:

@Transactional
public void placeOrder() {
    orderRepository.save(order);
    paymentRepository.save(payment);
}

If an exception is thrown during the method execution:

Spring marks the transaction for rollback
all database changes are reverted

If the method completes successfully:

the transaction is committed

So far, so good.

But this simplicity hides a lot of assumptions.

One of the biggest misconceptions is thinking of @Transactional as something that adds behavior.
It doesn’t. It defines a transactional boundary:

In other words, when you annotate a method with @Transactional, Spring does NOT modify your method.

Instead, Spring:

creates a proxy around your bean
intercepts calls to transactional methods
starts a transaction before the method execution
commits or rolls back after the method returns or throws an exception

This is done using Spring AOP (Aspect-Oriented Programming).

In practice, the flow looks like this:

Client → Spring Proxy → Transaction Interceptor
        → Your Method → Transaction Commit / Rollback

Why is this important?

Because only method calls that go through the proxy are transactional.

This single sentence explains:

why self-invocation doesn’t work
why @Transactional on private methods is ignored
why calling a transactional method from the same class can silently break everything

We’ll get back to this later in the pitfalls section, but keep this mental model in mind.

Where `@Transactional` Should Live (and Where It Shouldn’t)

A common question is: where do I put @Transactional?

The short answer:

On service-layer methods that define a business operation.

Typically:

❌ Controllers → no business logic, no transactions
⚠️ Repositories → usually too low-level
✅ Services → perfect place for transactional boundaries

Example:

@Service
public class OrderService {

    @Transactional
    public void placeOrder(CreateOrderCommand command) {
        // validate input
        // persist order
        // update stock
        // trigger side effects
    }
}

This makes your transactional boundary:

explicit
easy to reason about
aligned with business use cases

Class-Level vs Method-Level `@Transactional`

Spring allows you to annotate:

a single method
or the entire class

@Transactional
@Service
public class OrderService {
    ...
}

This means:

every public method is transactional by default
unless overridden at method level

This can be useful, but it’s also dangerous if overused.

From experience:

class-level works well for simple services
method-level is safer for complex ones

Explicit is better than implicit — especially with transactions.

At this point, we have a solid foundation:

what a transaction is
why it matters
how Spring manages it under the hood

5. Understanding `@Transactional` Attributes (The Real Ones)

@Transactional is not just an on/off switch.

Behind that single annotation there are rules that control how transactions behave, especially when:

multiple methods interact
exceptions are thrown
concurrent operations happen

Most bugs related to transactions come from default assumptions that turn out to be wrong.

Let’s go through the attributes that actually matter in real projects.

5.1 Propagation: How Transactions Interact with Each Other

Propagation defines what happens when a transactional method is called from another transactional method.

This is by far the most important attribute.

`REQUIRED` (Default)

@Transactional(propagation = Propagation.REQUIRED)

Meaning:

join the existing transaction if there is one
otherwise, create a new transaction

This is what you want most of the time.

Example:

@Transactional
public void placeOrder() {
    orderService.saveOrder();
    paymentService.charge();
}

If charge() fails:

the entire transaction rolls back
nothing is persisted

This is usually correct and desirable.

`REQUIRES_NEW`

@Transactional(propagation = Propagation.REQUIRES_NEW)

Meaning:

suspend the existing transaction
start a completely new one

Classic use case:

audit logs
technical events
actions that must persist even if the main transaction fails

Example:

@Transactional
public void placeOrder() {
    orderRepository.save(order);
    auditService.logOrderAttempt(order); // REQUIRES_NEW
    throw new RuntimeException("Payment failed");
}

Result:

order → rolled back
audit log → committed

This is powerful — and dangerous if misused.

Other Propagation Types (Quick but Honest)

SUPPORTS → join if exists, otherwise run non-transactionally
MANDATORY → fail if no transaction exists
NOT_SUPPORTED → suspend any existing transaction
NEVER → fail if a transaction exists
NESTED → savepoints (DB-dependent)

👉 In most applications:

REQUIRED and REQUIRES_NEW cover 95% of use cases
the others are niche and should be used intentionally

5.2 Isolation: How Much You See of Other Transactions

Isolation defines how concurrent transactions affect each other.

Default:

@Transactional(isolation = Isolation.DEFAULT)

This delegates to the database default (often READ_COMMITTED).

The Practical Levels

READ_COMMITTED You only see committed data. Good balance between consistency and performance.
REPEATABLE_READ Data read once won’t change during the transaction. Prevents non-repeatable reads.
SERIALIZABLE Full isolation. Transactions behave as if executed sequentially. Very safe. Very expensive.

Higher isolation = fewer anomalies = lower throughput.

👉 Rule of thumb:

trust your DB defaults
increase isolation only when you have a proven concurrency problem

5.3 Rollback Rules: The Most Common Source of Bugs

This is where many Spring developers get burned.

By default:

Spring rolls back only on unchecked exceptions (RuntimeException) and Error.

That means this will NOT rollback:

@Transactional
public void placeOrder() throws Exception {
    orderRepository.save(order);
    throw new Exception("Checked exception");
}

From a business perspective, this operation clearly failed.

From Spring’s perspective, however, this is a checked exception — and the transaction is committed.

No rollback. No warning. Just inconsistent data.
Yes, really.

Explicit Rollback Rules

You can override this:

@Transactional(rollbackFor = Exception.class)

Or the opposite:

@Transactional(noRollbackFor = BusinessException.class)

This is essential when:

using checked exceptions
modeling business failures explicitly

A Better Approach: Business Exceptions as Runtime Exceptions

In most real-world Spring Boot applications, business failures should invalidate the transaction.

A clean and effective way to model this is by using custom unchecked exceptions:

public class PaymentFailedException extends RuntimeException {

}

@Transactional
public void placeOrder() {
    orderRepository.save(order);
    throw new PaymentFailedException();
}

This approach has several advantages:

rollback happens automatically
transactional behavior is explicit
no need for extra configuration
business intent is clear

If the operation fails, the transaction fails. No ambiguity.

👉 Always be explicit if you rely on checked exceptions.

5.4 `readOnly`: Small Flag, Big Impact

@Transactional(readOnly = true)

This:

hints the persistence provider
may optimize flushing and dirty checking
documents intent clearly

Perfect for:

query-only service methods
read-heavy paths

Not a silver bullet — but a good habit.

5.5 `timeout`: A Safety Net

@Transactional(timeout = 5)

If the transaction runs longer than 5 seconds:

it’s rolled back

Useful for:

protecting DB resources
preventing stuck transactions

Especially relevant under load.

A Hard-Earned Lesson

Most transactional bugs are not caused by:

wrong SQL
broken databases

They come from:

wrong assumptions about propagation
unexpected rollback behavior
hidden transactional boundaries

Understanding these attributes turns @Transactional from a “magic annotation” into a precise tool.

6. Common Transactional Pitfalls in Spring Boot

At this point, we understand how transactions should work.

Unfortunately, many transactional bugs don’t come from a lack of knowledge —

they come from small details that are easy to miss and hard to debug.

Let’s go through the most common pitfalls you’ll encounter in real Spring Boot applications.

6.1 Self-Invocation: The Silent Transaction Killer

This is probably the most famous Spring transactional pitfall.

@Service
public class OrderService {

    public void placeOrder() {
        saveOrder(); // ❌ no transaction
    }

    @Transactional
    public void saveOrder() {
        orderRepository.save(order);
    }
}

At first glance, this looks fine.

It’s not.

What’s the problem?

The call to saveOrder() happens inside the same class.

It never goes through the Spring proxy.

Result:

@Transactional is completely ignored
no transaction is started
no error, no warning

This is one of the reasons transactional bugs feel “random”.

How to fix it

move the transactional method to another bean
or make sure it’s called from outside the class

@Service
public class OrderPersistenceService {

    @Transactional
    public void saveOrder(Order order) {
        orderRepository.save(order);
    }
}

6.2 `@Transactional` on `private` (or non-public) Methods

Another classic.

@Transactional
private void saveOrder() {
    ...
}

This will never work.

Spring proxies intercept public method calls only (by default).

Private, protected, or package-private methods are ignored.

Again:

no exception
no warning
just no transaction

👉 Transactional methods must be public. Always.

6.3 Catching Exceptions and Accidentally Preventing Rollback

This one is subtle — and extremely common.

@Transactional
public void placeOrder() {
    try {
        paymentService.charge();
    } catch (PaymentFailedException ex) {
        log.error("Payment failed", ex);
    }
}

Looks harmless, right?

But now:

the exception is swallowed
the method completes normally
the transaction is committed

Spring rolls back only if the exception escapes the transactional boundary.

Correct approaches

Either:

rethrow the exception
or mark the transaction for rollback manually

TransactionAspectSupport.currentTransactionStatus().setRollbackOnly();

But in most cases, rethowing is the cleanest solution.

6.4 Mixing Transactional and Non-Transactional Logic

Sometimes transactional methods grow too much:

@Transactional
public void placeOrder() {
    orderRepository.save(order);
    emailService.sendConfirmationEmail(); // ❌
}

Problems:

emails are slow
emails can fail
emails should not be part of a DB transaction

If the email fails:

do you really want to rollback the order?

Probably not.

Better approach

keep transactions short
isolate side effects
use events or async processing

Transactional boundaries should protect data consistency, not external systems.

6.5 Unexpected Rollbacks (`UnexpectedRollbackException`)

Sooner or later, you’ll see this:

UnexpectedRollbackException: Transaction silently rolled back

This usually happens when:

an inner transactional method marks the transaction as rollback-only
but the outer method tries to commit

Common causes:

caught exceptions inside nested transactional calls
mixed propagation settings
overuse of REQUIRES_NEW

When you see this exception:

don’t look at the commit
look at what marked the transaction as rollback-only earlier

6.6 Long-Running Transactions

Technically correct. Practically dangerous.

Long transactions:

lock rows for too long
reduce throughput
increase deadlock probability

Common causes:

doing I/O inside transactions
calling remote services
waiting for user input (yes, it happens…)

Rule:

Transactions should be as short as possible, but as long as necessary.

A Pattern You’ll Start to Recognize

Most transactional problems share a common theme:

the code looks correct
the behavior is implicit
Spring does exactly what you told it to do — not what you meant

That’s why:

understanding proxies
defining clear boundaries
modeling failures explicitly

…is more important than memorizing annotations.

7. `@Transactional` and `@Async`: A Dangerous Combination

At some point, almost every Spring Boot developer tries to combine:

@Transactional → consistency
@Async → performance

On paper, it sounds like a great idea.

In practice, it’s one of the most misunderstood and dangerous combinations in Spring.

Let’s clear things up.

The Core Problem: Different Threads, Different Transactions

@Transactional is thread-bound.

A transaction:

is associated with the current thread
lives and dies inside that thread

@Async, on the other hand:

executes the method in a different thread
outside the original call stack

So this code:

@Transactional
public void placeOrder() {
    orderRepository.save(order);
    asyncService.sendConfirmationEmail(order);
}

@Async
public void sendConfirmationEmail(Order order) {
    // ...
}

does not mean:

“send the email in the same transaction, but asynchronously”

It means:

“start a completely separate execution, with no transaction at all (unless explicitly defined)”

The Most Common Wrong Assumption

Many developers assume:

“If the async method is called from a transactional one, it participates in the same transaction.”

It doesn’t.

Ever.

Different thread = different transactional context.

What Happens in Practice

Let’s look at a slightly more subtle example:

@Transactional
public void placeOrder() {
    orderRepository.save(order);
    asyncService.notifyWarehouse(order);
    throw new RuntimeException("Payment failed");
}

Possible outcome:

transaction rolls back
order is NOT persisted
async method still runs
warehouse is notified about an order that doesn’t exist

This is how distributed inconsistencies are born.

Making `@Async` Transactional (Yes, But…)

You can put @Transactional on an async method:

@Async
@Transactional
public void notifyWarehouse(Order order) {
    ...
}

This creates:

a new transaction
completely independent from the original one

This might be fine — or disastrous — depending on intent.

Again: there is no shared transaction.

Better Patterns Than `@Transactional + @Async`

1. Transactional Events

Spring provides a much safer mechanism:

@Transactional
public void placeOrder() {
    orderRepository.save(order);
    applicationEventPublisher.publishEvent(new OrderPlacedEvent(order));
}

@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void onOrderPlaced(OrderPlacedEvent event) {
    sendEmail(event);
}

Now:

the event is processed only if the transaction commits
no ghost side effects
no inconsistent state

This pattern is gold.

2. Messaging / Event-Driven Architecture

For more complex systems:

Kafka
RabbitMQ
cloud queues

Persist state first, then publish events.

Transactions protect your database, not the world.

A Simple Rule That Saves a Lot of Pain

Never assume an async operation is part of your transaction.

It never is.

If consistency matters:

finish the transaction
then trigger async behavior

Always in that order.

Final Thought on `@Async`

@Async is not dangerous by itself.

What’s dangerous is:

mixing it with transactions
without understanding thread boundaries

Once you internalize this model, the behavior becomes predictable — and safe.

8. Transaction Logging and Debugging

One of the most frustrating things about transactional bugs is that everything looks fine until it’s not.

No errors.

No stack traces.

Just data in the wrong state.

When that happens, logging is often the only way to understand what Spring is actually doing.

Let’s see how to make transactions visible.

Why Transactional Bugs Are Hard to Debug

Transactional behavior is:

implicit
proxy-based
spread across multiple layers

So when a transaction:

starts
commits
rolls back
or is marked as rollback-only

…it usually happens outside your business code.

Without proper logs, you’re debugging blind.

Enabling Transaction Logs in Spring Boot

Spring exposes very useful logs — you just need to turn them on.

In application.yml (or application.properties):

logging:
  level:
    org.springframework.transaction: DEBUG

This alone already shows:

when a transaction is created
when it’s committed
when it’s rolled back

Logging Transaction Boundaries

With transaction logging enabled, you’ll start seeing logs like:

Creating new transaction with name [OrderService.placeOrder]
Participating in existing transaction
Committing JDBC transaction
Rolling back JDBC transaction

This tells you:

where the transaction starts
which method owns it
how nested calls behave

When debugging propagation issues, this is invaluable.

Hibernate / JPA Logs: Seeing What Actually Hits the DB

Transactions are about when changes are flushed.

To see what is executed, enable SQL logs:

logging:
  level:
    org.hibernate.SQL: DEBUG

Optionally, parameter binding:

logging:
  level:
    org.hibernate.type.descriptor.sql: TRACE

Now you can correlate:

transaction boundaries
SQL statements
commit / rollback events

This is often where inconsistencies finally make sense.

Debugging Rollbacks That “Come from Nowhere”

If you’ve ever seen this:

UnexpectedRollbackException: Transaction silently rolled back

it means:

the transaction was marked as rollback-only earlier
but the outer layer tried to commit it anyway

To debug this:

enable transaction logs
look for a setRollbackOnly event
check for swallowed exceptions
inspect nested transactional methods

The rollback never comes from nowhere — it’s just hidden.

Business Logging vs Transaction Logging

A common mistake is relying only on business logs:

log.info("Order placed successfully");

This log may appear:

before the transaction commits
even if the transaction later rolls back

If you need certainty, log:

after commit
or via transactional events

@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void onOrderCommitted(OrderPlacedEvent event) {
    log.info("Order committed: {}", event.getOrderId());
}

Now your logs reflect reality, not intent.

A Debugging Workflow That Actually Works

When dealing with transactional issues:

Enable Spring transaction logs
Enable SQL logs
Identify transaction boundaries
Track exception flow
Verify commit / rollback timing

This approach turns “random behavior” into deterministic behavior.

Final Takeaway

Transactions don’t fail silently.

They fail quietly.

Logging is what gives them a voice.

Once you get used to reading transaction logs, you’ll start spotting problems before they reach production.

9. Conclusion & Takeaways

Transactions are one of the most powerful tools in Spring Boot — but they are also one of the most misunderstood.

Here’s what you should remember:

Transactions are about business consistency, not just database operations. Define your transactional boundaries around business operations, not technical details.
@Transactional is declarative, but precise. Understand propagation, isolation, rollback rules, and method visibility.
Exceptions drive rollbacks.
- Unchecked exceptions → rollback by default
- Checked exceptions → explicit rollback required Model your business exceptions carefully.
Avoid common pitfalls:
- Self-invocation
- Private methods
- Catching exceptions and swallowing them
- Long-running transactions
- Mixing async and transactional logic without awareness
Logging is your friend.

Enable transaction and SQL logging to debug propagation, rollback, and commit behavior. Use @TransactionalEventListener for post-commit business logging.
Async and transactions are tricky.

Transactions are thread-bound. Async methods run in a different thread and have a separate transactional context. Prefer events or queues for safe decoupling.

Final Thought

Spring Boot gives you powerful tools, but with great power comes great responsibility.

Transactions can protect your data, but only if you understand how they work — not just how they look.

💬 I’d love to hear from you:

What are the trickiest transactional issues you’ve faced?
Do you have any favorite patterns for async + transactional operations?
Any hidden pitfalls you’ve learned the hard way?

Share your experiences in the comments — let’s learn from each other.

Inside the Backend: What Really Powers Modern Applications

Gianfranco Coppola — Thu, 30 Oct 2025 07:35:30 +0000

A Deep Dive into the Invisible Core of Modern Applications

When most people think about an application, they picture what they can see and touch — a sleek mobile interface, a beautiful website, an interactive dashboard.

But under that surface lies an invisible engine that actually makes everything happen: the backend.

As a backend developer, I’ve often joked that our best work is the kind no one ever notices — until it stops working. The backend doesn’t seek attention, but it powers everything that matters: data persistence, logic, security, communication, and performance.

This article isn’t about code snippets or frameworks (though we’ll mention a few). It’s about understanding what the backend really does, why it’s essential, and how all its moving parts come together to make modern applications possible.

The Role of the Backend

If the frontend is the face of an application, the backend is the brain and nervous system.

It handles three key things:

Data — storing, retrieving, and transforming information.
Logic — making decisions based on rules or workflows.
Communication — connecting the application with other systems.

Whether you’re building a SaaS product, an e-commerce platform, or a mobile app backend, these three pillars remain the same. The backend is responsible for ensuring that data flows correctly and safely across all parts of the system.

Core Responsibilities of a Backend

1. Data Management

Every backend starts with data.

It could be a PostgreSQL database, a MongoDB collection, or even a distributed data lake — but the principles are the same: store, retrieve, and manipulate data efficiently.

A well-designed backend abstracts away the raw SQL (or NoSQL queries) behind a clean data access layer. Tools like ORMs (e.g., SQLAlchemy, Prisma, or Hibernate) make this easier, but performance tuning and understanding how queries behave remain core skills for any backend developer.

2. Input Validation

Before anything hits the database, it needs to be trusted.

Input validation ensures that data sent from the frontend or other services is complete, correct, and safe.

For instance, you don’t want a user submitting null as their password or an external API sending malformed JSON. Proper validation helps prevent bugs, data corruption, and security issues like SQL injection.

I’ve learned that solid validation is one of those invisible things that users never notice — until it’s missing.

3. Business Logic

This is the heart of the application.

The business logic layer (often called the service layer) is where the actual “rules of the game” live.

Example:

If your app sells subscriptions, this layer decides whether a user can upgrade, when to charge them, and what happens when their payment fails.

It’s where domain knowledge meets code.

A good backend keeps business logic isolated from both the database and the API routes. This makes the system easier to test, reason about, and evolve.

4. External Services & Integrations

Modern applications are rarely self-contained.

Your backend might need to communicate with payment gateways, email providers, analytics tools, or even AI models. This “machine-to-machine” communication often happens via HTTP calls, SDKs, or message queues.

The key challenge here is resilience — handling timeouts, retries, and rate limits gracefully.

When you’re working with multiple integrations, having good error handling and observability is essential to avoid cascading failures.

5. Data Exposure via REST APIs

The backend exposes data to the outside world through APIs — typically RESTful ones that speak JSON over HTTP.

APIs are the contract between your backend and the frontend (or other systems).

Good APIs are:

Predictable
Well-documented
Versioned

Versioning (e.g., /api/v1/users) prevents breaking existing clients when you update logic or data structures.

And tools like OpenAPI or Swagger make collaboration with frontend or mobile teams much smoother.

6. Authentication & Authorization

Security is one of the most fundamental backend responsibilities.

Authentication confirms who the user is, while authorization determines what they can access.

There are many patterns here — session-based, JWT, OAuth2 — and the right one depends on your system’s architecture.

A secure backend never trusts input blindly and always validates tokens or credentials before giving access to data or functionality.

7. Error Handling, Logging & Configuration

No backend is perfect. Errors happen — network issues, database timeouts, unexpected input. What matters is how you handle them.

A robust backend:

Logs errors in a structured way (JSON logs are great for this).
Differentiates between client errors (4xx) and server errors (5xx).
Uses centralized logging tools like ELK, Loki, or CloudWatch.

Configuration is another overlooked topic: using environment variables, secrets management, and per-environment settings prevents nasty surprises when deploying to production.

8. Caching & Performance Optimization

Performance isn’t about writing faster code — it’s about making fewer expensive operations.

Caching is one of the most effective tools for this.

For example:

Caching user sessions or API responses in Redis
Storing expensive query results
Using HTTP caching headers (ETag, Cache-Control)

The tricky part is invalidation: making sure the cache stays fresh when data changes. But when done right, caching can drastically improve response times and scalability.

9. Asynchronous Tasks & Background Jobs

Not everything needs to happen inside a request.

Sending emails, generating reports, or cleaning up old data are perfect examples of tasks that can be done asynchronously.

Tools like Celery (Python), Sidekiq (Ruby), or BullMQ (Node.js) let you process these tasks in the background, improving user experience and system performance.

10. Monitoring & Observability

Once your backend is live, you need visibility into how it behaves.

Monitoring goes beyond “is it up?” — it’s about knowing when and why things go wrong.

A well-instrumented backend includes:

Metrics (response times, error rates, queue lengths)
Tracing (e.g., OpenTelemetry, Jaeger)
Dashboards (Prometheus, Grafana, Datadog)

Observability turns backend development from guesswork into engineering.

Popular Languages and Frameworks

Backend development isn’t tied to a single language or stack — it’s an ecosystem of tools, each with its own philosophy and strengths.

Here are some of the most common choices you’ll encounter:

Java / Kotlin → Spring Boot, Micronaut (great for enterprise-scale systems)
Python → Django, Flask, FastAPI (very popular for APIs and data-heavy apps)
JavaScript / TypeScript → Node.js with frameworks like Express, NestJS, or Fastify
C# / .NET Core → common in enterprise and cloud-native environments
Go (Golang) → favored for lightweight, high-performance microservices
Ruby → Ruby on Rails, still used for rapid web development
Rust → gaining traction for highly performant, safe backends

In practice, the “best” choice depends on what you’re building, the team’s experience, and your scalability or performance needs.

Conclusion

The backend is the hidden backbone of modern software.

It handles the invisible work — storing data, enforcing logic, integrating with other systems, and keeping everything secure and fast.

Understanding its moving parts helps you design systems that are not only functional but also reliable and scalable.

If you’re just starting your backend journey, focus on the fundamentals: data, APIs, security, and reliability.

And remember — the best backend code isn’t the one that does the most, but the one that makes everything else run smoothly.

Thanks for reading! If you found this post useful, feel free to share your own backend “lessons learned” in the comments — I’d love to hear how you approach these challenges.

Spring Boot and Validation: A Complete Guide with @Valid and @Validated

Gianfranco Coppola — Mon, 27 Oct 2025 07:56:44 +0000

Introduction

Data validation is one of those topics that every backend developer knows is important—but it often doesn’t get the attention it deserves. A solid validation strategy keeps your APIs clean, secure, and predictable.

In this guide, we’ll explore how to use Spring Boot validation effectively with @Valid and @Validated. You’ll learn how to:

Validate request DTOs cleanly
Handle nested objects and lists
Customize error messages
Manage validation groups for create/update operations
Build centralized exception handling
Implement custom validation annotations with ConstraintValidator

All examples are based on a simple product and category API built with Spring Boot 3, Hibernate Validator, and OpenAPI documentation.

1. Why Validation Matters

Validation helps ensure data integrity, security, and user experience:

Prevents invalid or malicious data from reaching your business logic.
Improves API predictability by enforcing consistent input rules.
Provides clear feedback to clients via structured error responses.

Spring Boot natively supports validation via the Bean Validation API (JSR 380), implemented by Hibernate Validator under the hood.

2. Enabling Validation

Add the spring-boot-starter-validation dependency to your project:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

Once included, Spring automatically integrates it into your controller request mappings.

3. Basic Validation Annotations

Spring Boot’s validation system supports all standard JSR-380 annotations:

Annotation	Description	Example
`@NotNull`	Field cannot be null	`@NotNull Double price`
`@NotBlank`	String cannot be null or empty (ignores spaces)	`@NotBlank String name`
`@Size`	Limits size of strings, arrays, or lists	`@Size(max = 5)`
`@Email`	Validates email format	`@Email String contactEmail`
`@Min`, `@Max`	Numeric boundaries	`@Min(1) @Max(10000)`
`@Positive`, `@Negative`	Must be > 0 or < 0	`@Positive Integer quantity`
`@Past`, `@Future`	For dates	`@Future LocalDate availabilityDate`

4. Example: ProductRequest DTO

Here’s a real-world DTO used in our API:

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@FieldDefaults(level = AccessLevel.PRIVATE)
public class ProductRequest {

    @NotBlank(message = "Product name cannot be blank", groups = {OnCreate.class, OnUpdate.class})
    @Size(min = 2, max = 100, message = "Product name must be between 2 and 100 characters", groups = {OnCreate.class, OnUpdate.class})
    String name;

    @NotNull(message = "Price cannot be null", groups = OnCreate.class)
    @Positive(message = "Price must be positive", groups = {OnCreate.class, OnUpdate.class})
    Double price;

    @NotNull(message = "Category ID is required", groups = OnCreate.class)
    Long categoryId;

    @Valid
    @Size(max = 5, message = "You can add up to 5 tags", groups = {OnCreate.class, OnUpdate.class})
    List<@NotBlank(message = "Tag cannot be blank") String> tags;

    @Email(message = "Invalid email format for warranty", groups = {OnCreate.class, OnUpdate.class})
    String emailForWarranty;

    @Min(value = 0, message = "Discount cannot be negative", groups = {OnCreate.class, OnUpdate.class})
    @Max(value = 80, message = "Discount cannot exceed 80%", groups = {OnCreate.class, OnUpdate.class})
    Integer discountPercentage;

    @Future(message = "Availability date must be in the future", groups = {OnCreate.class, OnUpdate.class})
    LocalDate availabilityDate;

    @Sku(message = "SKU must be 8 uppercase letters or digits", groups = {OnCreate.class, OnUpdate.class})
    String sku;
}

This DTO combines multiple annotation types and supports both create and update operations through validation groups.

5. Nested Object and List Validation

To validate nested objects or lists, use @Valid on the field that contains them.

@Valid
List<@NotBlank(message = "Tag cannot be blank") String> tags;

Spring will automatically cascade the validation down into each element of the list.

For complex nested DTOs (e.g. AddressRequest inside a UserRequest), you’d also annotate the nested field with @Valid.

6. `@Valid` vs `@Validated`

A common source of confusion!

Annotation	Used on	Supports Groups	Typical Use Case
`@Valid`	Method parameters and fields	No	Validate request bodies
`@Validated`	Class level or method level	Yes	Used on method parameters, path variables, or when validation groups are needed

Example:

@PostMapping
public ResponseEntity<ProductResponse> createProduct(
        @Validated(OnCreate.class) @RequestBody ProductRequest request) {
    ...
}

@PutMapping("/{id}")
public ResponseEntity<ProductResponse> updateProduct(
        @PathVariable @Min(1) Long id,
        @Validated(OnUpdate.class) @RequestBody ProductRequest request) {
    ...
}

Here, @Validated enables group-based validation, enforcing different constraints on creation vs update.

Meanwhile, in simpler cases (like categories), you can still use @Valid:

@PostMapping
public ResponseEntity<CategoryResponse> createCategory(
        @Valid @RequestBody CategoryRequest request) {
    ...
}

7. Validation Groups Explained

Validation groups let you define which constraints apply depending on context.

public interface OnCreate {}
public interface OnUpdate {}

Then assign them in your annotations:

@NotNull(groups = OnCreate.class)
@Positive(groups = {OnCreate.class, OnUpdate.class})
Double price;

When validating with @Validated(OnCreate.class), only constraints belonging to that group will be triggered.

This approach is essential for APIs where fields are optional on update but mandatory on create.

8. Custom Error Messages

You can define messages directly in annotations (as shown earlier), or externalize them in a messages.properties file:

product.name.notblank=Product name cannot be blank
product.price.positive=Price must be positive

Then reference them:

@NotBlank(message = "{product.name.notblank}")

This improves maintainability and supports localization.

9. Global Exception Handling for Validation

When validation fails in Spring Boot, two main exceptions are typically thrown:

MethodArgumentNotValidException: triggered when a @Valid or @Validated annotated @RequestBody fails validation.
ConstraintViolationException: triggered when validation fails on method parameters, such as @PathVariable, @RequestParam, or directly on method arguments annotated with @Validated.

If not handled, these exceptions result in default error responses that are not user-friendly and may expose internal details.

To keep your API responses consistent and developer-friendly, you should implement centralized exception handling using @RestControllerAdvice (or @ControllerAdvice, depending on your use case).

@RestControllerAdvice is the preferred choice for REST APIs, as it automatically adds @ResponseBody to all methods, returning structured JSON error responses.
@ControllerAdvice, on the other hand, is more general-purpose and suitable if your application also serves web pages or uses view templates, since it doesn’t assume a JSON response by default.

Both annotations act as global interceptors for exceptions thrown from controllers, allowing you to define a single, centralized place to handle and format error responses.

A typical example looks like this:

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, Object>> handleValidationError(MethodArgumentNotValidException ex) {
        Map<String, Object> errors = new LinkedHashMap<>();
        errors.put("timestamp", LocalDateTime.now());
        errors.put("status", HttpStatus.BAD_REQUEST.value());
        errors.put("errors", ex.getBindingResult().getFieldErrors()
                .stream()
                .map(err -> Map.of("field", err.getField(), "message", err.getDefaultMessage()))
                .toList());
        return ResponseEntity.badRequest().body(errors);
    }

    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<Map<String, Object>> handleConstraintViolation(ConstraintViolationException ex) {
        Map<String, Object> errors = new LinkedHashMap<>();
        errors.put("timestamp", LocalDateTime.now());
        errors.put("status", HttpStatus.BAD_REQUEST.value());
        errors.put("errors", ex.getConstraintViolations()
                .stream()
                .map(v -> Map.of("field", v.getPropertyPath().toString(), "message", v.getMessage()))
                .toList());
        return ResponseEntity.badRequest().body(errors);
    }
}

Why You Should Use @ControllerAdvice

✅ Centralization: all validation errors are managed in one place, improving maintainability.
✅ Consistency: every endpoint returns validation errors with the same JSON structure.
✅ Security: prevents exposing internal exception details to the client.
✅ Extensibility: you can easily extend the same class to handle business or authentication errors in the future.

This approach not only improves developer experience but also helps frontend teams rely on predictable, machine-readable error formats.

10. Custom Validators with ConstraintValidator

Sometimes standard annotations aren’t enough. You can create your own validator easily.

Example: SKU Validator

@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = SkuValidator.class)
public @interface Sku {
    String message() default "Invalid SKU format";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

Validator implementation:

public class SkuValidator implements ConstraintValidator<Sku, String> {

    private static final Pattern SKU_PATTERN = Pattern.compile("^[A-Z0-9]{8}$");

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        return value == null || SKU_PATTERN.matcher(value).matches();
    }
}

Then use it in your DTO:

@Sku(message = "SKU must be 8 uppercase letters or digits")
String sku;

11. Best Practices

✅ Validate at the edge — always in controllers, before reaching the service layer.
✅ Group constraints logically (create/update).
✅ Use @Valid for simple cases, @Validated for grouped or parameter-level validation.
✅ Keep error messages clean and user-friendly.
✅ Centralize exception handling with @ControllerAdvice.
✅ Externalize messages for easier maintenance.
✅ Prefer DTO validation over entity validation to maintain separation of concerns.

12. Conclusion

Validation is more than just checking inputs—it’s part of your API design.

Spring Boot, with Bean Validation, makes it easy to enforce correctness, improve security, and offer better UX.

We’ve covered:

Basic and advanced annotations
Nested and list validation
Custom constraints
Validation groups
Global error handling

🧩 Want more? Check out the GitHub repository for more examples and full implementations and my Pro Starter Kit on Gumroad!

💬 Join the Discussion

What’s your approach to validation and error handling in Spring Boot? Have you tried alternative strategies like custom ErrorResponse wrappers or problem-spring-web? Let’s discuss best practices and experiences from real-world projects.

Share your thoughts in the comments! 👇

Your feedback will help other developers (and me!) improve future articles.

10 Lombok Annotations Every Java Developer Should Know

Gianfranco Coppola — Sun, 26 Oct 2025 19:07:48 +0000

Introduction

Java is a powerful and mature language, but it comes with a cost: a lot of boilerplate code.

Think about the endless getters, setters, constructors, and toString() methods you’ve written over the years. They don’t add business value — they just make your code longer and harder to read.

That’s where Project Lombok comes to the rescue. Lombok uses annotations to generate boilerplate code at compile time, letting you focus on actual logic instead of repetitive syntax.

It integrates perfectly with Spring Boot, which makes it one of the most popular tools in modern Java development.

In this article, we’ll explore 10 Lombok annotations every Java developer should know and discuss best practices and common pitfalls so you can use Lombok effectively and safely.

How to Add Lombok to Your Project

Before you start using Lombok, make sure your project and IDE are properly configured.

Maven

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.32</version>
    <scope>provided</scope>
</dependency>

Gradle

compileOnly 'org.projectlombok:lombok:1.18.32'
annotationProcessor 'org.projectlombok:lombok:1.18.32'

IDE Configuration

IntelliJ IDEA →

Settings > Build, Execution, Deployment > Compiler > Annotation Processors > Enable annotation processing
Eclipse →

Preferences > Java Compiler > Annotation Processing > Enable
VS Code →
1. Make sure you have the Extension Pack for Java installed (includes the Language Support for Java by Red Hat).
2. Open your workspace settings and add: "java.configuration.annotationProcessing.enabled": true
3. Restart VS Code and recompile the project.

Once configured, Lombok’s annotations will work seamlessly in your IDE, and you’re ready to say goodbye to boilerplate.

The 10 Most Useful Lombok Annotations

Here are the top annotations that will make your Java code cleaner, shorter, and more readable.

1. `@Getter` / `@Setter`

These annotations generate standard getter and setter methods automatically.

import lombok.Getter;
import lombok.Setter;

public class User {
    @Getter @Setter
    private String name;

    @Getter
    private int age;
}

At class level:

@Getter
@Setter
public class User {
    private String name;
    private int age;
}

✅ Why is it useful?

Removes repetitive method definitions.
Keeps your classes focused on business logic.
You can control visibility: @Getter(AccessLevel.PROTECTED) for example.

2. `@Data`

Combines several Lombok annotations into one:

@Getter / @Setter
@ToString
@EqualsAndHashCode
@RequiredArgsConstructor

import lombok.Data;

@Data
public class Product {
    private final String id;
    private String name;
}

✅ Why is it useful?

Great for simple DTOs and data containers.
Saves multiple lines of boilerplate.

⚠ When to avoid it:

Not ideal for JPA entities or domain models where you need more control over equality and mutability.

3. `@Builder`

Implements the Builder pattern, letting you create objects in a more expressive and flexible way.

import lombok.Builder;

@Builder
public class User {
    private String name;
    private int age;
}

// Usage
User user = User.builder()
    .name("Alice")
    .age(25)
    .build();

✅ Why is it useful?

Eliminates complex constructors with many parameters.
Improves code readability.
Makes object creation safe and expressive (especially in tests).

4. `@AllArgsConstructor` / `@NoArgsConstructor`

Generates constructors with all fields or no fields respectively.

import lombok.AllArgsConstructor;
import lombok.NoArgsConstructor;

@AllArgsConstructor
@NoArgsConstructor
public class User {
    private String name;
    private int age;
}

✅ Why is it useful?

Perfect for frameworks like JPA or Jackson, which require a no-args constructor.
Speeds up development when dealing with DTOs or entity creation.

5. `@RequiredArgsConstructor`

Generates a constructor for all final fields (and those marked with @NonNull).

import lombok.RequiredArgsConstructor;

@RequiredArgsConstructor
public class Service {
    private final Repository repository;
}

In Spring Boot, this shines with constructor injection:

@Service
@RequiredArgsConstructor
public class UserService {
    private final UserRepository userRepository;
}

✅ Why is it useful?

Encourages dependency injection via constructors.
No need for @Autowired.
Promotes immutability and cleaner design.

6. `@FieldDefaults` (and Advanced Combo)

@FieldDefaults lets you define default modifiers for fields across a class, reducing repetitive access modifiers.

It has two main properties:

level → sets default access level (PRIVATE, PROTECTED, PUBLIC).
makeFinal → makes all fields final if true.

Example 1: Set default access level

import lombok.experimental.FieldDefaults;
import static lombok.AccessLevel.PRIVATE;

@FieldDefaults(level = PRIVATE)
public class UserService {
    String username;
    String email;
}

Example 2: Combine with makeFinal for immutability

import lombok.experimental.FieldDefaults;
import lombok.RequiredArgsConstructor;
import static lombok.AccessLevel.PRIVATE;

@FieldDefaults(level = PRIVATE, makeFinal = true)
@RequiredArgsConstructor
public class UserService {
    UserRepository userRepository;
    NotificationService notificationService;
}

✅ Why is it useful?

Keeps field definitions consistent and clean.
Reduces risk of accidentally exposing internal state.
Perfect for constructor injection when combined with @RequiredArgsConstructor.

💡 Tip: You don’t always need both properties.

Use only level for access control, or makeFinal when enforcing immutability.

7. `@Value`

@Value is like @Data, but it creates immutable classes:

All fields are private final.
No setters are generated.

import lombok.Value;

@Value
public class Address {
    String city;
    String zip;
}

✅ Why is it useful?

Promotes immutability and thread-safety.
Excellent for DTOs and value objects.
Works perfectly with the Builder pattern.

8. `@Slf4j`

Generates an SLF4J logger automatically.

Without Lombok:

private static final Logger log = LoggerFactory.getLogger(MyService.class);

With Lombok:

import lombok.extern.slf4j.Slf4j;

@Slf4j
public class OrderService {

    public void processOrder(String orderId) {
        log.info("Processing order: {}", orderId);
        try {
            // some business logic
        } catch (Exception e) {
            log.error("Error processing order {}", orderId, e);
        }
    }
}

✅ Why is it useful?

No more manual logger setup.
Fully compatible with Spring Boot’s default logging (SLF4J + Logback).
Supports structured logging and all log levels (info, warn, error, debug).
Keeps code cleaner and easier to maintain.

Other variants available:

@Log, @Log4j, @Log4j2, @CommonsLog — but @Slf4j is the most common and recommended.

9. `@UtilityClass`

@UtilityClass is a hidden gem in Lombok’s toolkit.

It’s used to create utility classes — classes that only contain static methods and constants.

Lombok will automatically:

Make the class final.
Add a private constructor (preventing instantiation).
Convert all fields and methods to static.

import lombok.experimental.UtilityClass;

@UtilityClass
public class MathUtils {
    public int add(int a, int b) {
        return a + b;
    }

    public final double PI = 3.14159;
}

Usage:

int sum = MathUtils.add(5, 10);

✅ Why is it useful?

Eliminates boilerplate for utility classes.
Enforces correct usage (non-instantiable, static members).
Perfect for helpers, validators, or constants.

Without Lombok, you’d need to write:

public final class MathUtils {
    private MathUtils() {}
    public static int add(int a, int b) {
        return a + b;
    }
}

With Lombok — one line. Clean and elegant.

10. `@ToString`

Generates a toString() method automatically.

import lombok.ToString;

@ToString
public class User {
    private String name;
    private int age;
}

Exclude fields when needed:

@ToString(exclude = "password")
public class User {
    private String username;
    private String password;
}

✅ Why is it useful?

Great for debugging and logging.
Avoids maintenance issues when adding or renaming fields.
Works perfectly with @Data or on its own for better control.

Best Practices & When to Avoid Lombok

While Lombok can make your life easier, it’s not always the right tool for every situation.

Avoid overusing @Data It may generate methods you don’t need and cause issues in entities or complex models.
Prefer immutability Use @Value or makeFinal = true in @FieldDefaults when possible.
Mind your team’s tooling Ensure everyone’s IDE and CI/CD pipelines support annotation processing.
Be explicit when needed Don’t hide complexity behind annotations if it reduces clarity for new contributors.

Conclusion

Lombok is a must-have library for Java developers who value clean, maintainable, and expressive code.

It removes the friction of boilerplate, integrates seamlessly with Spring Boot, and helps you focus on what truly matters: business logic.

Key takeaways:

Use Lombok for faster development and cleaner classes.
Combine @FieldDefaults with @RequiredArgsConstructor for elegant constructor injection.
Use @Value for immutability and @Builder for readability.
Don’t overlook gems like @Slf4j and @UtilityClass.

✅ Want more? Check out the GitHub repository for more examples and full implementations and my Pro Starter Kit on Gumroad!

💬 Join the Discussion

What do you think about Lombok? Do you love it, or do you find it hides too much magic?

Share your thoughts in the comments!

👉 How has Lombok helped (or hurt) your Java projects?
👉 Which annotations do you use the most?

Your feedback will help other developers (and me!) improve future articles.

How to Write Clean DTO & Entity Mappers in Java (with Spring Boot)

Gianfranco Coppola — Sun, 26 Oct 2025 18:08:17 +0000

How to Write Clean DTO & Entity Mappers in Java (with Spring Boot)

Introduction

When building a Spring Boot application, one of the most common patterns you’ll encounter is mapping between Entities and DTOs (Data Transfer Objects).

But why should you separate them? Why not just expose your JPA entities directly through your API?

The short answer: maintainability, security, and performance.

Maintainability: DTOs decouple your API layer from the database schema, giving you flexibility to change one without breaking the other.
Security: You can control exactly what data is exposed to the client, avoiding accidental leaks of sensitive fields.
Performance: DTOs can be optimized to include only the required fields, reducing payload size and unnecessary joins.

In this article, we’ll explore:

What DTOs are and why you need them
How to map Entities to DTOs (and vice versa) cleanly
Different approaches: manual mapping, MapStruct, and ModelMapper
Best practices for keeping your code clean and maintainable

What is a DTO and Why Use It?

A DTO (Data Transfer Object) is a plain object used to transfer data between processes, layers, or services—typically between your API and the client.

Entity vs DTO

Entity: Represents a database table. Usually annotated with @Entity and tied to JPA/Hibernate.
DTO: Represents the data structure you expose in your API response or accept in requests. It is not managed by JPA.

Common Problems Without DTO

If you expose your Entity directly:

Tight coupling: Any change in your database model breaks your API.
Sensitive data exposure: Internal fields like IDs or relationships may leak.
Lazy loading issues: Serializing JPA entities directly can trigger unwanted queries or LazyInitializationException.

DTOs solve these problems by acting as a safe and controlled data layer.

Our Example Domain: Category & Product

We’ll use the following Entities:

@Entity
@Table(name = "categories")
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@FieldDefaults(level = AccessLevel.PRIVATE)
public class Category {

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

    @Column(nullable = false, unique = true)
    String name;

    @OneToMany(mappedBy = "category", cascade = CascadeType.ALL, orphanRemoval = true)
    List<Product> products;
}

@Entity
@Table(name = "products")
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@FieldDefaults(level = AccessLevel.PRIVATE)
public class Product {

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

    @Column(nullable = false)
    String name;

    @Column(nullable = false)
    Double price;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "category_id", nullable = false)
    Category category;
}

And the following DTOs:

CategoryRequest (for creating categories)
ProductRequest (for creating products)
ProductResponse (for returning product data)

Example:

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@FieldDefaults(level = AccessLevel.PRIVATE)
public class ProductResponse {
    Long id;
    String category;
    String name;
    Double price;
}

Approaches to Mapping Entities and DTOs

1. Manual Mapping

The most basic approach: write the conversion logic by hand.

Example for Product:

public class ProductMapper {

    public static ProductResponse toResponse(Product product) {
        return ProductResponse.builder()
                .id(product.getId())
                .name(product.getName())
                .price(product.getPrice())
                .category(product.getCategory().getName()) // Extract category name
                .build();
    }

    public static Product toEntity(ProductRequest request, Category category) {
        return Product.builder()
                .name(request.getName())
                .price(request.getPrice())
                .category(category)
                .build();
    }
}

Pros: Full control, no dependencies

Cons: Boilerplate, hard to maintain at scale

2. Automatic Mapping with Libraries

MapStruct

MapStruct is a compile-time code generator for Java bean mappings. It uses annotations to define the mapping between source and target objects, and then generates the implementation at build time.

This means:

No reflection at runtime → faster than libraries like ModelMapper
Compile-time type checking → if a field mapping is missing or incorrect, you get a compiler error
No runtime surprises → everything is generated as plain Java code

How does MapStruct work?

When you define an interface and annotate it with @Mapper, MapStruct creates a class that implements it during compilation.

Example:

@Mapper(componentModel = "spring")
public interface ProductMapper {

    @Mapping(source = "category.name", target = "category")
    ProductResponse toResponse(Product product);

    @Mapping(source = "categoryId", target = "category.id")
    Product toEntity(ProductRequest request);
}

Breaking Down the Mapping

Product → ProductResponse
- id → id (same name → automatically mapped)
- name → name (same name → automatically mapped)
- price → price (same name → automatically mapped)
- product.category.name → category (custom mapping because the field names differ)
ProductRequest → Product
- name → name (automatic)
- price → price (automatic)
- categoryId → category.id (nested property mapping)

Generated Code Example (by MapStruct)

After compilation, MapStruct generates an implementation like this:

`@Component  public  class  ProductMapperImpl  implements  ProductMapper { @Override  public ProductResponse toResponse(Product product) { if (product == null) { return  null;
        }

        ProductResponse.ProductResponseBuilder  productResponse  = ProductResponse.builder();
        productResponse.id(product.getId());
        productResponse.name(product.getName());
        productResponse.price(product.getPrice()); if (product.getCategory() != null) {
            productResponse.category(product.getCategory().getName());
        } return productResponse.build();
    } @Override  public Product toEntity(ProductRequest request) { if (request == null) { return  null;
        }

        Product.ProductBuilder  product  = Product.builder();
        product.name(request.getName());
        product.price(request.getPrice()); if (request.getCategoryId() != null) { Category  category  =  new  Category();
            category.setId(request.getCategoryId());
            product.category(category);
        } return product.build();
    }
}`

✔ Notice how MapStruct takes care of null checks and builder patterns automatically.

Pros and cons of MapStruct

Pros:
- Compile-time safety
- High performance
- Clear, explicit mappings
Cons:
- Requires additional annotation processing setup

ModelMapper

Uses reflection at runtime:

@Configuration
public class MapperConfig {
    @Bean
    public ModelMapper modelMapper() {
        return new ModelMapper();
    }
}

@Service
public class ProductService {

    private final ModelMapper modelMapper;

    public ProductService(ModelMapper modelMapper) {
        this.modelMapper = modelMapper;
    }

    public ProductResponse toResponse(Product product) {
        return modelMapper.map(product, ProductResponse.class);
    }
}

With nested fields (like category.name), you need extra configuration for ModelMapper.

Best Practices for Clean Mapping

Keep mappers simple: No business logic inside.
Place mappers logically: Usually in mapper or inside the related module/package.
Choose the right approach:
- Manual mapping: Small projects, simple models.
- MapStruct: Most production apps (fast, safe).
- ModelMapper: Quick prototypes or POCs.
Avoid over-fetching: Map only the fields required by your API.
Benchmark performance: For large-scale apps, MapStruct > Manual > ModelMapper in most cases.

Conclusion

Separating Entities and DTOs is a fundamental best practice in modern Spring Boot applications. It makes your code cleaner, more secure, and easier to maintain.
When it comes to mapping:

Manual mapping for small apps
MapStruct for most production scenarios
ModelMapper for quick prototypes

Want more? Check out the GitHub repository for more examples and full implementations and my Pro Starter Kit on Gumroad.

✅ What’s your favorite mapping strategy? Comment below and share your experience!

The Ultimate Guide to HTTP Status Codes in REST APIs

Gianfranco Coppola — Tue, 02 Sep 2025 06:49:16 +0000

The Ultimate Guide to HTTP Status Codes in REST APIs

When building REST APIs, HTTP status codes play a crucial role in communication between the client and the server. They aren’t just numbers; they provide valuable context about what happened with a request—whether it succeeded, failed, or needs further action.

In this guide, you’ll learn:

Why status codes matter for REST APIs.
The main HTTP status code categories.
Which codes to use and when.
Best practices for consistent responses.
Practical Spring Boot examples to implement them.
How to handle errors properly with custom responses.

Why HTTP Status Codes Matter

Status codes are more than formalities—they enhance client-server communication and developer experience. When used correctly:

Clients know how to respond (e.g., retry, show an error message).
APIs are self-descriptive, reducing the need for extra documentation.
Debugging becomes easier, as error codes indicate the exact problem.

Incorrect usage can confuse API consumers and lead to bad UX. For example, returning 200 OK for an invalid request hides the real issue.

Categories of HTTP Status Codes

HTTP status codes are grouped into five categories:

1xx – Informational

Indicates the request was received and is being processed.
Rarely used in REST APIs.
Example: 100 Continue.

2xx – Success

Indicates the request was successfully processed.
Common codes:
- 200 OK – Generic success response.
- 201 Created – Resource successfully created.
- 202 Accepted – Request accepted but processing is asynchronous.
- 204 No Content – Action successful, no body returned.

3xx – Redirection

Indicates further action is needed (usually another URL).
Common in browsers, rarely in APIs.
Example: 301 Moved Permanently.

4xx – Client Errors

The client sent an invalid request.
Common codes:
- 400 Bad Request – Invalid input or missing parameters.
- 401 Unauthorized – Authentication required or failed.
- 403 Forbidden – Authenticated, but no permission.
- 404 Not Found – Resource doesn’t exist.
- 409 Conflict – Request conflicts with the current state.
- 422 Unprocessable Entity – Validation error.

5xx – Server Errors

Something went wrong on the server side.
Common codes:
- 500 Internal Server Error – Generic server error.
- 503 Service Unavailable – Server temporarily down.

Most Common HTTP Status Codes and When to Use Them

Here’s a quick guide to avoid confusion:

200 OK
- Use when the request succeeds and returns data.
```
{
  "id": 1,
  "name": "John Doe"
}
```
201 Created
- Use after successfully creating a resource.
- Example: POST request creating a user.
202 Accepted
- Use when the request has been accepted for processing but the operation is asynchronous.
- Example: triggering a background job, processing a file upload, sending an email.
```
{
  "code": 202,
  "message": "Processing started",
  "details": "You will receive a callback when the job completes"
}
```
204 No Content
- Use for successful operations without a response body (e.g., DELETE).
400 Bad Request
- Use when the client sends invalid input.
- Example: Missing required fields.
401 Unauthorized vs 403 Forbidden
- 401 – The client must authenticate.
- 403 – The client is authenticated but not allowed.
404 Not Found
- Resource not found (e.g., wrong ID).
409 Conflict
- Use when there’s a resource state conflict (e.g., duplicate username).
422 Unprocessable Entity
- Validation passed structurally but semantically invalid (e.g., age < 0).
500 Internal Server Error
- Unexpected server failure—should be avoided as much as possible.

Best Practices for Choosing the Right Status Code

✅ Be consistent: If you use 201 for resource creation in one endpoint, don’t switch to 200 in another.
✅ Don’t overuse 200: Returning 200 OK for every response defeats the purpose of HTTP status codes.
✅ Provide meaningful error responses: Include a JSON body with code, message, and optionally details.
✅ Follow REST conventions: Avoid creating custom semantics when a standard code exists.

Practical Examples with Spring Boot

Using `ResponseEntity` to Set Status Codes

Spring Boot makes it easy to control status codes via ResponseEntity.

// GET
@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    Optional<User> user = userService.findById(id);
    return user.map(ResponseEntity::ok)
               .orElseGet(() -> ResponseEntity.notFound().build());
}

// POST
@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {
    User createdUser = userService.save(user);
    URI location = URI.create("/users/" + createdUser.getId());
    return ResponseEntity.created(location).body(createdUser);
}

// PUT
@PutMapping("/users/{id}")
public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody User user) {
    Optional<User> updatedUser = userService.update(id, user);
    return updatedUser.map(ResponseEntity::ok)
                      .orElseGet(() -> ResponseEntity.notFound().build());
}

// DELETE
@DeleteMapping("/users/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
    userService.delete(id);
    return ResponseEntity.noContent().build();
}

// ASYNC example with 202
@PostMapping("/process")
public ResponseEntity<String> startProcess() {
    processService.startBackgroundJob();
    URI statusUri = URI.create("/process/status/123");
    return ResponseEntity.accepted()
                         .location(statusUri)
                         .body("Processing started");
}

Error Handling and Custom Responses

Instead of returning raw error messages, structure your error responses.

Global Exception Handling with `@ControllerAdvice`

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
        ErrorResponse error = new ErrorResponse(404, "Resource not found", ex.getMessage());
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
}

Example Error Response

{
  "code": 404,
  "error": "Resource not found",
  "message": "User with id 123 not found"
}

This approach makes your API predictable and easier to debug.

Conclusion

HTTP status codes are essential for building robust, self-descriptive APIs. Choosing the right one improves communication, reduces confusion, and makes your API a joy to consume.

✅ Use the correct code for each scenario.
✅ Be consistent and follow REST conventions.
✅ Provide meaningful error messages.

Check out the GitHub repository for more examples and full implementations. And if you want to go further, read my next article “Choosing the Right HTTP Method for Your REST API”, or discover my Pro Starter Kit on Gumroad.

Choosing the Right HTTP Method for Your REST API

Gianfranco Coppola — Sun, 31 Aug 2025 18:36:34 +0000

✅ Choosing the Right HTTP Method for Your REST API

Introduction

When designing a REST API, choosing the right HTTP method is more than a convention—it’s a fundamental aspect of API design. The HTTP method you pick impacts the clarity, consistency, and maintainability of your API.

A well-designed API is easy to understand because developers can predict its behavior based on standard HTTP semantics. Misusing methods (e.g., using POST for everything) can lead to confusion, poor documentation, and even security risks.

In this article, we’ll explore:

✅ The most common HTTP methods
✅ When to use each
✅ Key concepts like idempotence and safety
✅ Practical examples using Spring Boot
✅ Real-world tips (file uploads, logical deletes)

Overview of HTTP Methods

The HTTP specification defines several methods, but in REST APIs, the most common are:

GET: Retrieve data from the server.
POST: Create a new resource on the server.
PUT: Update or replace an existing resource.
PATCH: Partially update an existing resource.
DELETE: Remove a resource from the server.

Each method has a specific purpose and semantic meaning defined by the HTTP/1.1 specification (RFC 7231). Let’s see how to use them correctly.

🔍 Why Choosing the Right Method Matters

Using the proper HTTP method:

Improves clarity for API consumers
Aligns your API with RESTful best practices
Ensures compatibility with HTTP caching, proxies, and tools
Helps with SEO and API discoverability when exposed as OpenAPI/Swagger

🔑 Common HTTP Methods and When to Use Them

GET

Purpose: Retrieve resources without modifying them.
Characteristics:
- Safe: Does not change server state.
- Idempotent: Multiple identical requests return the same result.
Response: 200 OK
Example use case: Get a list of products or retrieve a specific product.

  GET /api/products
  GET /api/products/{id}

🛠 Spring Boot Example

@GetMapping("/api/products")
    public ResponseEntity<List<Product>> getAllProducts() {
        List<Product> products = productService.getAllProducts();
        return ResponseEntity.ok(products);
    }

POST

Purpose: Create a new resource or start an action that modifies state.
Characteristics:
- Not Idempotent: Calling multiple times creates multiple resources or triggers the action repeatedly.
Response: 201 Created
Example use case:
- Add a new product
- Upload a file for processing (e.g., importing a CSV)
- Trigger a background job
```
POST /api/products
```
Request Body:
```
{
  "name": "Updated Laptop",
  "price": 1099.99,
  "categoryId": 2
}
```

🛠 Spring Boot Example

// Create a new product
@PostMapping("/api/products")
    public ResponseEntity<Product> createProduct(@RequestBody Product productRequest) {
        Product product = productService.createProduct(productRequest);
        return ResponseEntity.status(HttpStatus.CREATED).body(product);
    }

// Upload a file for processing
@PostMapping("/import")
public ResponseEntity<String> importProducts(@RequestParam("file") MultipartFile file) {
    productService.importFromFile(file);
    return ResponseEntity.accepted().body("Import started");
}

🔍 Notice the use of 202 Accepted:

This status code is perfect when the request is accepted but the processing will occur asynchronously (e.g., background job, file import).
The client can later check the status of the operation via another endpoint (polling) or with a callback mechanism.

PUT

Purpose: Replace the entire resource with a new one.
Characteristics:
- Idempotent: Multiple identical requests result in the same state.
Response: 200 OK or 204 No Content

Example use case: Update all details of a product.

PUT /api/products/10

Request Body:

{
  "name": "Updated Laptop",
  "price": 1099.99,
  "categoryId": 2
}

🛠 Spring Boot Example

@PutMapping("/api/products/{id}")
    public ResponseEntity<Product> updateProduct(
            @PathVariable Long id,
            @RequestBody Product request) {
        Product product = productService.updateProduct(id, request);
        return ResponseEntity.ok(product);
    }

PATCH

Purpose: Partially update a resource (modify only specific fields)
Characteristics:
- Not necessarily Idempotent: Depends on implementation.
Response: 200 OK or 204 No Content
Example use case: Update only the price of a product.
```
PATCH /api/products/10
```
Request Body:
```
{
  "price": 899.99
}
```

🛠 Spring Boot Example

@PatchMapping("/api/products/{id}")
    public ResponseEntity<Product> updateProduct(
            @PathVariable Long id,
            @RequestBody Map<String, Object> updates) {
        Product product = productService.partialUpdate(id, updates);
        return ResponseEntity.ok(product);
    }

DELETE

Purpose: Delete an existing resource.
Characteristics:
- Idempotent: Deleting the same resource multiple times has the same effect.
Response: 204 No Content
Example use case: Delete a product.

  DELETE /api/products/10

🛠 Spring Boot Example

@DeleteMapping("/api/products/{id}")
    public ResponseEntity<Void> deleteProduct(@PathVariable Long id) {
        productService.deleteProduct(id);
        return ResponseEntity.noContent().build();
    }

🔍 What About Logical Deletion?

In some systems, we don't actually remove the record from the database, but mark it as deleted (soft delete).

You have two common options:

Use DELETE but implement it as logical deletion internally (recommended for API clarity).
Use PATCH with a status field, e.g., { "status": "INACTIVE" }.

🛠 Spring Boot Example

@DeleteMapping("api/products/{id}")
public void softDeleteProduct(@PathVariable Long id) {
    productService.markAsDeleted(id); // Sets deleted flag instead of removing
}

📌 Idempotence and Safety Explained

Two important concepts in HTTP semantics:

Safety: A method is safe if it does not change the server state.
- Safe methods: GET, HEAD.
Idempotence: A method is idempotent if multiple identical requests have the same effect as a single request.
- Idempotent methods: GET, PUT, DELETE.

Why does this matter?
Understanding these concepts helps you design APIs that behave predictably and handle retries without side effects.

Concept	Meaning	Example
Safe	No state changes	GET
Idempotent	Same result after multiple identical calls	PUT, DELETE

✅ Summary Table

HTTP Method	Action	Idempotent	Safe
GET	Read	✅ Yes	✅ Yes
POST	Create	❌ No	❌ No
PUT	Replace	✅ Yes	❌ No
PATCH	Update	✅ Yes*	❌ No
DELETE	Delete	✅ Yes	❌ No

*PATCH is generally idempotent if the same patch is applied multiple times.

⚠️ Common Mistakes to Avoid

❌ Using GET to create or update resources
❌ Using POST for all operations
❌ Returning 200 OK for resource creation (should be 201 Created)

✅ Best Practices for HTTP Methods

Use GET for retrieval
Use POST for creation
Use PUT for full update
Use PATCH for partial update
Use DELETE for deletion
Do not abuse POST: Use POST only for creating resources or triggering processes, not for updates or deletions.
Be consistent: Always use methods according to their semantics.
Avoid custom verbs: Stick to standard HTTP methods instead of inventing new ones like /users/disable.
Handle status codes properly:
- 200 OK → Successful GET or update.
- 201 Created → Resource successfully created.
- 202 Accepted → Request accepted for asynchronous processing (e.g., file import, background job).
- 204 No Content → Successful DELETE or update with no response body.
- 400 Bad Request → Client sent invalid data.
- 404 Not Found → Resource not found.

Want to dive deeper into status codes?

👉 Read my other article: The Ultimate Guide to HTTP Status Codes in REST APIs.

🔗 Conclusion and Related Resources

Choosing the right HTTP method is crucial for building clean, predictable, and RESTful APIs. Stick to standard semantics, respect idempotence and safety, and your API will be easier to understand and maintain.

Want more? Check out the GitHub repository for more examples and full implementations and my Pro Starter Kit on Gumroad.

DEV Community: Gianfranco Coppola

Transactions in Spring Boot: What `@Transactional` Really Does (and Why It Matters)

1. Introduction: Why Transactions Matter More Than You Think

2. What Is a Transaction? (The Basics, Done Right)

The ACID Properties

Atomicity

Consistency

Isolation

Durability

Transactions Are Not Just About Databases

Why Transactions Are Fundamental in Backend Systems

3. Transactions in Spring Boot: The Big Picture

Declarative vs Programmatic Transactions

1. Programmatic transactions

2. Declarative transactions (the Spring way)

The Role of PlatformTransactionManager

4. What Actually Happens When You Use @Transactional

The Simplest (and Most Common) Use Case

Where @Transactional Should Live (and Where It Shouldn’t)

Class-Level vs Method-Level @Transactional

5. Understanding @Transactional Attributes (The Real Ones)

5.1 Propagation: How Transactions Interact with Each Other

REQUIRED (Default)

REQUIRES_NEW

Other Propagation Types (Quick but Honest)

5.2 Isolation: How Much You See of Other Transactions

The Practical Levels

5.3 Rollback Rules: The Most Common Source of Bugs

Explicit Rollback Rules

A Better Approach: Business Exceptions as Runtime Exceptions

5.4 readOnly: Small Flag, Big Impact

5.5 timeout: A Safety Net

A Hard-Earned Lesson

6. Common Transactional Pitfalls in Spring Boot

6.1 Self-Invocation: The Silent Transaction Killer

What’s the problem?

How to fix it

6.2 @Transactional on private (or non-public) Methods

6.3 Catching Exceptions and Accidentally Preventing Rollback

Correct approaches

6.4 Mixing Transactional and Non-Transactional Logic

Better approach

6.5 Unexpected Rollbacks (UnexpectedRollbackException)

6.6 Long-Running Transactions

A Pattern You’ll Start to Recognize

7. @Transactional and @Async: A Dangerous Combination

The Core Problem: Different Threads, Different Transactions

The Most Common Wrong Assumption

What Happens in Practice

Making @Async Transactional (Yes, But…)

Better Patterns Than @Transactional + @Async

1. Transactional Events

2. Messaging / Event-Driven Architecture

A Simple Rule That Saves a Lot of Pain

Final Thought on @Async

8. Transaction Logging and Debugging

Why Transactional Bugs Are Hard to Debug

Enabling Transaction Logs in Spring Boot

Logging Transaction Boundaries

Hibernate / JPA Logs: Seeing What Actually Hits the DB

Debugging Rollbacks That “Come from Nowhere”

Business Logging vs Transaction Logging

A Debugging Workflow That Actually Works

Final Takeaway

9. Conclusion & Takeaways

Final Thought

Inside the Backend: What Really Powers Modern Applications

The Role of the Backend

Core Responsibilities of a Backend

1. Data Management

2. Input Validation

3. Business Logic

4. External Services & Integrations

5. Data Exposure via REST APIs

6. Authentication & Authorization

7. Error Handling, Logging & Configuration

8. Caching & Performance Optimization

9. Asynchronous Tasks & Background Jobs

10. Monitoring & Observability

Popular Languages and Frameworks

The Role of `PlatformTransactionManager`

4. What Actually Happens When You Use `@Transactional`

Where `@Transactional` Should Live (and Where It Shouldn’t)

Class-Level vs Method-Level `@Transactional`

5. Understanding `@Transactional` Attributes (The Real Ones)

`REQUIRED` (Default)

`REQUIRES_NEW`

5.4 `readOnly`: Small Flag, Big Impact

5.5 `timeout`: A Safety Net

6.2 `@Transactional` on `private` (or non-public) Methods

6.5 Unexpected Rollbacks (`UnexpectedRollbackException`)

7. `@Transactional` and `@Async`: A Dangerous Combination

Making `@Async` Transactional (Yes, But…)

Better Patterns Than `@Transactional + @Async`

Final Thought on `@Async`

6. `@Valid` vs `@Validated`

1. `@Getter` / `@Setter`

2. `@Data`

3. `@Builder`

4. `@AllArgsConstructor` / `@NoArgsConstructor`

5. `@RequiredArgsConstructor`

6. `@FieldDefaults` (and Advanced Combo)

7. `@Value`

8. `@Slf4j`

9. `@UtilityClass`

10. `@ToString`

Using `ResponseEntity` to Set Status Codes