The Order Management API

By the end of this chapter the Order Management API runs against the Dockerised PostgreSQL from chapter 02, serves all four endpoints, and — just as important — is a fair baseline: paginated search, real indexes, no intentionally planted slowness. Performance exercises fail when the baseline is a straw man; this one is built the way you would build it for real, which is what makes the bottlenecks later in the series instructive.

The data-access decision: Spring Data JPA

The series uses Spring Data JPA with Hibernate, and the choice deserves an honest paragraph rather than a default.

JPA trades explicitness for leverage. You get dirty checking, transactional consistency, and derived queries — and you pay for them in places a benchmark will find: the persistence context holds managed entities per request (memory and identity-map overhead), lazy associations can turn one query into N+1, and a derived findAll() can silently return a million rows. JdbcClient or jOOQ give you exactly the SQL you write, with none of that machinery — the performance profile is more predictable because there is nothing hidden to mis-predict.

Why JPA anyway: it is what most Spring Boot services actually run, and its failure modes under load are precisely what this series teaches you to see. Every JPA-specific pitfall here has a metric signature — hikaricp_connections_pending, spring_data_repository_invocations_seconds counts, EXPLAIN output — and the method for finding it transfers to any stack. Where JdbcClient would change the answer, the text says so.

The schema

db/init/01-schema.sql runs once when the PostgreSQL volume is empty (chapter 02 wired the mount). It owns the schema; Hibernate only validates against it.

1
CREATE TABLE customers (
2
    id         BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
3
    name       VARCHAR(200) NOT NULL,
4
    email      VARCHAR(320) NOT NULL UNIQUE,
5
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
6
);
7

8
CREATE TABLE orders (
9
    id           BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
10
    customer_id  BIGINT NOT NULL REFERENCES customers (id),
11
    status       VARCHAR(20) NOT NULL,
12
    total_amount NUMERIC(12, 2) NOT NULL,
13
    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
14
    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
15
);
16

17
CREATE TABLE order_items (
18
    id         BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
19
    order_id   BIGINT NOT NULL REFERENCES orders (id) ON DELETE CASCADE,
20
    sku        VARCHAR(40) NOT NULL,
21
    quantity   INT NOT NULL CHECK (quantity > 0),
22
    unit_price NUMERIC(12, 2) NOT NULL
23
);
24

25
-- The search endpoint's access paths. Chosen now, measured later.
26
CREATE INDEX idx_orders_customer_status ON orders (customer_id, status);
27
CREATE INDEX idx_orders_status_created  ON orders (status, created_at DESC);
28
CREATE INDEX idx_order_items_order      ON order_items (order_id);

Index rationale, briefly: idx_orders_customer_status covers the dominant query — “orders for this customer, optionally filtered by status” — where customer_id equality leads and status filters within it. idx_orders_status_created covers “all orders in a status, newest first”, the pagination pattern. idx_order_items_order lets the items join avoid scanning the whole items table. Whether they are sufficient is a chapter 09–10 question, answered with EXPLAIN, not assumed here.

Apply it:

1
docker compose down -v && docker compose up -d postgres

Domain model

1
package in.o612.eng.orders.order;
2

3
import java.util.EnumSet;
4
import java.util.Map;
5
import java.util.Set;
6

7
public enum OrderStatus {
8
    PLACED, PAID, SHIPPED, DELIVERED, CANCELLED;
9

10
    private static final Map<OrderStatus, Set<OrderStatus>> ALLOWED = Map.of(
11
        PLACED,    EnumSet.of(PAID, CANCELLED),
12
        PAID,      EnumSet.of(SHIPPED, CANCELLED),
13
        SHIPPED,   EnumSet.of(DELIVERED),
14
        DELIVERED, EnumSet.noneOf(OrderStatus.class),
15
        CANCELLED, EnumSet.noneOf(OrderStatus.class));
16

17
    public boolean canTransitionTo(OrderStatus target) {
18
        return ALLOWED.get(this).contains(target);
19
    }
20
}

1
package in.o612.eng.orders.order;
2

3
import jakarta.persistence.*;
4
import java.math.BigDecimal;
5
import java.time.Instant;
6
import java.util.ArrayList;
7
import java.util.List;
8

