springboot-patterns

Spring Boot development patterns

Spring Boot architecture and API patterns for scalable, production-grade services.

When to enable

• Build REST APIs using Spring MVC or WebFlux
• Organize Controller → Service → Repository layers
• Configure Spring Data JPA, caching, or asynchronous processing
• Add validation, exception handling, or pagination
• Set up profiles for development/test/production environments
• Implement event-driven patterns using Spring Events or Kafka

REST API structure

@RestController
@RequestMapping("/api/markets")
@Validated
class MarketController {
  private final MarketService marketService;

  MarketController(MarketService marketService) {
    this.marketService = marketService;
  }

  @GetMapping
  ResponseEntity<Page<MarketResponse>> list(
      @RequestParam(defaultValue = "0") int page,
      @RequestParam(defaultValue = "20") int size) {
    Page<Market> markets = marketService.list(PageRequest.of(page, size));
    return ResponseEntity.ok(markets.map(MarketResponse::from));
  }

  @PostMapping
  ResponseEntity<MarketResponse> create(@Valid @RequestBody CreateMarketRequest request) {
    Market market = marketService.create(request);
    return ResponseEntity.status(HttpStatus.CREATED).body(MarketResponse.from(market));
  }
}

Repository pattern (Spring Data JPA)

public interface MarketRepository extends JpaRepository<MarketEntity, Long> {
  @Query("select m from MarketEntity m where m.status = :status order by m.volume desc")
  List<MarketEntity> findActive(@Param("status") MarketStatus status, Pageable pageable);
}

Service layer with transactions

@Service
public class MarketService {
  private final MarketRepository repo;

  public MarketService(MarketRepository repo) {
    this.repo = repo;
  }

  @Transactional
  public Market create(CreateMarketRequest request) {
    MarketEntity entity = MarketEntity.from(request);
    MarketEntity saved = repo.save(entity);
    return Market.from(saved);
  }
}

DTOs and validation

public record CreateMarketRequest(
    @NotBlank @Size(max = 200) String name,
    @NotBlank @Size(max = 2000) String description,
    @NotNull @FutureOrPresent Instant endDate,
    @NotEmpty List<@NotBlank String> categories) {}

public record MarketResponse(Long id, String name, MarketStatus status) {
  static MarketResponse from(Market market) {
    return new MarketResponse(market.id(), market.name(), market.status());
  }
}

Exception handling

@ControllerAdvice
class GlobalExceptionHandler {
  @ExceptionHandler(MethodArgumentNotValidException.class)
  ResponseEntity<ApiError> handleValidation(MethodArgumentNotValidException ex) {
    String message = ex.getBindingResult().getFieldErrors().stream()
        .map(e -> e.getField() + ": " + e.getDefaultMessage())
        .collect(Collectors.joining(", "));
    return ResponseEntity.badRequest().body(ApiError.validation(message));
  }

  @ExceptionHandler(AccessDeniedException.class)
  ResponseEntity<ApiError> handleAccessDenied() {
    return ResponseEntity.status(HttpStatus.FORBIDDEN).body(ApiError.of("Forbidden"));
  }

  @ExceptionHandler(Exception.class)
  ResponseEntity<ApiError> handleGeneric(Exception ex) {
    // 记录带有堆栈跟踪的非预期错误
    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
        .body(ApiError.of("Internal server error"));
  }
}

Caching

Need to add on the configuration class @EnableCaching。

@Service
public class MarketCacheService {
  private final MarketRepository repo;

  public MarketCacheService(MarketRepository repo) {
    this.repo = repo;
  }

  @Cacheable(value = "market", key = "#id")
  public Market getById(Long id) {
    return repo.findById(id)
        .map(Market::from)
        .orElseThrow(() -> new EntityNotFoundException("Market not found"));
  }

  @CacheEvict(value = "market", key = "#id")
  public void evict(Long id) {}
}

Asynchronous processing

Need to add on the configuration class @EnableAsync。

@Service
public class NotificationService {
  @Async
  public CompletableFuture<Void> sendAsync(Notification notification) {
    // 发送电子邮件/短信
    return CompletableFuture.completedFuture(null);
  }
}

Logging (SLF4J)

@Service
public class ReportService {
  private static final Logger log = LoggerFactory.getLogger(ReportService.class);

  public Report generate(Long marketId) {
    log.info("generate_report marketId={}", marketId);
    try {
      // 逻辑
    } catch (Exception ex) {
      log.error("generate_report_failed marketId={}", marketId, ex);
      throw ex;
    }
    return new Report();
  }
}

Middleware / Filters

@Component
public class RequestLoggingFilter extends OncePerRequestFilter {
  private static final Logger log = LoggerFactory.getLogger(RequestLoggingFilter.class);

