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
- Virtual Threads Enabled: Ensure
spring.threads.virtual.enabled: trueis active for high-concurrency throughput without Netty reactive overhead. - Disable OSIV: Always set
spring.jpa.open-in-view: falseto avoid holding database connections during template rendering or external serialization. - Optimistic Locking: Include
@Version private Long version;on mutable entities to prevent concurrent write loss. - Read-Only Transactions: Enforce
@Transactional(readOnly = true)on query methods to allow Hibernate to skip dirty checks and route to replica databases.
04 同仓库更多 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).
malware-analysis-reversing
Production malware analysis workflows, reverse engineering methodologies, isolated sandbox triage, static/dynamic binary analysis, memory forensics, and YARA detection rule authoring.
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.
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.
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.
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.