9
@Entity
10
@Table(name = "orders")
11
public class Order {
12

13
    @Id
14
    @GeneratedValue(strategy = GenerationType.IDENTITY)
15
    private Long id;
16

17
    @Column(name = "customer_id", nullable = false)
18
    private Long customerId;
19

20
    @Enumerated(EnumType.STRING)
21
    @Column(nullable = false, length = 20)
22
    private OrderStatus status = OrderStatus.PLACED;
23

24
    @Column(name = "total_amount", nullable = false)
25
    private BigDecimal totalAmount = BigDecimal.ZERO;
26

27
    @Column(name = "created_at", nullable = false, updatable = false)
28
    private Instant createdAt;
29

30
    @Column(name = "updated_at", nullable = false)
31
    private Instant updatedAt;
32

33
    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL,
34
             orphanRemoval = true, fetch = FetchType.LAZY)
35
    private List<OrderItem> items = new ArrayList<>();
36

37
    protected Order() { }
38

39
    public Order(Long customerId) {
40
        this.customerId = customerId;
41
    }
42

43
    public void addItem(OrderItem item) {
44
        item.setOrder(this);
45
        items.add(item);
46
        totalAmount = totalAmount.add(item.getUnitPrice()
47
            .multiply(BigDecimal.valueOf(item.getQuantity())));
48
    }
49

50
    public void transitionTo(OrderStatus target) {
51
        if (!status.canTransitionTo(target)) {
52
            throw new IllegalOrderStateException(
53
                "Cannot move order " + id + " from " + status + " to " + target);
54
        }
55
        status = target;
56
    }
57

58
    @PrePersist
59
    void onCreate() {
60
        createdAt = updatedAt = Instant.now();
61
    }
62

63
    @PreUpdate
64
    void onUpdate() {
65
        updatedAt = Instant.now();
66
    }
67

68
    public Long getId() { return id; }
69
    public Long getCustomerId() { return customerId; }
70
    public OrderStatus getStatus() { return status; }
71
    public BigDecimal getTotalAmount() { return totalAmount; }
72
    public Instant getCreatedAt() { return createdAt; }
73
    public Instant getUpdatedAt() { return updatedAt; }
74
    public List<OrderItem> getItems() { return items; }
75
}

Two decisions to notice:

customerId is a plain column, not a @ManyToOne association. No endpoint ever returns customer details, so mapping the association would only add a proxy, a join temptation, and an accidental lazy-load path — cost with no payoff. The foreign key still enforces integrity in the schema.
items is LAZY and stays lazy in the mapping. Loading it is controlled per-query (below), which is the whole point: the caller decides whether to pay for items.

1
package in.o612.eng.orders.order;
2

3
import jakarta.persistence.*;
4
import java.math.BigDecimal;
5

6
@Entity
7
@Table(name = "order_items")
8
public class OrderItem {
9

10
    @Id
11
    @GeneratedValue(strategy = GenerationType.IDENTITY)
12
    private Long id;
13

14
    @ManyToOne(fetch = FetchType.LAZY)
15
    @JoinColumn(name = "order_id", nullable = false)
16
    private Order order;
17

18
    @Column(nullable = false, length = 40)
19
    private String sku;
20

21
    @Column(nullable = false)
22
    private int quantity;
23

24
    @Column(name = "unit_price", nullable = false)
25
    private BigDecimal unitPrice;
26

27
    protected OrderItem() { }
28

29
    public OrderItem(String sku, int quantity, BigDecimal unitPrice) {
30
        this.sku = sku;
31
        this.quantity = quantity;
32
        this.unitPrice = unitPrice;
33
    }
34

35
    void setOrder(Order order) { this.order = order; }
36
    public Long getId() { return id; }
37
    public String getSku() { return sku; }
38
    public int getQuantity() { return quantity; }
39
    public BigDecimal getUnitPrice() { return unitPrice; }
40
}

1
package in.o612.eng.orders.order;
2

3
public class IllegalOrderStateException extends RuntimeException {
4
    public IllegalOrderStateException(String message) {
5
        super(message);
6
    }
7
}

DTOs and the response boundary

Entities never cross the controller boundary. Besides decoupling, this is a performance choice: serialising a managed entity walks every mapped association, and under Hibernate that can mean lazy-load queries fired during Jackson serialisation — work you cannot see in repository metrics.

1
package in.o612.eng.orders.web;
2