  @Override
  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
      FilterChain filterChain) throws ServletException, IOException {
    long start = System.currentTimeMillis();
    try {
      filterChain.doFilter(request, response);
    } finally {
      long duration = System.currentTimeMillis() - start;
      log.info("req method={} uri={} status={} durationMs={}",
          request.getMethod(), request.getRequestURI(), response.getStatus(), duration);
    }
  }
}

Pagination and sorting

PageRequest page = PageRequest.of(pageNumber, pageSize, Sort.by("createdAt").descending());
Page<Market> results = marketService.list(page);

Fault-tolerant external calls

public <T> T withRetry(Supplier<T> supplier, int maxRetries) {
  int attempts = 0;
  while (true) {
    try {
      return supplier.get();
    } catch (Exception ex) {
      attempts++;
      if (attempts >= maxRetries) {
        throw ex;
      }
      try {
        Thread.sleep((long) Math.pow(2, attempts) * 100L);
      } catch (InterruptedException ie) {
        Thread.currentThread().interrupt();
        throw ex;
      }
    }
  }
}

Rate limiting (Filter + Bucket4j)

Security tips: By default, X-Forwarded-For request headers are untrustworthy because clients can forge them. Use forwarded headers only in the following cases:

1. The application is behind a trusted reverse proxy (nginx, AWS ALB, etc.)
2. Have registered ForwardedHeaderFilter as a Bean
3. Have configured in the application properties server.forward-headers-strategy=NATIVE or FRAMEWORK
4. The proxy is configured to overwrite (rather than append)X-Forwarded-For request headers

When ForwardedHeaderFilter is configured correctly,request.getRemoteAddr() will automatically return the correct client IP from forwarded headers. Without this configuration, use request.getRemoteAddr()directly—it returns the IP of the direct connection, which is the only trustworthy value.

@Component
public class RateLimitFilter extends OncePerRequestFilter {
  private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();

  /*
   * 安全：此过滤器使用 request.getRemoteAddr() 来识别客户端以进行速率限制。
   *
   * 如果应用位于反向代理（nginx、AWS ALB 等）之后，必须配置 Spring 正确处理转发头，
   * 以进行准确的客户端 IP 检测：
   *
   * 1. 在 application.properties/yaml 中设置 server.forward-headers-strategy=NATIVE（用于云平台）
   *    或 FRAMEWORK
   * 2. 如果使用 FRAMEWORK 策略，请注册 ForwardedHeaderFilter：
   *
   *    @Bean
   *    ForwardedHeaderFilter forwardedHeaderFilter() {
   *        return new ForwardedHeaderFilter();
   *    }
   *
   * 3. 确保代理覆盖（而不是追加）X-Forwarded-For 请求头，以防止伪造
   * 4. 为容器配置 server.tomcat.remoteip.trusted-proxies 或等效配置
   *
   * 如果没有此配置，request.getRemoteAddr() 将返回代理 IP，而不是客户端 IP。
   * 不要直接读取 X-Forwarded-For——在没有受信任代理处理的情况下，它是极易伪造的。
   */
  @Override
  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
      FilterChain filterChain) throws ServletException, IOException {
    // 使用 getRemoteAddr()，在配置了 ForwardedHeaderFilter 时它返回正确的客户端 IP，
    // 否则返回直接连接 IP。在没有正确代理配置的情况下，切勿直接信任 X-Forwarded-For 请求头。
    String clientIp = request.getRemoteAddr();

    Bucket bucket = buckets.computeIfAbsent(clientIp,
        k -> Bucket.builder()
            .addLimit(Bandwidth.classic(100, Refill.greedy(100, Duration.ofMinutes(1))))
            .build());

    if (bucket.tryConsume(1)) {
      filterChain.doFilter(request, response);
    } else {
      response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
    }
  }
}

Background jobs

Use Spring's @Scheduled or integrate a queue (such as Kafka, SQS, RabbitMQ). Keep handlers idempotent and observable.

Observability

• Structured logging (JSON) via Logback encoder
• Metrics: Micrometer + Prometheus/OTel
• Tracing: Micrometer Tracing with OpenTelemetry or Brave backend

Production environment defaults

• Prefer constructor injection, avoid field injection
• Enable for RFC 7807 errors spring.mvc.problemdetails.enabled=true（Spring Boot 3+）
• Configure HikariCP connection pool size based on workload, set timeouts
• Use for queries @Transactional(readOnly = true)
• Where appropriate, use @NonNull and Optional to enforce null safety

Keep in mind: Keep Controllers lean, Services focused, Repositories simple, and handle errors centrally. Optimize for maintainability and testability.