Simplify order pipelines with Spring Integration's message-driven design

Spring Boot REST APIs are a great start for handling requests, but when business logic grows complex, a message-driven approach can keep workflows clean and maintainable. A recent open-source project demonstrates how Spring Integration transforms order processing into a flexible pipeline that handles HTTP submissions and file uploads alike—without duplicating core logic.

The sample application, built with Spring Boot 4.1 and Spring Integration 7, processes orders from two distinct entry points: a REST endpoint and a file poller. Each order follows the same validation, routing, and persistence steps, but the framework’s declarative routing and fan-out capabilities make the architecture intuitive and scalable. Developers can use this as a reference for designing hybrid ingestion systems where different input channels converge into a unified processing flow.

A unified pipeline for orders, regardless of source

Whether an order arrives via a POST request to /api/orders or as a CSV file dropped into an input/ directory, the system treats both inputs identically after initial transformation. The application first converts raw payloads—JSON for HTTP or text for files—into a structured Order object. It then applies validation rules to required fields such as id, customer, and total.

Next, the order is routed based on its monetary value:

• Orders with total <= 100 are labeled EXPRESS for expedited handling
• Orders exceeding this threshold go to REVIEW for additional scrutiny

After routing, the order is persisted using Spring Data JPA with PostgreSQL as the runtime database. A fan-out mechanism then triggers multiple downstream actions: archiving the order, generating a summary, and returning a response to the original caller.

This design ensures consistency across input methods while keeping business logic decoupled from transport concerns like HTTP or file I/O.

Behind the scenes: the tech stack and architecture

The project leverages modern Java standards and Spring’s ecosystem to deliver a robust foundation:

Java 21
Spring Boot 4.1
Spring Integration 7 (Java DSL)
Spring Data JPA
PostgreSQL (runtime)
H2 (testing)
Maven

The architecture is split into two primary flows: HTTP and file. Each flow begins with a transformer that converts raw data into domain objects. For HTTP requests, a JsonToOrderTransformer handles JSON payloads. For files, a FileToStringTransformer reads CSV content, followed by a CsvToOrderTransformer to parse rows into Order objects.

Both flows then pass through the same validation and routing components. A content-based router directs orders to either the EXPRESS or REVIEW channel. From there, an OrderStore persists the order via JPA. Finally, a publish-subscribe channel fans out events to archive, summary, and response handlers.

Error handling is built into the file pipeline. Failed processing attempts log errors and move problematic files to input/failed/, preserving the original source for debugging. HTTP errors return structured JSON responses, maintaining API consistency even during failures.

Why choose Spring Integration for message flows?

The framework shines in systems where data moves through multiple stages with clear separation of concerns. In this project, Spring Integration delivers several key advantages:

• Declarative routing: Content-based routers split traffic without manual if-else logic
• Explicit fan-out: Publish-subscribe channels broadcast events to multiple consumers cleanly
• Configurable retry: File handlers can include retry advice to handle transient I/O issues
• Runtime visibility: The integration graph endpoint (/api/integration/graph) renders the live flow as a diagram, aiding troubleshooting and documentation

These features make Spring Integration ideal for systems that need to scale from simple pipelines to complex event-driven workflows. It also serves as a stepping stone for developers transitioning to distributed systems with Kafka or RabbitMQ.

Hands-on: testing and running the sample

Developers interested in experimenting can clone and run the project in minutes. The setup uses Docker Compose for PostgreSQL and a standard Maven build:

# Clone the repository
git clone 

# Navigate to the project
git cd spring-integration-sample

# Start PostgreSQL and dependencies
docker compose up -d

# Build and run the application
mvn clean package
mvn spring-boot:run

Once running, orders can be submitted via HTTP or file. Example commands include:

# Submit an EXPRESS order
curl -X POST  \
  -H "Content-Type: application/json" \
  -d '{"id":"ORD-001","customer":"Alice","description":"Book","total":25.00}'

# Submit a REVIEW order
curl -X POST  \
  -H "Content-Type: application/json" \
  -d '{"id":"ORD-002","customer":"Bob","description":"Laptop","total":1500.00}'

The project includes 38 tests covering unit and integration scenarios. These validate transformation logic, HTTP success and failure paths, duplicate order detection, file processing, retries, and summary aggregation. The tests can be executed directly from the repository.

Practical tips for building message-driven systems

The project’s maintainer shared several lessons that can help teams avoid common pitfalls:

• Use correlation IDs in message headers and propagate them into MDC for end-to-end traceability across log entries
• Split integration configurations by concern—such as HTTP, file, and shared logic—rather than consolidating into a single monolithic class
• Treat stateful components like summary aggregation as batch processes with clear release rules based on size or timeout
• Prefer direct path-variable lookups (e.g., GET /api/orders/{id}) over indirect URL parsing to reduce complexity and improve reliability

These patterns not only simplify maintenance but also make it easier to extend the system as requirements evolve.

A foundation for scalable, event-driven services

This Spring Integration sample offers more than just a technical demo—it’s a practical template for teams building order processing systems that must handle diverse input channels without duplicating business logic. By leveraging Spring’s message-driven architecture, developers can create systems that are easier to test, extend, and monitor.

For those exploring Spring Integration or designing hybrid ingestion pipelines, this project provides a solid starting point before moving to distributed event brokers like Kafka. The modular design and clear separation of concerns make it a valuable resource for both learning and production use.