spring-boot-conventions

Standardizes Spring Boot 3 idioms for configuration, validation, async, caching, and scheduling.

Updated Jun 25, 2026
One-click install
npx skills add https://github.com/oriddd/ai-toolkit --skill spring-boot-conventions-oriddd
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: spring-boot-conventions
Source: https://github.com/oriddd/ai-toolkit/tree/main/copilot/public/skills/spring-boot-conventions
Command: npx skills add https://github.com/oriddd/ai-toolkit --skill spring-boot-conventions-oriddd

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Java microservice teams often adopt Spring Boot features inconsistently, mixing @Value with @ConfigurationProperties, hard-coding scheduled intervals, or using RestTemplate in new code. This Skill provides a single canonical checklist so every Spring Boot feature is used the same way across the project. ## Core Features & Use Cases - Configuration conventions: Typed @ConfigurationProperties records with JSR-380 validation, profile-based YAML inheritance, and conditional beans for optional features. - Runtime conventions: Named TaskExecutors for @Async work, safe @Scheduled jobs with idempotency and Shedlock guidance, explicit cache providers, and injected Clock for testable time logic. - API conventions: springdoc OpenAPI documentation, Pageable pagination contract, Idempotency-Key handling for retried POST/PATCH requests, and application events for in-service fan-out. - Use Case: When adding a new outbound HTTP integration or a scheduled cleanup job to a Spring Boot 3 service, apply this Skill to pick the canonical RestClient pattern and a property-driven, cluster-safe @Scheduled task. ## Quick Start Apply the spring-boot-conventions skill to review this Spring Boot service and align its configuration, scheduling, and HTTP client code with the canonical patterns.

Frequently Asked Questions about spring-boot-conventions

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I configure Spring Boot properties with @ConfigurationProperties?

Group related properties into a single immutable @ConfigurationProperties record with a prefix matching <bounded-context>.<feature>, and enable scanning via @ConfigurationPropertiesScan. Add @NotBlank, @Positive, or @Min annotations so misconfiguration fails fast at startup, and reserve @Value for single isolated values only.

How do I write a safe @Scheduled job in Spring Boot?

Put @Scheduled on a dedicated task component, drive the interval from a property like fixedRateString = "${prop:default}", and never hard-code milliseconds. The task must be idempotent, never throw (always try/catch and log), and use Shedlock when running with multiple replicas.

Should I use RestTemplate or RestClient in Spring Boot 3?

Use RestClient (Spring 6.1+) for synchronous outbound HTTP or WebClient for reactive calls in all new code. RestTemplate is in maintenance mode and should not be used for new integrations.

Does @Async work with void return types in Spring?

Avoid @Async on void methods; return CompletableFuture<Void> instead so callers can wait for completion. Always define a named ThreadPoolTaskExecutor with explicit pool sizes and a CallerRunsPolicy rather than relying on the framework default executor.

When should I use Spring profiles versus feature flags?

Use profiles only for infrastructure connectivity differences (database URLs, hosts) via application-{profile}.yaml overrides and environment variables. Never toggle business logic with profiles; use feature flags backed by @ConditionalOnProperty beans instead.