AGENT SKILL

spring-boot-production-architecture

Production-grade Spring Boot 3.3+ architecture with Java 21, Project Loom virtual threads, layered architecture (Controller, Service, Repository, DTO), Spring Data JPA, connection pooling with HikariCP, transactional integrity, RFC 7807 ProblemDetails exception handling, and Micrometer observability. Trigger when building enterprise Java microservices or refactoring Spring Boot architectures.

License 许可
MIT
最近更新
2026-10-17
Stars
★ 8
Forks
1

01 前言 Front Matter

name
spring-boot-production-architecture
metadata
{ "category": "Backend Frameworks and Runtimes" }
description
Production-grade Spring Boot 3.3+ architecture with Java 21, Project Loom virtual threads, layered architecture (Controller, Service, Repository, DTO), Spring Data JPA, connection pooling with HikariCP, transactional integrity, RFC 7807 ProblemDetails exception handling, and Micrometer observability. Trigger when building enterprise Java microservices or refactoring Spring Boot architectures.
compatibility
Spring Boot 3.2+, Java 21 LTS, Gradle 8+ / Maven 3.9+

03 SKILL.md 正文

Spring Boot Production Architecture Skill Guide

This skill provides architectural patterns, production configurations, and idiomatic Java 21 code standards for building enterprise-grade, high-throughput microservices using Spring Boot 3.3+.


1. Architectural Layers & Virtual Thread Concurrency

Modern Spring Boot 3 applications leverage Java 21 Virtual Threads (Project Loom) to achieve non-blocking concurrency without reactive boilerplate.

+------------------------------------------------------------------------+
| Client Request (HTTP / REST)                                           |
+------------------------------------------------------------------------+
                               |
                               v (Virtual Thread per Request)
+------------------------------------------------------------------------+
| Web Layer: @RestController                                              |
| - Request validation (@Valid, JSR-380)                                 |
| - DTO Mapping (MapStruct)                                              |
| - HTTP Status & RFC 7807 ProblemDetails Responses                     |
+------------------------------------------------------------------------+
                               |
                               v
+------------------------------------------------------------------------+
| Domain / Service Layer: @Service                                       |
| - Business logic & Domain Invariants                                   |
| - Explicit Transaction Boundaries (@Transactional(readOnly = ...))    |
| - Event Publishing (ApplicationEventPublisher)                         |
+------------------------------------------------------------------------+
                               |
                               v
+------------------------------------------------------------------------+
| Persistence Layer: @Repository                                         |
| - Spring Data JPA Repositories (Derived & JPQL Queries)                |
| - HikariCP Optimized Connection Pool                                   |
| - Database Migration (Flyway / Liquibase)                              |
+------------------------------------------------------------------------+

2. Core Production Implementation

A. Application Configuration (application.yml)

server:
  port: 8080
  shutdown: graceful
  tomcat:
    threads:
      max: 200
  compression:
    enabled: true
    mime-types: application/json,text/html,text/plain

spring:
  threads:
    virtual:
      enabled: true # Enable Java 21 Virtual Threads for all Web & Async tasks
  datasource:
    url: jdbc:postgresql://${DB_HOST:localhost}:${DB_PORT:5432}/${DB_NAME:orders_db}
    username: ${DB_USER:postgres}
    password: ${DB_PASS:secret}
    hikari:
      pool-name: SpringBootHikariPool
      maximum-pool-size: 20
      minimum-idle: 10
      idle-timeout: 300000
      connection-timeout: 20000
      max-lifetime: 1200000
  jpa:
    open-in-view: false # CRITICAL: Disable OSIV to prevent connection leaks
    hibernate:
      ddl-auto: validate # Schema validation only; migrations handled by Flyway
    properties:
      hibernate:
        format_sql: false
        jdbc.batch_size: 50
        order_inserts: true
        order_updates: true

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      show-details: when-authorized
      probes:
        enabled: true

B. Clean Layered Domain Implementation

package com.example.orders.domain;

import jakarta.persistence.*;
import lombok.*;
import java.math.BigDecimal;
import java.time.Instant;
import java.util.UUID;

@Entity
@Table(name = "orders", indexes = {
    @Index(name = "idx_orders_customer_id", columnList = "customer_id"),
    @Index(name = "idx_orders_status", columnList = "status")
})
@Getter
@Setter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
@AllArgsConstructor
@Builder
public class Order {

    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    private UUID id;

    @Column(name = "customer_id", nullable = false)
    private UUID customerId;

    @Enumerated(EnumType.STRING)
    @Column(name = "status", nullable = false, length = 32)
    private OrderStatus status;

    @Column(name = "total_amount", nullable = false, precision = 12, scale = 2)
    private BigDecimal totalAmount;

    @Version
    private Long version; // Optimistic locking

    @Column(name = "created_at", nullable = false, updatable = false)
    private Instant createdAt;

    @PrePersist
    protected void onCreate() {
        this.createdAt = Instant.now();
        if (this.status == null) {
            this.status = OrderStatus.PENDING;
        }
    }
}

C. Service with Strict Transactional Boundaries

package com.example.orders.service;

