Spring Boot architecture patterns, REST API design, hexagonal (ports & adapters) architecture, data access, caching, async processing, and logging. Use for Java Spring Boot backend work.
From clarcnpx claudepluginhub marvinrichter/clarc --plugin clarcThis skill uses the workspace's default tool permissions.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Spring Boot architecture and API patterns for scalable, production-grade services.
@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));
}
}
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);
}
Use cases implement input ports and depend on output ports — no JPA or Spring framework imports in domain:
// domain/port/in/CreateMarketUseCase.java
public interface CreateMarketUseCase {
Market create(CreateMarketCommand command);
}
// domain/port/out/MarketRepository.java
public interface MarketRepository {
Market save(Market market);
Optional<Market> findBySlug(String slug);
}
// application/usecase/CreateMarketService.java — implements input port, uses output port
@Transactional
public class CreateMarketService implements CreateMarketUseCase {
private final MarketRepository marketRepository; // output port interface
public CreateMarketService(MarketRepository marketRepository) {
this.marketRepository = marketRepository;
}
@Override
public Market create(CreateMarketCommand command) {
var market = Market.create(command.name(), command.slug());
return marketRepository.save(market);
}
}
// adapter/out/persistence/JpaMarketRepository.java — implements output port
@Repository
class JpaMarketRepository implements MarketRepository {
private final MarketJpaRepository jpaRepo;
JpaMarketRepository(MarketJpaRepository jpaRepo) {
this.jpaRepo = jpaRepo;
}
@Override
public Market save(Market market) {
return MarketMapper.toDomain(jpaRepo.save(MarketMapper.toEntity(market)));
}
@Override
public Optional<Market> findBySlug(String slug) {
return jpaRepo.findBySlug(slug).map(MarketMapper::toDomain);
}
}
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());
}
}
Spring Boot 4 has native RFC 7807 support via ProblemDetail. Enable it in application.yml:
spring:
mvc:
problemdetails:
enabled: true # auto-maps built-in exceptions to ProblemDetail
This automatically handles MethodArgumentNotValidException, NoResourceFoundException, etc.
For domain exceptions, add a @RestControllerAdvice:
@RestControllerAdvice
class ProblemDetailsAdvice {
@ExceptionHandler(MarketNotFoundException.class)
ProblemDetail handleNotFound(MarketNotFoundException ex, HttpServletRequest req) {
ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
pd.setType(URI.create("https://api.example.com/problems/not-found"));
pd.setTitle("Not Found");
pd.setProperty("instance", req.getRequestURI());
return pd; // Spring sets Content-Type: application/problem+json automatically
}
@ExceptionHandler(ConstraintViolationException.class)
ProblemDetail handleValidation(ConstraintViolationException ex, HttpServletRequest req) {
ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.UNPROCESSABLE_ENTITY);
pd.setType(URI.create("https://api.example.com/problems/validation-failed"));
pd.setTitle("Validation Failed");
pd.setDetail("One or more fields failed validation.");
pd.setProperty("instance", req.getRequestURI());
pd.setProperty("errors", ex.getConstraintViolations().stream()
.map(v -> Map.of("field", v.getPropertyPath().toString(), "detail", v.getMessage()))
.toList());
return pd;
}
@ExceptionHandler(AccessDeniedException.class)
ProblemDetail handleAccessDenied(HttpServletRequest req) {
ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.FORBIDDEN);
pd.setType(URI.create("https://api.example.com/problems/forbidden"));
pd.setTitle("Forbidden");
pd.setProperty("instance", req.getRequestURI());
return pd;
}
@ExceptionHandler(Exception.class)
ProblemDetail handleGeneric(Exception ex, HttpServletRequest req) {
log.error("unhandled exception uri={}", req.getRequestURI(), ex);
ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.INTERNAL_SERVER_ERROR);
pd.setType(URI.create("about:blank"));
pd.setTitle("Internal Server Error");
return pd;
}
}
Response example:
HTTP/1.1 404 Not Found
Content-Type: application/problem+json
{
"type": "https://api.example.com/problems/not-found",
"title": "Not Found",
"status": 404,
"detail": "Market 'crypto-btc' not found.",
"instance": "/api/markets/crypto-btc"
}
See skill: problem-details for the full RFC 7807/9457 reference and multi-language examples.
Requires @EnableCaching on a configuration class.
@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) {}
}
Requires @EnableAsync on a configuration class.
@Service
public class NotificationService {
@Async
public CompletableFuture<Void> sendAsync(Notification notification) {
// send email/SMS
return CompletableFuture.completedFuture(null);
}
}
@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();
}
}
@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);
}
}
}
PageRequest page = PageRequest.of(pageNumber, pageSize, Sort.by("createdAt").descending());
Page<Market> results = marketService.list(page);
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;
}
}
}
}
Security Note: The X-Forwarded-For header is untrusted by default because clients can spoof it.
Only use forwarded headers when:
ForwardedHeaderFilter as a beanserver.forward-headers-strategy=NATIVE or FRAMEWORK in application propertiesX-Forwarded-For headerWhen 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.
@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());
}
}
}
Use Spring’s @Scheduled or integrate with queues (e.g., Kafka, SQS, RabbitMQ). Keep handlers idempotent and observable.
spring.mvc.problemdetails.enabled=true for RFC 7807 errors (Spring Boot 4+)spring:
threads:
virtual:
enabled: true # Tomcat + @Async + @Scheduled all use virtual threads
@Transactional(readOnly = true) for queries@NonNull and Optional where appropriateRemember: Keep domain framework-free, use cases focused on business logic, adapters thin (map only), and errors handled centrally. Dependency arrows always point inward — toward domain. Optimize for testability and replaceability of adapters.