3
import in.o612.eng.orders.order.Order;
4
import in.o612.eng.orders.order.OrderItem;
5
import in.o612.eng.orders.order.OrderStatus;
6
import jakarta.validation.Valid;
7
import jakarta.validation.constraints.*;
8
import java.math.BigDecimal;
9
import java.time.Instant;
10
import java.util.List;
11
import org.springframework.data.domain.Page;
12

13
public final class OrderDtos {
14

15
    public record CreateOrderRequest(
16
        @NotNull Long customerId,
17
        @NotEmpty List<@Valid ItemRequest> items) { }
18

19
    public record ItemRequest(
20
        @NotBlank String sku,
21
        @Min(1) int quantity,
22
        @NotNull @DecimalMin("0.01") BigDecimal unitPrice) { }
23

24
    public record UpdateStatusRequest(@NotNull OrderStatus status) { }
25

26
    public record OrderItemResponse(String sku, int quantity, BigDecimal unitPrice) {
27
        static OrderItemResponse from(OrderItem item) {
28
            return new OrderItemResponse(item.getSku(), item.getQuantity(), item.getUnitPrice());
29
        }
30
    }
31

32
    public record OrderResponse(Long id, Long customerId, OrderStatus status,
33
                                BigDecimal totalAmount, List<OrderItemResponse> items,
34
                                Instant createdAt, Instant updatedAt) {
35
        public static OrderResponse from(Order order) {
36
            return new OrderResponse(
37
                order.getId(), order.getCustomerId(), order.getStatus(),
38
                order.getTotalAmount(),
39
                order.getItems().stream().map(OrderItemResponse::from).toList(),
40
                order.getCreatedAt(), order.getUpdatedAt());
41
        }
42
    }
43

44
    public record PageResponse<T>(List<T> content, int page, int size,
45
                                 long totalElements, int totalPages) {
46
        public static <T> PageResponse<T> from(Page<T> p) {
47
            return new PageResponse<>(p.getContent(), p.getNumber(), p.getSize(),
48
                p.getTotalElements(), p.getTotalPages());
49
        }
50
    }
51

52
    private OrderDtos() { }
53
}

OrderSummary — the projection for search results — lives in its own file, deliberately. JPQL constructor expressions need the class name Hibernate can resolve; a nested record would require the awkward binary name OrderDtos$OrderSummary in the query string. Top-level keeps the JPQL readable:

1
package in.o612.eng.orders.web;
2

3
import in.o612.eng.orders.order.OrderStatus;
4
import java.math.BigDecimal;
5
import java.time.Instant;
6

7
public record OrderSummary(Long id, Long customerId, OrderStatus status,
8
                           BigDecimal totalAmount, Instant createdAt) { }

It exists because the search endpoint must not return items — both for payload size and because the query should never touch order_items. PageResponse is a hand-rolled page envelope rather than serialising Spring Data’s Page directly — it keeps the response contract stable regardless of framework-internal serialization choices.

Repository

1
package in.o612.eng.orders.order;
2

3
import in.o612.eng.orders.web.OrderSummary;
4
import java.util.Optional;
5
import org.springframework.data.domain.Page;
6
import org.springframework.data.domain.Pageable;
7
import org.springframework.data.jpa.repository.EntityGraph;
8
import org.springframework.data.jpa.repository.JpaRepository;
9
import org.springframework.data.jpa.repository.Query;
10
import org.springframework.data.repository.query.Param;
11

12
public interface OrderRepository extends JpaRepository<Order, Long> {
13

14
    @EntityGraph(attributePaths = "items")
15
    @Query("select o from Order o where o.id = :id")
16
    Optional<Order> findByIdWithItems(@Param("id") Long id);
17

18
    @Query("""
19
        select new in.o612.eng.orders.web.OrderSummary(
20
            o.id, o.customerId, o.status, o.totalAmount, o.createdAt)
21
        from Order o
22
        where (:customerId is null or o.customerId = :customerId)
23
          and (:status is null or o.status = :status)
24
        """)
25
    Page<OrderSummary> search(@Param("customerId") Long customerId,
26
                              @Param("status") OrderStatus status,
27
                              Pageable pageable);
28
}

