backend-patterns
Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.
- License 许可
- MIT
- 最近更新
- 2026-09-14
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- backend-patterns
- metadata
- { "origin": "AgentPowerHouse - APH" }
- description
- Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.
03 SKILL.md 正文
Backend Development Patterns
Architecture patterns and best practices for scalable Spring Boot applications consumed by React frontends.
When to Activate
- Designing REST API endpoints in Spring Boot
- Implementing repository, service, or controller layers
- Optimizing database queries (N+1, indexing, connection pooling)
- Adding caching (Redis, Spring Cache, HTTP cache headers)
- Setting up background jobs or async processing
- Structuring error handling and validation for APIs
- Building middleware (auth, logging, rate limiting)
API Design Patterns
RESTful API Structure
// Resource-based URLs with Spring MVC
@RestController
@RequestMapping("/api/v1/markets")
public class MarketController {
@GetMapping // GET /api/v1/markets
@GetMapping("/{id}") // GET /api/v1/markets/{id}
@PostMapping // POST /api/v1/markets
@PutMapping("/{id}") // PUT /api/v1/markets/{id}
@PatchMapping("/{id}") // PATCH /api/v1/markets/{id}
@DeleteMapping("/{id}") // DELETE /api/v1/markets/{id}
}
// Query parameters for filtering, sorting, pagination
// GET /api/v1/markets?status=active&sort=volume,desc&size=20&page=0
Repository Pattern
Spring Data JPA generates the implementation; you define the interface.
// Domain model
@Entity
@Table(name = "markets")
public class Market {
@Id @GeneratedValue(strategy = GenerationType.UUID)
private UUID id;
private String name;
private String status;
private BigDecimal volume;
private LocalDateTime createdAt;
// getters, setters, or use Lombok @Data
}
// Repository interface — Spring Data provides the implementation
public interface MarketRepository extends JpaRepository<Market, UUID>,
JpaSpecificationExecutor<Market> {
List<Market> findByStatus(String status);
@Query("SELECT m FROM Market m WHERE m.status = :status ORDER BY m.volume DESC")
Page<Market> findActiveByVolume(@Param("status") String status, Pageable pageable);
// Projection query — only the columns you need
@Query("SELECT m.id AS id, m.name AS name, m.status AS status, m.volume AS volume " +
"FROM Market m WHERE m.status = :status")
Page<MarketSummary> findSummariesByStatus(@Param("status") String status, Pageable pageable);
}
// Projection interface (no extra class needed)
public interface MarketSummary {
UUID getId();
String getName();
String getStatus();
BigDecimal getVolume();
}
Service Layer Pattern
// Business logic separated from data access
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true) // default: read-only; override per method
public class MarketService {
private final MarketRepository marketRepo;
private final EmbeddingService embeddingService;
public Page<MarketDto> listMarkets(MarketFilters filters, Pageable pageable) {
Specification<Market> spec = Specification
.where(MarketSpec.hasStatus(filters.status()))
.and(MarketSpec.volumeAtLeast(filters.minVolume()));
return marketRepo.findAll(spec, pageable).map(MarketDto::from);
}
public List<MarketDto> searchMarkets(String query, int limit) {
float[] embedding = embeddingService.embed(query);
// Vector search returns IDs + scores
List<VectorResult> results = embeddingService.search(embedding, limit);
List<UUID> ids = results.stream().map(VectorResult::id).toList();
// Batch fetch by IDs (1 query)
Map<UUID, Market> marketMap = marketRepo.findAllById(ids)
.stream()
.collect(Collectors.toMap(Market::getId, Function.identity()));
// Reassemble in score order
return results.stream()
.map(r -> marketMap.get(r.id()))
.filter(Objects::nonNull)
.map(MarketDto::from)
.toList();
}
@Transactional // write operation — overrides class-level readOnly
public MarketDto create(CreateMarketRequest request) {
if (marketRepo.existsByName(request.name())) {
throw new DuplicateResourceException("Market name already exists: " + request.name());
}
Market market = new Market(request.name(), request.status());
return MarketDto.from(marketRepo.save(market));
}
}
Middleware: Filters and Interceptors
Spring has two hook points: Filter (servlet level) and HandlerInterceptor (MVC level).
// Filter — runs for every request, including static resources
@Component
@Order(1)
public class RequestIdFilter extends OncePerRequestFilter {
@Override
protected void doFilterInternal(HttpServletRequest req,
HttpServletResponse res, FilterChain chain)
throws ServletException, IOException {
String requestId = Optional.ofNullable(req.getHeader("X-Request-Id"))
.orElse(UUID.randomUUID().toString());
MDC.put("requestId", requestId); // attach to log context
res.addHeader("X-Request-Id", requestId);
try {
chain.doFilter(req, res);
} finally {
MDC.clear();
}
}
}
// HandlerInterceptor — runs only for controller routes
@Component
@RequiredArgsConstructor
public class AuthInterceptor implements HandlerInterceptor {
private final JwtService jwtService;
@Override
public boolean preHandle(HttpServletRequest req,
HttpServletResponse res, Object handler) {
if (handler instanceof HandlerMethod hm &&
hm.hasMethodAnnotation(PublicEndpoint.class)) {
return true; // skip auth for @PublicEndpoint methods
}
String token = Optional.ofNullable(req.getHeader("Authorization"))
.map(h -> h.replace("Bearer ", ""))
.orElse(null);
if (token == null) {
res.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
return false;
}
try {
UserPrincipal principal = jwtService.verify(token);
req.setAttribute("principal", principal);
return true;
} catch (JwtException e) {
res.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
return false;
}
}
}
// Register the interceptor
@Configuration
@RequiredArgsConstructor
public class WebConfig implements WebMvcConfigurer {
private final AuthInterceptor authInterceptor;
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(authInterceptor)
.addPathPatterns("/api/**")
.excludePathPatterns("/api/v1/auth/**");
}
}
Database Patterns
Query Optimization — Projections over select *
// BAD: fetches every column and maps to full entity
List<Market> all = marketRepository.findAll();
// GOOD: projection — only id, name, status, volume reach the JDBC layer
Page<MarketSummary> summaries = marketRepository
.findSummariesByStatus("active", pageable);
// GOOD: native query with explicit column list when JPQL isn't enough
@Query(value = "SELECT id, name, status, volume FROM markets WHERE status = :status",
nativeQuery = true)
List<MarketProjection> findActiveNative(@Param("status") String status);
N+1 Query Prevention
// BAD: N+1 — one query for markets, then one per market for creator
List<Market> markets = marketRepository.findAll();
markets.forEach(m -> m.getCreator().getName()); // triggers N lazy loads
// GOOD option 1: JPQL JOIN FETCH
@Query("SELECT m FROM Market m JOIN FETCH m.creator WHERE m.status = :status")
List<Market> findWithCreator(@Param("status") String status);
// GOOD option 2: @EntityGraph (no query string needed)
@EntityGraph(attributePaths = {"creator", "category"})
List<Market> findByStatus(String status);
// GOOD option 3: batch-fetch by IDs (when joining would cause cartesian products)
List<UUID> ids = marketRepository.findIdsByStatus("active");
Map<UUID, User> creatorMap = userRepository.findAllById(creatorIds)
.stream()
.collect(Collectors.toMap(User::getId, Function.identity()));
Hibernate tip: enable
spring.jpa.properties.hibernate.format_sql=trueandlogging.level.org.hibernate.SQL=DEBUGin development to catch N+1 issues early. Use Hypersistence Optimizer or Datasource Proxy in CI.
Transaction Pattern
// Simple service-level transaction
@Service
public class MarketService {
@Transactional
public MarketWithPosition createMarketWithPosition(
CreateMarketRequest marketReq,
CreatePositionRequest positionReq) {
Market market = marketRepository.save(new Market(marketReq));
Position position = positionRepository.save(new Position(market, positionReq));
// If either save throws, the whole transaction rolls back automatically
return new MarketWithPosition(market, position);
}
}
// Explicit rollback rules
@Transactional(rollbackOn = Exception.class,
noRollbackOn = OptimisticLockException.class)
public void processMarket(UUID id) { /* ... */ }
// Programmatic transaction (when declarative isn't granular enough)
@Service
@RequiredArgsConstructor
public class BulkService {
private final TransactionTemplate txTemplate;
public void bulkCreate(List<CreateMarketRequest> requests) {
requests.forEach(req ->
txTemplate.executeWithoutResult(status -> {
try {
marketRepository.save(new Market(req));
} catch (DataIntegrityViolationException e) {
status.setRollbackOnly();
log.warn("Skipped duplicate market: {}", req.name());
}
})
);
}
}
Connection Pool Configuration
# application.yml — HikariCP (Spring Boot default)
spring:
datasource:
url: jdbc:postgresql://localhost:5432/mydb
username: ${DB_USERNAME}
password: ${DB_PASSWORD}
hikari:
maximum-pool-size: 20 # tune to (core_count * 2) + effective_spindle_count
minimum-idle: 5
connection-timeout: 30000 # ms — fail fast rather than queue indefinitely
idle-timeout: 600000
max-lifetime: 1800000
leak-detection-threshold: 60000
Caching Strategies
Spring Cache Abstraction (Redis-backed)
// Enable caching
@SpringBootApplication
@EnableCaching
public class Application { /* ... */ }
# application.yml
spring:
cache:
type: redis
data:
redis:
host: ${REDIS_HOST:localhost}
port: 6379
timeout: 2000ms
// Configure TTLs per cache
@Configuration
public class CacheConfig {
@Bean
public RedisCacheManagerBuilderCustomizer redisCacheCustomizer() {
return builder -> builder
.withCacheConfiguration("markets",
RedisCacheConfiguration.defaultCacheConfig()
.entryTtl(Duration.ofMinutes(5))
.disableCachingNullValues())
.withCacheConfiguration("market-summaries",
RedisCacheConfiguration.defaultCacheConfig()
.entryTtl(Duration.ofMinutes(10)));
}
}
// Apply caching at the service layer — not the controller or repository
@Service
public class MarketService {
@Cacheable(value = "markets", key = "#id")
public MarketDto findById(UUID id) {
return marketRepository.findById(id)
.map(MarketDto::from)
.orElseThrow(() -> new ResourceNotFoundException("Market not found: " + id));
}
@CacheEvict(value = "markets", key = "#id")
@Transactional
public MarketDto update(UUID id, UpdateMarketRequest request) {
Market market = marketRepository.findById(id)
.orElseThrow(() -> new ResourceNotFoundException("Market not found: " + id));
market.apply(request);
return MarketDto.from(marketRepository.save(market));
}
@CacheEvict(value = "markets", allEntries = true)
@Transactional
public void delete(UUID id) {
marketRepository.deleteById(id);
}
}
Cache-Aside Pattern (Manual / Redis Template)
@Service
@RequiredArgsConstructor
public class MarketCacheService {
private final MarketRepository marketRepository;
private final RedisTemplate<String, MarketDto> redisTemplate;
private static final Duration TTL = Duration.ofMinutes(5);
public MarketDto getMarket(UUID id) {
String key = "market:" + id;
// 1. Try cache
MarketDto cached = redisTemplate.opsForValue().get(key);
if (cached != null) return cached;
// 2. Cache miss — hit the database
MarketDto dto = marketRepository.findById(id)
.map(MarketDto::from)
.orElseThrow(() -> new ResourceNotFoundException("Market not found: " + id));
// 3. Populate cache
redisTemplate.opsForValue().set(key, dto, TTL);
return dto;
}
public void invalidate(UUID id) {
redisTemplate.delete("market:" + id);
}
}
Error Handling Patterns
Custom Exception Hierarchy
// Base exception — marks it as a known, operational error
public abstract class ApiException extends RuntimeException {
private final HttpStatus status;
private final String code;
protected ApiException(HttpStatus status, String code, String message) {
super(message);
this.status = status;
this.code = code;
}
public HttpStatus getStatus() { return status; }
public String getCode() { return code; }
}
public class ResourceNotFoundException extends ApiException {
public ResourceNotFoundException(String message) {
super(HttpStatus.NOT_FOUND, "not_found", message);
}
}
public class DuplicateResourceException extends ApiException {
public DuplicateResourceException(String message) {
super(HttpStatus.CONFLICT, "conflict", message);
}
}
public class ForbiddenException extends ApiException {
public ForbiddenException(String message) {
super(HttpStatus.FORBIDDEN, "forbidden", message);
}
}
Centralized Error Handler
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {
// Bean Validation failures (@Valid)
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ErrorResponse> handleValidation(
MethodArgumentNotValidException ex) {
List<FieldError> details = ex.getBindingResult().getFieldErrors().stream()
.map(e -> new FieldError(e.getField(), e.getDefaultMessage(), "invalid_value"))
.toList();
return ResponseEntity.unprocessableEntity()
.body(ErrorResponse.of("validation_error", "Request validation failed", details));
}
// Constraint violations (e.g., @Validated on service methods)
@ExceptionHandler(ConstraintViolationException.class)
public ResponseEntity<ErrorResponse> handleConstraintViolation(
ConstraintViolationException ex) {
List<FieldError> details = ex.getConstraintViolations().stream()
.map(v -> new FieldError(
v.getPropertyPath().toString(),
v.getMessage(),
"constraint_violation"))
.toList();
return ResponseEntity.unprocessableEntity()
.body(ErrorResponse.of("validation_error", "Constraint violation", details));
}
// All operational exceptions
@ExceptionHandler(ApiException.class)
public ResponseEntity<ErrorResponse> handleApiException(ApiException ex) {
return ResponseEntity.status(ex.getStatus())
.body(ErrorResponse.of(ex.getCode(), ex.getMessage()));
}
// Malformed JSON / type mismatch
@ExceptionHandler(HttpMessageNotReadableException.class)
public ResponseEntity<ErrorResponse> handleBadJson(
HttpMessageNotReadableException ex) {
return ResponseEntity.badRequest()
.body(ErrorResponse.of("invalid_json", "Malformed request body"));
}
// Optimistic lock conflicts
@ExceptionHandler(OptimisticLockingFailureException.class)
public ResponseEntity<ErrorResponse> handleOptimisticLock(
OptimisticLockingFailureException ex) {
return ResponseEntity.status(HttpStatus.CONFLICT)
.body(ErrorResponse.of("conflict", "Resource was modified by another request. Retry."));
}
// Catch-all — never expose internal details
@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleUnexpected(Exception ex) {
log.error("Unexpected error", ex);
return ResponseEntity.internalServerError()
.body(ErrorResponse.of("internal_error", "An unexpected error occurred"));
}
}
Retry with Exponential Backoff — Spring Retry
// Add spring-retry + spring-aspects to pom.xml, enable on the app class
@SpringBootApplication
@EnableRetry
public class Application { /* ... */ }
// Annotate the operation to retry
@Service
public class EmbeddingService {
@Retryable(
retryFor = { HttpServerErrorException.class, ResourceAccessException.class },
maxAttempts = 3,
backoff = @Backoff(delay = 1000, multiplier = 2) // 1s, 2s, 4s
)
public float[] embed(String text) {
return callExternalEmbeddingApi(text);
}
@Recover
public float[] embedFallback(Exception ex, String text) {
log.error("Embedding failed after retries for text: {}", text, ex);
throw new ServiceUnavailableException("Embedding service unavailable");
}
}
// Programmatic retry (when annotation isn't flexible enough)
@Bean
public RetryTemplate retryTemplate() {
return RetryTemplate.builder()
.maxAttempts(3)
.exponentialBackoff(1000, 2, 8000)
.retryOn(HttpServerErrorException.class)
.build();
}
// Usage
retryTemplate.execute(ctx -> embeddingClient.embed(text));
Authentication & Authorization
JWT with Spring Security
// JWT service
@Service
public class JwtService {
@Value("${app.jwt.secret}")
private String secret;
@Value("${app.jwt.expiration-ms:3600000}")
private long expirationMs;
public String generate(UserPrincipal principal) {
return Jwts.builder()
.subject(principal.id().toString())
.claim("email", principal.email())
.claim("role", principal.role().name())
.issuedAt(new Date())
.expiration(new Date(System.currentTimeMillis() + expirationMs))
.signWith(getKey())
.compact();
}
public UserPrincipal verify(String token) {
Claims claims = Jwts.parser()
.verifyWith(getKey())
.build()
.parseSignedClaims(token)
.getPayload();
return new UserPrincipal(
UUID.fromString(claims.getSubject()),
claims.get("email", String.class),
Role.valueOf(claims.get("role", String.class))
);
}
private SecretKey getKey() {
return Keys.hmacShaKeyFor(Decoders.BASE64.decode(secret));
}
}
// JWT filter
@Component
@RequiredArgsConstructor
public class JwtAuthFilter extends OncePerRequestFilter {
private final JwtService jwtService;
private final UserDetailsService userDetailsService;
@Override
protected void doFilterInternal(HttpServletRequest req,
HttpServletResponse res, FilterChain chain)
throws ServletException, IOException {
String authHeader = req.getHeader("Authorization");
if (authHeader == null || !authHeader.startsWith("Bearer ")) {
chain.doFilter(req, res);
return;
}
try {
String token = authHeader.substring(7);
UserPrincipal principal = jwtService.verify(token);
UsernamePasswordAuthenticationToken auth =
new UsernamePasswordAuthenticationToken(
principal, null,
List.of(new SimpleGrantedAuthority("ROLE_" + principal.role().name())));
SecurityContextHolder.getContext().setAuthentication(auth);
} catch (JwtException e) {
res.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
res.getWriter().write("{\"error\":{\"code\":\"invalid_token\",\"message\":\"Invalid or expired token\"}}");
return;
}
chain.doFilter(req, res);
}
}
Role-Based Access Control
// Enum-based roles
public enum Role { ADMIN, MODERATOR, USER }
// Method security — enable once in a @Configuration
@Configuration
@EnableMethodSecurity
public class SecurityConfig { /* ... */ }
// Controller annotations
@RestController
@RequestMapping("/api/v1/markets")
public class MarketController {
@GetMapping // any authenticated user
public Page<MarketDto> list(Pageable pageable) { /* ... */ }
@PostMapping // any authenticated user
public ResponseEntity<MarketDto> create(@Valid @RequestBody CreateMarketRequest req) { /* ... */ }
@DeleteMapping("/{id}")
@PreAuthorize("hasRole('ADMIN')") // admin only
public ResponseEntity<Void> delete(@PathVariable UUID id) { /* ... */ }
@PatchMapping("/{id}/resolve")
@PreAuthorize("hasAnyRole('ADMIN', 'MODERATOR')")
public ResponseEntity<MarketDto> resolve(@PathVariable UUID id) { /* ... */ }
}
// Ownership check in service layer (finer-grained than annotations)
@Service
public class MarketService {
@Transactional
public void delete(UUID marketId, UserPrincipal principal) {
Market market = marketRepository.findById(marketId)
.orElseThrow(() -> new ResourceNotFoundException("Market not found: " + marketId));
boolean isOwner = market.getCreatorId().equals(principal.id());
boolean isAdmin = principal.role() == Role.ADMIN;
if (!isOwner && !isAdmin) {
throw new ForbiddenException("You do not have permission to delete this market");
}
marketRepository.delete(market);
}
}
Rate Limiting
Rate limiting must use a shared store such as Redis, a gateway, or the platform's native limiter. Do not use per-process in-memory counters for production: they reset on deploy, split across replicas, and fail open in multi-instance or serverless environments.
// Bucket4j with Redis (see api-design doc for full implementation)
@Component
@RequiredArgsConstructor
public class RateLimitFilter extends OncePerRequestFilter {
private final BucketRepository bucketRepository; // Redis-backed
private static final Map<String, BandwidthDefinition> TIERS = Map.of(
"anonymous", Bandwidth.classic(30, Refill.intervally(30, Duration.ofMinutes(1))),
"authenticated", Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1))),
"premium", Bandwidth.classic(1000,Refill.intervally(1000,Duration.ofMinutes(1)))
);
@Override
protected void doFilterInternal(HttpServletRequest req,
HttpServletResponse res, FilterChain chain)
throws ServletException, IOException {
String tier = resolveTier(req);
String key = resolveKey(req, tier);
Bucket bucket = bucketRepository.getOrCreate(key, TIERS.get(tier));
ConsumptionProbe probe = bucket.tryConsumeAndReturnRemaining(1);
res.addHeader("X-RateLimit-Remaining", String.valueOf(probe.getRemainingTokens()));
if (!probe.isConsumed()) {
res.setStatus(429);
res.addHeader("Retry-After", "60");
return;
}
chain.doFilter(req, res);
}
private String resolveTier(HttpServletRequest req) {
if (req.getHeader("X-API-Key") != null) return "premium";
if (SecurityContextHolder.getContext().getAuthentication() != null) return "authenticated";
return "anonymous";
}
}
Background Jobs & Async Processing
Spring @Async (fire-and-forget)
@SpringBootApplication
@EnableAsync
public class Application { /* ... */ }
// Thread pool configuration
@Configuration
public class AsyncConfig {
@Bean("taskExecutor")
public Executor taskExecutor() {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
executor.setCorePoolSize(4);
executor.setMaxPoolSize(10);
executor.setQueueCapacity(100);
executor.setThreadNamePrefix("async-");
executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
executor.initialize();
return executor;
}
}
// Async service method
@Service
@Slf4j
public class IndexingService {
@Async("taskExecutor")
public CompletableFuture<Void> indexMarket(UUID marketId) {
try {
Market market = marketRepository.findById(marketId)
.orElseThrow(() -> new ResourceNotFoundException("Market not found"));
vectorStore.upsert(market.getId(), embeddingService.embed(market.toText()));
log.info("Indexed market {}", marketId);
} catch (Exception e) {
log.error("Failed to index market {}", marketId, e);
}
return CompletableFuture.completedFuture(null);
}
}
// Controller: respond immediately, index in background
@PostMapping
public ResponseEntity<MarketDto> create(@Valid @RequestBody CreateMarketRequest req) {
MarketDto created = marketService.create(req);
indexingService.indexMarket(created.id()); // non-blocking
return ResponseEntity.status(HttpStatus.CREATED).body(created);
}
Scheduled Jobs — Spring @Scheduled
@Component
@Slf4j
@RequiredArgsConstructor
public class MarketSyncJob {
private final MarketSyncService syncService;
@Scheduled(cron = "0 0 * * * *") // top of every hour
public void syncActiveMarkets() {
log.info("Starting market sync");
try {
int synced = syncService.syncAll();
log.info("Synced {} markets", synced);
} catch (Exception e) {
log.error("Market sync failed", e);
}
}
@Scheduled(fixedDelay = 30_000, initialDelay = 10_000) // every 30s
public void processQueue() {
syncService.drainQueue();
}
}
// Enable scheduling
@SpringBootApplication
@EnableScheduling
public class Application { /* ... */ }
Durable Queues with Spring Events + Outbox Pattern
For operations that must survive restarts, use a transactional outbox instead of @Async:
// 1. Save the job atomically with the triggering transaction
@Transactional
public MarketDto create(CreateMarketRequest request) {
Market market = marketRepository.save(new Market(request));
outboxRepository.save(new OutboxEvent("market.created", market.getId().toString()));
return MarketDto.from(market);
}
// 2. Poll the outbox table and dispatch
@Scheduled(fixedDelay = 5_000)
@Transactional
public void processOutbox() {
List<OutboxEvent> pending = outboxRepository.findPendingWithLock(10);
pending.forEach(event -> {
try {
dispatch(event);
event.markProcessed();
} catch (Exception e) {
event.incrementRetries();
log.error("Failed to dispatch event {}", event.getId(), e);
}
});
}
Logging & Monitoring
Structured Logging with SLF4J + Logback + MDC
// logback-spring.xml — JSON output for log aggregators (Datadog, Loki, CloudWatch)
// Use logstash-logback-encoder:
// <dependency>
// <groupId>net.logstash.logback</groupId>
// <artifactId>logstash-logback-encoder</artifactId>
// </dependency>
<!-- logback-spring.xml -->
<appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
<encoder class="net.logstash.logback.encoder.LogstashEncoder">
<includeMdcKeyName>requestId</includeMdcKeyName>
<includeMdcKeyName>userId</includeMdcKeyName>
<includeMdcKeyName>traceId</includeMdcKeyName>
</encoder>
</appender>
<root level="INFO">
<appender-ref ref="JSON"/>
</root>
// Request filter — populate MDC for every request
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class MdcFilter extends OncePerRequestFilter {
@Override
protected void doFilterInternal(HttpServletRequest req,
HttpServletResponse res, FilterChain chain)
throws ServletException, IOException {
String requestId = Optional.ofNullable(req.getHeader("X-Request-Id"))
.orElse(UUID.randomUUID().toString());
MDC.put("requestId", requestId);
MDC.put("method", req.getMethod());
MDC.put("path", req.getRequestURI());
// If JWT is already parsed, attach userId
Authentication auth = SecurityContextHolder.getContext().getAuthentication();
if (auth != null && auth.getPrincipal() instanceof UserPrincipal p) {
MDC.put("userId", p.id().toString());
}
try {
chain.doFilter(req, res);
} finally {
MDC.clear(); // critical — thread pool reuse means stale MDC leaks
}
}
}
// Service-level logging — MDC fields are added automatically
@Service
@Slf4j
public class MarketService {
public MarketDto findById(UUID id) {
log.info("Fetching market"); // requestId, userId added by MDC filter
return marketRepository.findById(id)
.map(MarketDto::from)
.orElseThrow(() -> {
log.warn("Market not found: {}", id);
return new ResourceNotFoundException("Market not found: " + id);
});
}
}
Actuator & Health Checks
# application.yml
management:
endpoints:
web:
exposure:
include: health, info, metrics, prometheus
base-path: /internal
endpoint:
health:
show-details: when-authorized
metrics:
tags:
application: ${spring.application.name}
// Custom health indicator
@Component
@RequiredArgsConstructor
public class VectorStoreHealthIndicator implements HealthIndicator {
private final VectorStore vectorStore;
@Override
public Health health() {
try {
vectorStore.ping();
return Health.up().withDetail("vectorStore", "reachable").build();
} catch (Exception e) {
return Health.down().withDetail("vectorStore", e.getMessage()).build();
}
}
}
React: Consuming Backend Patterns
Retry and Error Boundary
// src/components/AsyncBoundary.tsx — wraps TanStack Query errors
import { QueryErrorResetBoundary } from "@tanstack/react-query";
import { ErrorBoundary } from "react-error-boundary";
export function AsyncBoundary({ children }: { children: React.ReactNode }) {
return (
<QueryErrorResetBoundary>
{({ reset }) => (
<ErrorBoundary
onReset={reset}
fallbackRender={({ error, resetErrorBoundary }) => (
<div role="alert">
<p>Something went wrong: {error.message}</p>
<button onClick={resetErrorBoundary}>Retry</button>
</div>
)}
>
{children}
</ErrorBoundary>
)}
</QueryErrorResetBoundary>
);
}
Optimistic Updates
// src/hooks/useMarkets.ts
export function useDeleteMarket() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: marketsApi.delete,
onMutate: async (id: string) => {
await queryClient.cancelQueries({ queryKey: marketKeys.list() });
const previous = queryClient.getQueryData(marketKeys.list());
// Optimistically remove from list
queryClient.setQueryData(marketKeys.list(), (old: PagedResponse<MarketDto>) => ({
...old,
data: old.data.filter((m) => m.id !== id),
}));
return { previous };
},
onError: (_err, _id, context) => {
// Rollback on failure
queryClient.setQueryData(marketKeys.list(), context?.previous);
},
onSettled: () => {
queryClient.invalidateQueries({ queryKey: marketKeys.list() });
},
});
}
Background Refetching and Polling
// Poll for a resource until its status changes (e.g., async job completion)
export function useMarket(id: string) {
return useQuery({
queryKey: marketKeys.detail(id),
queryFn: () => marketsApi.getById(id),
refetchInterval: (query) => {
const status = query.state.data?.status;
// Stop polling once the job finishes
return status === "indexing" ? 3000 : false;
},
});
}
Architecture Layering Reference
Controller — HTTP binding (@RestController, @Valid, ResponseEntity)
↓
Service — Business logic, @Transactional, @Cacheable
↓
Repository — Data access (JpaRepository, @Query, Specification)
↓
Database — PostgreSQL / Redis / Vector store
Rules:
- Controllers never call repositories directly — only services.
- Services own transactions; repositories are transaction-aware but don't define them.
- DTOs cross the controller ↔ service boundary; domain entities stay in service ↔ repository.
- Never expose JPA entities in API responses — mapper to DTO first.
Checklist
Before shipping a new feature:
- [ ] Controller delegates to service — no business logic in
@RestController - [ ]
@Transactional(readOnly = true)on service class,@Transactionalon mutating methods only - [ ] N+1 queries eliminated — verified with SQL logging enabled
- [ ] Projections used for list endpoints instead of full entities
- [ ]
@Validon all@RequestBodyparameters - [ ]
@RestControllerAdvicehandles all exception types - [ ]
@Cacheable/@CacheEvictapplied at service layer, not controller - [ ] Async jobs (
@Async) don't swallow exceptions — useCompletableFutureor a recovery method - [ ] MDC populated per-request and cleared in
finally - [ ] No JPA entities serialized to JSON — always map to DTOs
- [ ] React query keys follow
[resource, action, params]structure - [ ] Optimistic updates with rollback for destructive mutations
- [ ]
AsyncBoundarywraps all data-fetching subtrees
04 同仓库更多 Skills
springboot-verification
Verification loop for Spring Boot projects: build, static analysis, tests with coverage, security scans, and diff review before release or PR.
springboot-tdd
Test-driven development for Spring Boot using JUnit 5, Mockito, MockMvc, Testcontainers, and JaCoCo. Use when adding features, fixing bugs, or refactoring.
springboot-security
Spring Security best practices for authn/authz, validation, CSRF, secrets, headers, rate limiting, and dependency security in Java Spring Boot services.
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.
quarkus-tdd
Test-driven development for Quarkus 3.x LTS using JUnit 5, Mockito, REST Assured, Camel testing, and JaCoCo. Use when adding features, fixing bugs, or refactoring event-driven services.
quarkus-security
Quarkus Security best practices for authentication, authorization, JWT/OIDC, RBAC, input validation, CSRF, secrets management, and dependency security.