1---
2name: springboot-patterns
3description: Spring Boot architecture patterns, REST API design, layered services, data access, caching, async processing, and logging. Use for Java Spring Boot backend work.
4origin: ECC
5---
6 
7# Spring Boot Development Patterns
8 
9Spring Boot architecture and API patterns for scalable, production-grade services.
10 
11## When to Activate
12 
13- Building REST APIs with Spring MVC or WebFlux
14- Structuring controller → service → repository layers
15- Configuring Spring Data JPA, caching, or async processing
16- Adding validation, exception handling, or pagination
17- Setting up profiles for dev/staging/production environments
18- Implementing event-driven patterns with Spring Events or Kafka
19 
20## REST API Structure
21 
22```java
23@RestController
24@RequestMapping("/api/markets")
25@Validated
26class MarketController {
27  private final MarketService marketService;
28 
29  MarketController(MarketService marketService) {
30    this.marketService = marketService;
31  }
32 
33  @GetMapping
34  ResponseEntity<Page<MarketResponse>> list(
35      @RequestParam(defaultValue = "0") int page,
36      @RequestParam(defaultValue = "20") int size) {
37    Page<Market> markets = marketService.list(PageRequest.of(page, size));
38    return ResponseEntity.ok(markets.map(MarketResponse::from));
39  }
40 
41  @PostMapping
42  ResponseEntity<MarketResponse> create(@Valid @RequestBody CreateMarketRequest request) {
43    Market market = marketService.create(request);
44    return ResponseEntity.status(HttpStatus.CREATED).body(MarketResponse.from(market));
45  }
46}
47```
48 
49## Repository Pattern (Spring Data JPA)
50 
51```java
52public interface MarketRepository extends JpaRepository<MarketEntity, Long> {
53  @Query("select m from MarketEntity m where m.status = :status order by m.volume desc")
54  List<MarketEntity> findActive(@Param("status") MarketStatus status, Pageable pageable);
55}
56```
57 
58## Service Layer with Transactions
59 
60```java
61@Service
62public class MarketService {
63  private final MarketRepository repo;
64 
65  public MarketService(MarketRepository repo) {
66    this.repo = repo;
67  }
68 
69  @Transactional
70  public Market create(CreateMarketRequest request) {
71    MarketEntity entity = MarketEntity.from(request);
72    MarketEntity saved = repo.save(entity);
73    return Market.from(saved);
74  }
75}
76```
77 
78## DTOs and Validation
79 
80```java
81public record CreateMarketRequest(
82    @NotBlank @Size(max = 200) String name,
83    @NotBlank @Size(max = 2000) String description,
84    @NotNull @FutureOrPresent Instant endDate,
85    @NotEmpty List<@NotBlank String> categories) {}
86 
87public record MarketResponse(Long id, String name, MarketStatus status) {
88  static MarketResponse from(Market market) {
89    return new MarketResponse(market.id(), market.name(), market.status());
90  }
91}
92```
93 
94## Exception Handling
95 
96```java
97@ControllerAdvice
98class GlobalExceptionHandler {
99  @ExceptionHandler(MethodArgumentNotValidException.class)
100  ResponseEntity<ApiError> handleValidation(MethodArgumentNotValidException ex) {
101    String message = ex.getBindingResult().getFieldErrors().stream()
102        .map(e -> e.getField() + ": " + e.getDefaultMessage())
103        .collect(Collectors.joining(", "));
104    return ResponseEntity.badRequest().body(ApiError.validation(message));
105  }
106 
107  @ExceptionHandler(AccessDeniedException.class)
108  ResponseEntity<ApiError> handleAccessDenied() {
109    return ResponseEntity.status(HttpStatus.FORBIDDEN).body(ApiError.of("Forbidden"));
110  }
111 
112  @ExceptionHandler(Exception.class)
113  ResponseEntity<ApiError> handleGeneric(Exception ex) {
114    // Log unexpected errors with stack traces
115    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
116        .body(ApiError.of("Internal server error"));
117  }
118}
119```
120 
121## Caching
122 
123Requires `@EnableCaching` on a configuration class.
124 
125```java
126@Service
127public class MarketCacheService {
128  private final MarketRepository repo;
129 
130  public MarketCacheService(MarketRepository repo) {
131    this.repo = repo;
132  }
133 
134  @Cacheable(value = "market", key = "#id")
135  public Market getById(Long id) {
136    return repo.findById(id)
137        .map(Market::from)
138        .orElseThrow(() -> new EntityNotFoundException("Market not found"));
139  }
140 
141  @CacheEvict(value = "market", key = "#id")
142  public void evict(Long id) {}
143}
144```
145 
146## Async Processing
147 
148Requires `@EnableAsync` on a configuration class.
149 
150```java
151@Service
152public class NotificationService {
153  @Async
154  public CompletableFuture<Void> sendAsync(Notification notification) {
155    // send email/SMS
156    return CompletableFuture.completedFuture(null);
157  }
158}
159```
160 
161## Logging (SLF4J)
162 
163```java
164@Service
165public class ReportService {
166  private static final Logger log = LoggerFactory.getLogger(ReportService.class);
167 
168  public Report generate(Long marketId) {
169    log.info("generate_report marketId={}", marketId);
170    try {
171      // logic
172    } catch (Exception ex) {
173      log.error("generate_report_failed marketId={}", marketId, ex);
174      throw ex;
175    }
176    return new Report();
177  }
178}
179```
180 
181## Middleware / Filters
182 
183```java
184@Component
185public class RequestLoggingFilter extends OncePerRequestFilter {
186  private static final Logger log = LoggerFactory.getLogger(RequestLoggingFilter.class);
187 
188  @Override
189  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
190      FilterChain filterChain) throws ServletException, IOException {
191    long start = System.currentTimeMillis();
192    try {
193      filterChain.doFilter(request, response);
194    } finally {
195      long duration = System.currentTimeMillis() - start;
196      log.info("req method={} uri={} status={} durationMs={}",
197          request.getMethod(), request.getRequestURI(), response.getStatus(), duration);
198    }
199  }
200}
201```
202 
203## Pagination and Sorting
204 
205```java
206PageRequest page = PageRequest.of(pageNumber, pageSize, Sort.by("createdAt").descending());
207Page<Market> results = marketService.list(page);
208```
209 
210## Error-Resilient External Calls
211 
212> **Production recommendation:** Use Resilience4j or Spring Retry for production retry logic
213> with circuit breakers, metrics, and configurable policies.
214 
215```java
216public <T> T withRetry(Supplier<T> supplier, int maxRetries) {
217  final long maxBackoffMillis = 10_000L;
218  int attempts = 0;
219  while (true) {
220    try {
221      return supplier.get();
222    } catch (Exception ex) {
223      attempts++;
224      if (attempts >= maxRetries) {
225        throw ex;
226      }
227      try {
228        long backoff = Math.min((long) Math.pow(2, attempts) * 100L, maxBackoffMillis);
229        Thread.sleep(backoff);
230      } catch (InterruptedException ie) {
231        Thread.currentThread().interrupt();
232        throw ex;
233      }
234    }
235  }
236}
237```
238 
239## Rate Limiting (Filter + Bucket4j)
240 
241**Security Note**: The `X-Forwarded-For` header is untrusted by default because clients can spoof it.
242Only use forwarded headers when:
2431. Your app is behind a trusted reverse proxy (nginx, AWS ALB, etc.)
2442. You have registered `ForwardedHeaderFilter` as a bean
2453. You have configured `server.forward-headers-strategy=NATIVE` or `FRAMEWORK` in application properties
2464. Your proxy is configured to overwrite (not append to) the `X-Forwarded-For` header
247 
248When `ForwardedHeaderFilter` is properly configured, `request.getRemoteAddr()` will automatically
249return the correct client IP from the forwarded headers. Without this configuration, use
250`request.getRemoteAddr()` directly—it returns the immediate connection IP, which is the only
251trustworthy value.
252 
253```java
254@Component
255public class RateLimitFilter extends OncePerRequestFilter {
256  private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();
257 
258  /*
259   * SECURITY: This filter uses request.getRemoteAddr() to identify clients for rate limiting.
260   *
261   * If your application is behind a reverse proxy (nginx, AWS ALB, etc.), you MUST configure
262   * Spring to handle forwarded headers properly for accurate client IP detection:
263   *
264   * 1. Set server.forward-headers-strategy=NATIVE (for cloud platforms) or FRAMEWORK in
265   *    application.properties/yaml
266   * 2. If using FRAMEWORK strategy, register ForwardedHeaderFilter:
267   *
268   *    @Bean
269   *    ForwardedHeaderFilter forwardedHeaderFilter() {
270   *        return new ForwardedHeaderFilter();
271   *    }
272   *
273   * 3. Ensure your proxy overwrites (not appends) the X-Forwarded-For header to prevent spoofing
274   * 4. Configure server.tomcat.remoteip.trusted-proxies or equivalent for your container
275   *
276   * Without this configuration, request.getRemoteAddr() returns the proxy IP, not the client IP.
277   * Do NOT read X-Forwarded-For directly—it is trivially spoofable without trusted proxy handling.
278   */
279  @Override
280  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
281      FilterChain filterChain) throws ServletException, IOException {
282    // Use getRemoteAddr() which returns the correct client IP when ForwardedHeaderFilter
283    // is configured, or the direct connection IP otherwise. Never trust X-Forwarded-For
284    // headers directly without proper proxy configuration.
285    String clientIp = request.getRemoteAddr();
286 
287    Bucket bucket = buckets.computeIfAbsent(clientIp,
288        k -> Bucket.builder()
289            .addLimit(Bandwidth.classic(100, Refill.greedy(100, Duration.ofMinutes(1))))
290            .build());
291 
292    if (bucket.tryConsume(1)) {
293      filterChain.doFilter(request, response);
294    } else {
295      response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
296    }
297  }
298}
299```
300 
301## Background Jobs
302 
303Use Spring’s `@Scheduled` or integrate with queues (e.g., Kafka, SQS, RabbitMQ). Keep handlers idempotent and observable.
304 
305## Observability
306 
307- Structured logging (JSON) via Logback encoder
308- Metrics: Micrometer + Prometheus/OTel
309- Tracing: Micrometer Tracing with OpenTelemetry or Brave backend
310 
311## Production Defaults
312 
313- Prefer constructor injection, avoid field injection
314- Enable `spring.mvc.problemdetails.enabled=true` for RFC 7807 errors (Spring Boot 3+)
315- Configure HikariCP pool sizes for workload, set timeouts
316- Use `@Transactional(readOnly = true)` for queries
317- Enforce null-safety via `@NonNull` and `Optional` where appropriate
318 
319**Remember**: Keep controllers thin, services focused, repositories simple, and errors handled centrally. Optimize for maintainability and testability.
320