mirror of
https://github.com/sweetwisdom/everything-claude-code-zh.git
synced 2026-03-22 06:20:10 +00:00
fix: restore missing files (package.json etc) and fix sync script logic
This commit is contained in:
xuxiang
304
skills/springboot-patterns/SKILL.md
Normal file
304
skills/springboot-patterns/SKILL.md
Normal file
@@ -0,0 +1,304 @@
|
||||
---
|
||||
name: springboot-patterns
|
||||
description: Spring Boot architecture patterns, REST API design, layered services, data access, caching, async processing, and logging. Use for Java Spring Boot backend work.
|
||||
---
|
||||
|
||||
# Spring Boot Development Patterns
|
||||
|
||||
Spring Boot architecture and API patterns for scalable, production-grade services.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user