Spring Boot Development Patterns
Расширьте возможности Claude Code с помощью production-ready паттернов Spring Boot. Реализуйте REST API, многослойные сервисы, JPA и кеширование с использованием лучших практик Java.
Этот навык даёт Claude экспертизу для проектирования и реализации надёжных приложений на Spring Boot с использованием отраслевых паттернов. Он охватывает полный стек backend-разработки: от определения многослойной архитектуры (Controller-Service-Repository) и безопасных REST API до продвинутых функций, таких как распределённое кэширование, асинхронная обработка и отказоустойчивые внешние вызовы. Навык строго предписывает лучшие практики валидации, глобальной обработки исключений и наблюдаемости, гарантируя, что сгенерированный Java-код будет поддерживаемым, тестируемым и готовым к промышленной эксплуатации.
Ключевые возможности
Сценарии использования
| 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. |
| origin | ECC |
Ölçeklenebilir, üretim seviyesi servisler için Spring Boot mimari ve API desenleri.
- Spring MVC veya WebFlux ile REST API'leri oluşturma
- Controller → service → repository katmanlarını yapılandırma
- Spring Data JPA, caching veya async processing'i yapılandırma
- Validation, exception handling veya sayfalama ekleme
- Dev/staging/production ortamları için profiller kurma
- Spring Events veya Kafka ile event-driven desenler uygulama
@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);
}@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);
}
}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());
}
}@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) {
// Beklenmeyen hataları stack trace'ler ile loglayın
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
.body(ApiError.of("Internal server error"));
}
}Bir configuration sınıfında @EnableCaching gerektirir.
@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) {}
}Bir configuration sınıfında @EnableAsync gerektirir.
@Service
public class NotificationService {
@Async
public CompletableFuture<Void> sendAsync(Notification notification) {
// email/SMS gönder
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 {
// mantık
} 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;
}
}
}
}Güvenlik Notu: X-Forwarded-For başlığı varsayılan olarak güvenilmezdir çünkü istemciler onu taklit edebilir.
Forwarded başlıkları sadece şu durumlarda kullanın:
- Uygulamanız güvenilir bir reverse proxy'nin arkasında (nginx, AWS ALB, vb.)
ForwardedHeaderFilter'ı bean olarak kaydetmişsiniz- application properties'de
server.forward-headers-strategy=NATIVEveyaFRAMEWORKyapılandırmışsınız - Proxy'niz
X-Forwarded-Forbaşlığını üzerine yazmak için yapılandırılmış (eklememek için değil)
ForwardedHeaderFilter düzgün yapılandırıldığında, request.getRemoteAddr() otomatik olarak
forwarded başlıklardan doğru istemci IP'sini döndürür. Bu yapılandırma olmadan, request.getRemoteAddr() doğrudan kullanın—anlık bağlantı IP'sini döndürür, bu güvenilir tek değerdir.
@Component
public class RateLimitFilter extends OncePerRequestFilter {
private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();
/*
* GÜVENLİK: Bu filtre rate limiting için istemcileri tanımlamak üzere request.getRemoteAddr() kullanır.
*
* Uygulamanız bir reverse proxy'nin (nginx, AWS ALB, vb.) arkasındaysa, doğru istemci IP tespiti için
* Spring'i forwarded başlıkları düzgün işleyecek şekilde yapılandırmalısınız:
*
* 1. application.properties/yaml'da server.forward-headers-strategy=NATIVE (cloud platformlar için)
* veya FRAMEWORK ayarlayın
* 2. FRAMEWORK stratejisi kullanıyorsanız, ForwardedHeaderFilter'ı kaydedin:
*
* @Bean
* ForwardedHeaderFilter forwardedHeaderFilter() {
* return new ForwardedHeaderFilter();
* }
*
* 3. Proxy'nizin sahteciliği önlemek için X-Forwarded-For başlığını üzerine yazdığından emin olun (eklemediğinden)
* 4. Container'ınız için server.tomcat.remoteip.trusted-proxies veya eşdeğerini yapılandırın
*
* Bu yapılandırma olmadan, request.getRemoteAddr() istemci IP'si değil proxy IP'si döndürür.
* X-Forwarded-For'u doğrudan okumayın—güvenilir proxy işleme olmadan kolayca taklit edilebilir.
*/
@Override
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
FilterChain filterChain) throws ServletException, IOException {
// ForwardedHeaderFilter yapılandırıldığında doğru istemci IP'sini döndüren
// veya aksi halde doğrudan bağlantı IP'sini döndüren getRemoteAddr() kullanın. X-Forwarded-For
// başlıklarına doğrudan güvenmeyin, düzgun proxy yapılandırması olmadan.
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());
}
}
}Spring'in @Scheduled'ını kullanın veya kuyruklar ile entegre olun (örn. Kafka, SQS, RabbitMQ). Handler'ları idempotent ve gözlemlenebilir tutun.
- Logback encoder ile yapılandırılmış loglama (JSON)
- Metrikler: Micrometer + Prometheus/OTel
- Tracing: OpenTelemetry veya Brave backend ile Micrometer Tracing
- Constructor injection'ı tercih edin, field injection'dan kaçının
- RFC 7807 hataları için
spring.mvc.problemdetails.enabled=trueetkinleştirin (Spring Boot 3+) - İş yükü için HikariCP pool boyutlarını yapılandırın, timeout'ları ayarlayın
- Sorgular için
@Transactional(readOnly = true)kullanın @NonNullve uygun yerlerdeOptionalile null-safety zorlayın
Unutmayın: Controller'ları ince, servisleri odaklı, repository'leri basit ve hataları merkezi olarak işlenmiş tutun. Bakım yapılabilirlik ve test edilebilirlik için optimize edin.
🧩 Что это
Этот навык — шпаргалка для разработчика, пишущего на Java Spring Boot. Он содержит готовые шаблоны кода и рекомендации для создания REST API с многослойной архитектурой: Controller → Service → Repository. Навык покрывает типовые задачи: валидацию данных, обработку исключений, кеширование, асинхронные операции, логирование, фильтры, пагинацию, rate limiting и фоновые задачи. Цель — помочь быстро писать чистый, поддерживаемый и production-ready код, не изобретая велосипед для каждой повторяющейся задачи.
⚙️ Как работает
🏛️ Многослойная архитектура
Навык предлагает чёткое разделение ответственности между слоями:
- Controller — принимает HTTP-запросы, возвращает ответы. Использует аннотации
@RestControllerи@Validated. - Service — содержит бизнес-логику, аннотирован
@Serviceи@Transactional. - Repository — слой доступа к данным, использует Spring Data JPA (интерфейс, расширяющий
JpaRepository).
Пример контроллера:
@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));
}
}
🎯 Валидация и DTO
Для входящих данных используются Java Records с аннотациями @NotBlank, @Size, @NotNull, @FutureOrPresent и @NotEmpty. Ответы также оборачиваются в Record — это иммутабельно и лаконично.
❗ Централизованная обработка ошибок
@ControllerAdvice перехватывает все исключения и возвращает стандартизированный JSON с кодом ошибки. Это избавляет от дублирования try-catch в каждом контроллере.
💾 Кеширование
Аннотация @Cacheable на сервисе автоматически кеширует результат метода по ключу. @CacheEvict удаляет конкретный кеш. Требуется @EnableCaching в конфигурации.
@Cacheable(value = "market", key = "#id")
public Market getById(Long id) { ... }
⚡ Асинхронная обработка
@Async позволяет выполнять методы в отдельном потоке (например, отправка уведомлений). Возвращается CompletableFuture. Требуется @EnableAsync.
📋 Логирование
Используется SLF4J с параметризованными сообщениями (не конкатенация строк). Это улучшает читаемость логов и производительность.
🧰 Фильтры и Middleware
Наследуйтесь от OncePerRequestFilter, чтобы, например, логировать каждый запрос (метод, URI, статус, время выполнения).
📄 Пагинация и сортировка
Spring Data поддерживает PageRequest с параметрами page, size и Sort. Это стандартный способ разбивки больших списков.
🔁 Retry для внешних вызовов
Шаблон withRetry повторяет запрос при ошибке с экспоненциальной задержкой (2^attempts * 100 мс). Это повышает устойчивость к временным сбоям.
🚦 Rate Limiting с Bucket4j
Фильтр ограничивает количество запросов от одного IP (100 запросов в минуту). Используется ConcurrentHashMap для хранения сегментов (buckets). Важно: для корректного определения IP за прокси необходимо настроить server.forward-headers-strategy и ForwardedHeaderFilter. Никогда не доверяйте заголовку X-Forwarded-For напрямую — он легко подделывается, если не настроен доверенный прокси.
🕒 Фоновые задачи
Для периодических заданий используйте @Scheduled. В production лучше интегрироваться с очередями (Kafka, RabbitMQ, SQS) и делать обработчики идемпотентными.
📊 Наблюдаемость
Рекомендуется:
- Структурированное логирование (JSON через Logback).
- Метрики (Micrometer + Prometheus / OpenTelemetry).
- Трассировка (Micrometer Tracing).
✅ Когда использовать
- 🆕 Начало нового микросервиса — взять за основу многослойную структуру.
- 🛠️ Добавление REST API — быстрая реализация CRUD с валидацией и пагинацией.
- 🔐 Улучшение безопасности — внедрение rate limiting и корректной обработки IP за прокси.
- 📈 Оптимизация производительности — кеширование, асинхронность, пагинация.
- 🐞 Упрощение отладки — структурированное логирование и централизованная обработка ошибок.
💡 Важно знать
- Constructor injection — предпочтителен для всех бинов, полевая инъекция (
@Autowiredна поле) считается плохой практикой. - readOnly транзакции — для запросов на чтение ставьте
@Transactional(readOnly = true), это оптимизирует соединения с БД. - Null-safety — используйте
Optionalи@NonNull, чтобы избежать NullPointerException. - Spring Boot 3+ — включите
spring.mvc.problemdetails.enabled=trueдля автоматического возврата ошибок по стандарту RFC 7807 (Problem Details). - Настройка HikariCP — корректно конфигурируйте пул соединений под нагрузку вашего сервиса.
- Избегайте избыточности — контроллеры должны быть тонкими, сервисы содержать бизнес-логику, репозитории — только запросы к данным.
Какие версии Spring Boot поддерживает этот навык?
Он оптимизирован для современных версий Spring Boot, включая Spring Boot 3+, с использованием Java records, стандартов Jakarta EE и современных шаблонов внедрения зависимостей.
Обрабатывает ли этот навык взаимодействие с базами данных?
Да, он предоставляет оптимизированные шаблоны для Spring Data JPA, включая проектирование репозиториев, уровни сервисов с транзакциями и встроенную пагинацию/сортировку.
Включает ли навык глобальную обработку ошибок?
Да, он реализует централизованную обработку исключений с помощью @ControllerAdvice, чтобы обеспечить единообразные ответы об ошибках в соответствии с RFC для всего API.
Может ли навык помочь с производительностью приложения?
Безусловно. Навык включает шаблоны для абстракции @Cacheable, асинхронной обработки с @Async и отказоустойчивых вызовов внешних API с логикой повторных попыток.
Как навык работает с безопасностью API и ограничением скорости запросов?
Он предоставляет шаблоны реализации для ограничения скорости на основе Bucket4j и безопасные промежуточные фильтры, которые правильно обрабатывают определение IP-адреса клиента за обратными прокси.
Синхронизируйте навыки с Claude Cowork, Claude Code, Codex и другими.
Установка одной командой.
npx skillfish add affaan-m/everything-claude-code springboot-patternsИсточник: https://mcpmarket.com/tools/skills/spring-boot-development-patterns-8
Комментарии
Комментариев пока нет. Будьте первым.