Cursor rule

1---
2paths:
3  - "**/*.java"
4---
5# Java Patterns
6 
7> This file extends [common/patterns.md](../common/patterns.md) with Java-specific content.
8 
9## Repository Pattern
10 
11Encapsulate data access behind an interface:
12 
13```java
14public interface OrderRepository {
15    Optional<Order> findById(Long id);
16    List<Order> findAll();
17    Order save(Order order);
18    void deleteById(Long id);
19}
20```
21 
22Concrete implementations handle storage details (JPA, JDBC, in-memory for tests).
23 
24## Service Layer
25 
26Business logic in service classes; keep controllers and repositories thin:
27 
28```java
29public class OrderService {
30    private final OrderRepository orderRepository;
31    private final PaymentGateway paymentGateway;
32 
33    public OrderService(OrderRepository orderRepository, PaymentGateway paymentGateway) {
34        this.orderRepository = orderRepository;
35        this.paymentGateway = paymentGateway;
36    }
37 
38    public OrderSummary placeOrder(CreateOrderRequest request) {
39        var order = Order.from(request);
40        paymentGateway.charge(order.total());
41        var saved = orderRepository.save(order);
42        return OrderSummary.from(saved);
43    }
44}
45```
46 
47## Constructor Injection
48 
49Always use constructor injection — never field injection:
50 
51```java
52// GOOD — constructor injection (testable, immutable)
53public class NotificationService {
54    private final EmailSender emailSender;
55 
56    public NotificationService(EmailSender emailSender) {
57        this.emailSender = emailSender;
58    }
59}
60 
61// BAD — field injection (untestable without reflection, requires framework magic)
62public class NotificationService {
63    @Inject // or @Autowired
64    private EmailSender emailSender;
65}
66```
67 
68## DTO Mapping
69 
70Use records for DTOs. Map at service/controller boundaries:
71 
72```java
73public record OrderResponse(Long id, String customer, BigDecimal total) {
74    public static OrderResponse from(Order order) {
75        return new OrderResponse(order.getId(), order.getCustomerName(), order.getTotal());
76    }
77}
78```
79 
80## Builder Pattern
81 
82Use for objects with many optional parameters:
83 
84```java
85public class SearchCriteria {
86    private final String query;
87    private final int page;
88    private final int size;
89    private final String sortBy;
90 
91    private SearchCriteria(Builder builder) {
92        this.query = builder.query;
93        this.page = builder.page;
94        this.size = builder.size;
95        this.sortBy = builder.sortBy;
96    }
97 
98    public static class Builder {
99        private String query = "";
100        private int page = 0;
101        private int size = 20;
102        private String sortBy = "id";
103 
104        public Builder query(String query) { this.query = query; return this; }
105        public Builder page(int page) { this.page = page; return this; }
106        public Builder size(int size) { this.size = size; return this; }
107        public Builder sortBy(String sortBy) { this.sortBy = sortBy; return this; }
108        public SearchCriteria build() { return new SearchCriteria(this); }
109    }
110}
111```
112 
113## Sealed Types for Domain Models
114 
115```java
116public sealed interface PaymentResult permits PaymentSuccess, PaymentFailure {
117    record PaymentSuccess(String transactionId, BigDecimal amount) implements PaymentResult {}
118    record PaymentFailure(String errorCode, String message) implements PaymentResult {}
119}
120 
121// Exhaustive handling (Java 21+)
122String message = switch (result) {
123    case PaymentSuccess s -> "Paid: " + s.transactionId();
124    case PaymentFailure f -> "Failed: " + f.errorCode();
125};
126```
127 
128## API Response Envelope
129 
130Consistent API responses:
131 
132```java
133public record ApiResponse<T>(boolean success, T data, String error) {
134    public static <T> ApiResponse<T> ok(T data) {
135        return new ApiResponse<>(true, data, null);
136    }
137    public static <T> ApiResponse<T> error(String message) {
138        return new ApiResponse<>(false, null, message);
139    }
140}
141```
142 
143## References
144 
145See skill: `springboot-patterns` for Spring Boot architecture patterns.
146See skill: `jpa-patterns` for entity design and query optimization.
147