Skip to main content
Agent skill

Springboot Patterns

Spring Boot architecture patterns, REST API design, layered services, data access, caching, async processing, and logging. Use for Java Spring Boot backend work. Use when building or reviewing a Spring Boot backend — REST layer, services, data access, caching, or async work.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Springboot Patterns when an AI agent needs a reusable SKILL.md workflow for this job: Spring Boot architecture patterns, REST API design, layered services, data access, caching, async processing, and logging. Use for Java Spring Boot backend work. Use when building or reviewing a Spring Boot backend — REST layer, services, data access, caching, or async work.

When not to use it

Skip Springboot Patterns when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/springboot-patterns
# Save SKILL.md to ~/.claude/skills/springboot-patterns/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/springboot-patterns/SKILL.md. For a shared project, commit the folder at .claude/skills/springboot-patterns/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Springboot Patterns skill for this task: Use Springboot Patterns when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Spring Boot Development Patterns

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

## When to Activate

- Building REST APIs with Spring MVC or WebFlux - Structuring controller → service → repository layers - Configuring Spring Data JPA, caching, or async processing - Adding validation, exception handling, or pagination - Setting up profiles for dev/staging/production environments - Implementing event-driven patterns with Spring Events or Kafka

## REST API Structure

```java @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)

```java 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

```java @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

```java 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

```java @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) { // Log unexpected errors with stack traces return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR) .body(ApiError.of("Internal server error")); } } ```

## Caching

Requires `@EnableCaching` on a configuration class.

```java @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) {} } ```

## Async Processing

Requires `@EnableAsync` on a configuration class.

```java @Service public class NotificationService { @Async public CompletableFuture<Void> sendAsync(Notification notification) { // send email/SMS return CompletableFuture.completedFuture(null); } } ```

## Logging (SLF4J)

```java @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 { // logic } catch (Exception ex) { log.error("generate_report_failed marketId={}", marketId, ex); throw ex; } return new Report(); } } ```

## Middleware / Filters

```java @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

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

## Error-Resilient External Calls

```java 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 Note**: The `X-Forwarded-For` header is untrusted by default because clients can spoof it. Only use forwarded headers when: 1. Your app is behind a trusted reverse proxy (nginx, AWS ALB, etc.) 2. You have registered `ForwardedHeaderFilter` as a bean 3. You have configured `server.forward-headers-strategy=NATIVE` or `FRAMEWORK` in application properties 4. Your proxy is configured to overwrite (not append to) the `X-Forwarded-For` header

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

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

/* * SECURITY: This filter uses request.getRemoteAddr() to identify clients for rate limiting. * * If your application is behind a reverse proxy (nginx, AWS ALB, etc.), you MUST configure * Spring to handle forwarded headers properly for accurate client IP detection: * * 1. Set server.forward-headers-strategy=NATIVE (for cloud platforms) or FRAMEWORK in * application.properties/yaml * 2. If using FRAMEWORK strategy, register ForwardedHeaderFilter: * * @Bean * ForwardedHeaderFilter forwardedHeaderFilter() { * return new ForwardedHeaderFilter(); * } * * 3. Ensure your proxy overwrites (not appends) the X-Forwarded-For header to prevent spoofing * 4. Configure server.tomcat.remoteip.trusted-proxies or equivalent for your container * * Without this configuration, request.getRemoteAddr() returns the proxy IP, not the client IP. * Do NOT read X-Forwarded-For directly—it is trivially spoofable without trusted proxy handling. */ @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { // Use getRemoteAddr() which returns the correct client IP when ForwardedHeaderFilter // is configured, or the direct connection IP otherwise. Never trust X-Forwarded-For // headers directly without proper proxy configuration. 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 with queues (e.g., 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 Defaults

- Prefer constructor injection, avoid field injection - Enable `spring.mvc.problemdetails.enabled=true` for RFC 7807 errors (Spring Boot 3+) - Configure HikariCP pool sizes for workload, set timeouts - Use `@Transactional(readOnly = true)` for queries - Enforce null-safety via `@NonNull` and `Optional` where appropriate

**Remember**: Keep controllers thin, services focused, repositories simple, and errors handled centrally. Optimize for maintainability and testability.

Intended uses

  • Use Springboot Patterns when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.