findByIdWithItems fetches the order and its items in one SQL statement. findById alone would leave items a lazy collection; with open-in-view: false (chapter 03), touching it during mapping would throw LazyInitializationException — or, in the more dangerous configuration, silently issue one extra query per order. The @EntityGraph makes the fetch plan explicit and therefore measurable.
search is a single query with optional filters and server-side pagination (Pageable). It returns a projection — four scalar columns plus the constructor — so Hibernate never instantiates Order entities for list traffic. This is the fast path by design; chapter 10 shows what the slow version costs.

Service

1
package in.o612.eng.orders.order;
2

3
import in.o612.eng.orders.web.OrderDtos.*;
4
import io.micrometer.core.instrument.Timer;
5
import org.springframework.data.domain.Page;
6
import org.springframework.data.domain.Pageable;
7
import org.springframework.stereotype.Service;
8
import org.springframework.transaction.annotation.Transactional;
9

10
@Service
11
public class OrderService {
12

13
    private final OrderRepository orders;
14
    private final OrderMetrics metrics;
15

16
    public OrderService(OrderRepository orders, OrderMetrics metrics) {
17
        this.orders = orders;
18
        this.metrics = metrics;
19
    }
20

21
    @Transactional
22
    public OrderResponse create(CreateOrderRequest request) {
23
        Timer.Sample sample = metrics.startCreationTimer();
24
        try {
25
            Order order = new Order(request.customerId());
26
            request.items().forEach(i ->
27
                order.addItem(new OrderItem(i.sku(), i.quantity(), i.unitPrice())));
28
            return OrderResponse.from(orders.save(order));
29
        } finally {
30
            metrics.recordCreation(sample);
31
        }
32
    }
33

34
    @Transactional(readOnly = true)
35
    public OrderResponse getById(long id) {
36
        Order order = orders.findByIdWithItems(id)
37
            .orElseThrow(() -> new OrderNotFoundException(id));
38
        return OrderResponse.from(order);
39
    }
40

41
    @Transactional(readOnly = true)
42
    public Page<OrderSummary> search(Long customerId, OrderStatus status, Pageable pageable) {
43
        return orders.search(customerId, status, pageable);
44
    }
45

46
    @Transactional
47
    public OrderResponse updateStatus(long id, OrderStatus target) {
48
        Order order = orders.findByIdWithItems(id)
49
            .orElseThrow(() -> new OrderNotFoundException(id));
50
        order.transitionTo(target);          // dirty checking writes the UPDATE at commit
51
        metrics.countStatusTransition();
52
        return OrderResponse.from(order);
53
    }
54
}

1
package in.o612.eng.orders.order;
2

3
public class OrderNotFoundException extends RuntimeException {
4
    public OrderNotFoundException(long id) {
5
        super("Order " + id + " not found");
6
    }
7
}

Note readOnly = true on the two queries: it sets Hibernate’s flush mode to manual, skipping dirty checking on every entity in the persistence context — a real, measurable saving on read-heavy endpoints, and the kind of detail that is free to do right in a baseline.

Controller and error mapping

1
package in.o612.eng.orders.web;
2

3
import in.o612.eng.orders.order.*;
4
import in.o612.eng.orders.web.OrderDtos.*;
5
import jakarta.validation.Valid;
6
import org.springframework.data.domain.Pageable;
7
import org.springframework.data.web.PageableDefault;
8
import org.springframework.http.HttpStatus;
9
import org.springframework.http.ResponseEntity;
10
import org.springframework.web.bind.annotation.*;
11

12
@RestController
13
@RequestMapping("/api/orders")
14
public class OrderController {
15

16
    private final OrderService service;
17

18
    public OrderController(OrderService service) {
19
        this.service = service;
20
    }
21

22
    @PostMapping
23
    public ResponseEntity<OrderResponse> create(@Valid @RequestBody CreateOrderRequest request) {
24
        OrderResponse created = service.create(request);
25
        return ResponseEntity.status(HttpStatus.CREATED).body(created);
26
    }
27

28
    @GetMapping("/{id}")
29
    public OrderResponse getById(@PathVariable long id) {
30
        return service.getById(id);
31
    }
32

33
    @GetMapping
34
    public PageResponse<OrderSummary> search(@RequestParam(required = false) Long customerId,
35
                                             @RequestParam(required = false) OrderStatus status,
36
                                             @PageableDefault(size = 20, sort = "createdAt") Pageable pageable) {
37
        return PageResponse.from(service.search(customerId, status, pageable));
38
    }
39

40
    @PatchMapping("/{id}/status")
41
    public OrderResponse updateStatus(@PathVariable long id,
42
                                      @Valid @RequestBody UpdateStatusRequest request) {
43
        return service.updateStatus(id, request.status());
44
    }
45
}