import com.example.orders.domain.Order;
import com.example.orders.domain.OrderStatus;
import com.example.orders.dto.CreateOrderRequest;
import com.example.orders.dto.OrderResponse;
import com.example.orders.exception.ResourceNotFoundException;
import com.example.orders.repository.OrderRepository;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.util.UUID;

@Slf4j
@Service
@RequiredArgsConstructor
public class OrderService {

    private final OrderRepository orderRepository;

    @Transactional(readOnly = true)
    public OrderResponse getOrderById(UUID id) {
        return orderRepository.findById(id)
            .map(this::toResponse)
            .orElseThrow(() -> new ResourceNotFoundException("Order with ID " + id + " not found"));
    }

    @Transactional
    public OrderResponse createOrder(CreateOrderRequest request) {
        log.info("Creating new order for customer: {}", request.customerId());
        Order order = Order.builder()
            .customerId(request.customerId())
            .totalAmount(request.totalAmount())
            .status(OrderStatus.PENDING)
            .build();

        Order saved = orderRepository.save(order);
        return toResponse(saved);
    }

    private OrderResponse toResponse(Order order) {
        return new OrderResponse(
            order.getId(),
            order.getCustomerId(),
            order.getStatus(),
            order.getTotalAmount(),
            order.getCreatedAt()
        );
    }
}

D. Global RFC 7807 ProblemDetails Exception Handler

package com.example.orders.exception;

import org.springframework.http.*;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;

import java.net.URI;
import java.time.Instant;
import java.util.stream.Collectors;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ProblemDetail handleResourceNotFound(ResourceNotFoundException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        problem.setTitle("Resource Not Found");
        problem.setType(URI.create("https://api.example.com/errors/not-found"));
        problem.setProperty("timestamp", Instant.now());
        return problem;
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ProblemDetail handleValidationErrors(MethodArgumentNotValidException ex) {
        String detail = ex.getBindingResult().getFieldErrors().stream()
            .map(err -> err.getField() + ": " + err.getDefaultMessage())
            .collect(Collectors.joining(", "));

        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, detail);
        problem.setTitle("Validation Failure");
        problem.setType(URI.create("https://api.example.com/errors/validation"));
        problem.setProperty("timestamp", Instant.now());
        return problem;
    }
}

3. Production Best Practices & Quality Gates

  1. Virtual Threads Enabled: Ensure spring.threads.virtual.enabled: true is active for high-concurrency throughput without Netty reactive overhead.
  2. Disable OSIV: Always set spring.jpa.open-in-view: false to avoid holding database connections during template rendering or external serialization.
  3. Optimistic Locking: Include @Version private Long version; on mutable entities to prevent concurrent write loss.
  4. Read-Only Transactions: Enforce @Transactional(readOnly = true) on query methods to allow Hibernate to skip dirty checks and route to replica databases.

04 同仓库更多 Skills

hamzabellouch
hamzabellouch/agent-skills

security-audit

Comprehensive security guidance, source code audit, vulnerability assessment, and penetration test review for codebases, APIs, microservices, CLI tools, libraries, and LLM-backed applications. Triggers on requests to audit a codebase, conduct security reviews, find vulnerabilities or flaws, pen-test source code, or when the user asks in Arabic (فحص أمني، تدقيق الكود أمنياً، مراجعة الثغرات، فحص أمان المشروع). Supports Guidance mode (focused review) and Full Audit mode (deterministic 6-phase harness).

★ 8
hamzabellouch
hamzabellouch/agent-skills

malware-analysis-reversing

Production malware analysis workflows, reverse engineering methodologies, isolated sandbox triage, static/dynamic binary analysis, memory forensics, and YARA detection rule authoring.

★ 8
hamzabellouch
hamzabellouch/agent-skills

application-security-pentesting

Production Application Security (AppSec) standards, OWASP Top 10 vulnerability remediation, SAST/DAST pipeline integration, secure code review, threat modeling, and defensive security posture.

★ 8
hamzabellouch
hamzabellouch/agent-skills

oauth2-oidc-security-flows

Implement enterprise OAuth 2.1 and OpenID Connect (OIDC) authorization code flow with Proof Key for Code Exchange (PKCE), state and nonce verification, refresh token rotation, token revocation, and centralized IdP federation (Keycloak, Auth0, Okta). Trigger when building secure authentication, single sign-on (SSO), or third-party delegated authorization.

★ 8
hamzabellouch
hamzabellouch/agent-skills

jwt-session-management-hardening

Harden JWT-based authentication and session lifecycles using asymmetric signing (RS256/EdDSA), JWKS rotation, strict claims validation, Redis-backed sliding window sessions, revocation lists, and secure HttpOnly cookie storage. Trigger when implementing token validation, session revocation, or hardening API authentication.

★ 8
hamzabellouch
hamzabellouch/agent-skills

soc2-compliance-automation

Best practices for implementing SOC 2 Type II compliance controls, continuous evidence collection, infrastructure policy-as-code, and automated security monitoring. Use when automating Trust Services Criteria (Security, Availability, Confidentiality, Processing Integrity, Privacy), audit logging, IAM least privilege, or CI/CD security gates.

★ 8