1
package in.o612.eng.orders.web;
2

3
import in.o612.eng.orders.order.IllegalOrderStateException;
4
import in.o612.eng.orders.order.OrderNotFoundException;
5
import org.springframework.http.HttpStatus;
6
import org.springframework.http.ProblemDetail;
7
import org.springframework.web.bind.annotation.ExceptionHandler;
8
import org.springframework.web.bind.annotation.RestControllerAdvice;
9

10
@RestControllerAdvice
11
public class ApiExceptionHandler {
12

13
    @ExceptionHandler(OrderNotFoundException.class)
14
    ProblemDetail notFound(OrderNotFoundException ex) {
15
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
16
            HttpStatus.NOT_FOUND, ex.getMessage());
17
        problem.setTitle("Order not found");
18
        return problem;
19
    }
20

21
    @ExceptionHandler(IllegalOrderStateException.class)
22
    ProblemDetail invalidTransition(IllegalOrderStateException ex) {
23
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
24
            HttpStatus.CONFLICT, ex.getMessage());
25
        problem.setTitle("Illegal status transition");
26
        return problem;
27
    }
28
}

Bean Validation failures (@Valid) return 400 automatically via Spring MVC’s default error handling — no extra code needed.

One last config addition. Unbounded size parameters are an unbounded-result-set bug waiting for a query string, so cap the page size in application.yml (add under spring.data):

1
spring:
2
  data:
3
    web:
4
      pageable:
5
        max-page-size: 100

Why the benchmark traps are designed out

Four patterns distort load-test results so reliably that they are worth naming directly — a baseline containing them would measure the bug, not the service:

Unbounded result sets. A search endpoint without pagination returns whatever the filter matches. As the dataset grows, latency grows with it — the benchmark is really measuring table size. Pageable plus max-page-size bounds the work per request.
N+1 queries. Returning entities whose lazy associations get touched once per row turns one query into 1+N. At 20 rows per page it hides; at dataset scale it saturates the connection pool — which then masquerades as a pool-size problem. The projection in search and the @EntityGraph in findByIdWithItems are the baseline’s defences; chapter 10 breaks one deliberately to show the signature.
Missing indexes. Every table looks indexed on a thousand rows because sequential scans are cheap there. The two composite indexes exist so that the baseline is honest before data arrives; whether they suffice is verified with EXPLAIN under real volume, not assumed.
Entity-as-DTO mapping. Serialising entities couples payload size to mapping depth and hides lazy-loading inside the response writer. The DTO boundary makes serialisation cost proportional to the response you actually designed.

Milestone: exercise all four endpoints

1
./gradlew bootRun

1
# create an order (customer_id 1 exists only after chapter 05's seed —
2
# insert one manually for now)
3
docker compose exec postgres psql -U orders -d orders -c \
4
  "INSERT INTO customers (name, email) VALUES ('Ada Lovelace', 'ada@example.com');"
5

6
curl -s -X POST http://localhost:8080/api/orders \
7
  -H 'Content-Type: application/json' \
8
  -d '{"customerId":1,"items":[{"sku":"SKU-1","quantity":2,"unitPrice":19.99}]}'
9

10
curl -s http://localhost:8080/api/orders/1
11
curl -s "http://localhost:8080/api/orders?customerId=1&status=PLACED"
12
curl -s -X PATCH http://localhost:8080/api/orders/1/status \
13
  -H 'Content-Type: application/json' \
14
  -d '{"status":"PAID"}'

Expected: 201 with the created order body, a 200 fetch including the items array, a paginated JSON envelope (content, page, totalElements, …), and a 200 showing "status":"PAID". A second PATCH to CANCELLED from PAID works; DELIVERED → anything returns the 409 problem detail.

Check that instrumentation sees it: curl -s http://localhost:8080/actuator/prometheus | grep http_server_requests should now show uri="/api/orders" series, and orders_creation_seconds should appear after the first POST.

State of the lab: schema live, four endpoints working, business timers flowing. What is missing is the thing that makes all of this meaningful — realistic data volume. That is chapter 05.

Spring BootJavaPerformancePostgres