a-pavithraa/springboot-skills-marketplace / plugins/springboot-architecture/skills/creating-springboot-projects
creating-springboot-projects
VerifiedUse when starting a new Spring Boot project or service: scaffolding or bootstrapping a backend, REST API, microservice or modular monolith; choosing how to structure it (layered, package-by-module, modular monolith, tomato, DDD-hexagonal); selecting Spring Boot 4 features; generating the base project with progen or Spring Initializr; or applying the bundled templates and references in this skill. Not for migrating existing projects or for isolated JPA/repository work without broader project-creation context.
references/spring-boot-4-features.md
View on GitHub# Spring Boot 4 New Features Reference
## Table of Contents
1. [Overview](#overview)
2. [1. RestTestClient - Modern REST Testing](#1-resttestclient---modern-rest-testing)
3. [2. Native Resiliency Features](#2-native-resiliency-features)
4. [3. HTTP Service Client Simplification](#3-http-service-client-simplification)
5. [4. API Versioning](#4-api-versioning)
6. [5. Spring Data AOT - Native Image Support](#5-spring-data-aot---native-image-support)
7. [6. JSpecify Null-Safety](#6-jspecify-null-safety)
8. [Dependencies](#dependencies)
9. [Migration from Spring Boot 3](#migration-from-spring-boot-3)
---
## Overview
Spring Boot 4 (built on Spring Framework 7; Java 17 minimum) includes six major features that eliminate the need for external libraries and improve developer experience. Recommended toolchain: Java 25 (LTS). See [`java-version-policy.md`](java-version-policy.md) for newer releases.
## 1. RestTestClient - Modern REST Testing
**Recommended new HTTP test client.** `TestRestTemplate` is not deprecated, but `@SpringBootTest` no longer auto-provides it in Boot 4 — opt in via `@AutoConfigureTestRestTemplate` to keep existing tests, or migrate to `RestTestClient` for new ones.
**Benefits:**
- Fluent, readable API for integration tests
- Built-in API versioning support with `.apiVersion("2.0")`
- Better type safety with ParameterizedTypeReference
- More intuitive assertions
**Template:** `resttestclient-test.java`
**Basic Usage:**
```java
@SpringBootTest(webEnvironment = RANDOM_PORT)
class ProductControllerTest {
@Autowired
private WebApplicationContext context;
private RestTestClient client;
@BeforeEach
void setup() {
client = RestTestClient.bindToApplicationContext(context)
.apiVersionInserter(ApiVersionInserter.useHeader("X-API-Version"))
.build();
}
@Test
void shouldGetProduct() {
ProductVM product = client.get()
.uri("/api/products/{id}", "PRD-001")
.exchange()
.expectStatus().isOk()
.expectBody(ProductVM.class)
.returnResult()
.getResponseBody();
assertThat(product.id()).isEqualTo("PRD-001");
}
}
```
**Key Methods:**
- `.get()`, `.post()`, `.patch()`, `.delete()` - HTTP methods
- `.uri()` - Set request URI with path variables
- `.apiVersion("2.0")` - Set API version header
- `.exchange()` - Execute request
- `.expectStatus()` - Assert status code
- `.expectBody()` - Assert response body
## 2. Native Resiliency Features
**What's Native in Spring Framework 7:**
- `@Retryable` — automatic retry with backoff (`org.springframework.resilience.annotation`)
- `@ConcurrencyLimit` — concurrent-invocation throttling. From the Framework reference: "specifies a concurrency limit for an individual method ... meant to protect the target resource from being accessed from too many threads at the same time, similar to the effect of a pool size limit for a thread pool or a connection pool that blocks access if its limit is reached." This is **not** time-window rate limiting and **not** the Resilience4j bulkhead.
**What Still Requires External Libraries:**
- Circuit Breaker → Resilience4j (`spring-cloud-starter-circuitbreaker-resilience4j`)
- Time-window rate limiting (requests-per-second budgets) → Resilience4j or Bucket4j; `@ConcurrencyLimit` only caps in-flight concurrency.
- Resilience4j-style Bulkhead with queueing semantics → Resilience4j
**Benefits:**
- Native retry and concurrency features with zero dependencies
- Seamless reactive programming support
- Integration with Virtual Threads (Project Loom)
**Decision note:**
- Spring Retry is now maintenance-only and superseded by Spring Framework 7 resilience features.
- Prefer `org.springframework.resilience.annotation.*` for new Boot 4 projects and remove `spring-retry` if not needed.
- Reference: https://github.com/spring-projects/spring-retry
**Template:** `resilience-service.java`
### @Retryable - Automatic Retries (NATIVE)
```java
import org.springframework.resilience.annotation.Retryable;
@Service
public class ProductService {
// 1 initial attempt + maxRetries — up to 5 total invocations here
@Retryable(
includes = {RuntimeException.class},
maxRetries = 4,
delay = 2000L // milliseconds
)
public Optional<Product> fetchFromExternalApi(String id) {
return externalClient.getById(id);
}
// Optional: Advanced configuration with exponential backoff (up to 4 total invocations)
@Retryable(
includes = {IOException.class},
maxRetries = 3,
delay = 1000,
multiplier = 2
)
public String callRemoteService() {
// transient failures handled automatically
}
}
```
**Configuration:**
- Requires `@EnableResilientMethods` on a `@Configuration` class
- Package: `org.springframework.resilience.annotation.*`
- Supports exponential backoff, jitter, and reactive types
- Works seamlessly with Virtual Threads
**Parameters:**
- `includes` - Exception types that trigger retry
- `excludes` - Exception types that should never retry
- `maxRetries` - Number of retries after the initial attempt (default: 3 — total invocations = 1 + maxRetries)
- `delay` / `delayString` - Delay between retries
- `multiplier` - Exponential backoff multiplier
- `maxDelay` - Maximum delay ceiling
**Use cases:**
- External API calls with transient failures
- Database operations during brief connection issues
- Network operations with temporary disruptions
### @ConcurrencyLimit - Concurrent Invocation Throttling (NATIVE)
```java
import org.springframework.resilience.annotation.ConcurrencyLimit;
@Service
public class ReportService {
@ConcurrencyLimit(2) // At most 2 invocations in flight at any time
public void processExpensiveOperation(String id) {
performExpensiveWork(id);
}
}
```
Semantics: when the third caller arrives while 2 invocations are already running, it **blocks** until a slot frees up — same shape as a fixed-size connection pool. It is not a time-window rate limit and does not implement Resilience4j-style bulkhead queueing.
**Configuration:**
- Requires `@EnableResilientMethods` on a `@Configuration` class
- Package: `org.springframework.resilience.annotation.*`
- Particularly valuable with Virtual Threads, where caller threads are cheap and back-pressure has to come from somewhere
**Good fits:**
- Cap concurrent calls into an expensive downstream (DB report query, slow third-party API) to protect the resource
- Hold the in-flight count below a known safe ceiling regardless of how many caller threads exist
**NOT this annotation's job:**
- Time-window rate limiting ("≤ 100 requests/sec") — use Resilience4j or Bucket4j
- Resilience4j-style Bulkhead with explicit queue depth / wait timeout semantics — use Resilience4j
### RetryTemplate - Programmatic Retry (NATIVE)
For scenarios needing more control than `@Retryable`:
```java
import org.springframework.core.retry.RetryPolicy;
import org.springframework.core.retry.RetryTemplate;
@Service
public class DriverAssignmentService {
private final RetryTemplate retryTemplate;
public DriverAssignmentService() {
// 1 initial attempt + maxRetries — up to 11 total invocations
RetryPolicy retryPolicy = RetryPolicy.builder()
.maxRetries(10)
.delay(Duration.ofMillis(2000))
.multiplier(1.5)
.maxDelay(Duration.ofMillis(10000))
.includes(NoDriversAvailableException.class)
.build();
this.retryTemplate = new RetryTemplate(retryPolicy);
}
public Driver assignDriver(Order order) {
return retryTemplate.execute(() -> {
// logic that may throw NoDriversAvailableException
return findAvailableDriver(order);
});
}
}
```
**Observability with RetryListener:**
```java
import org.springframework.core.retry.RetryListener;
import org.springframework.core.retry.RetryPolicy;
import org.springframework.core.retry.Retryable;
@Component
public class MetricsRetryListener implements RetryListener {
@Override
public void beforeRetry(RetryPolicy policy, Retryable<?> retryable) {
// track attempt count, log retry start
}
@Override
public void onRetrySuccess(RetryPolicy policy, Retryable<?> retryable, Object result) {
// track successful recovery
}
@Override
public void onRetryFailure(RetryPolicy policy, Retryable<?> retryable, Throwable t) {
// track exhausted retries
}
}
```
Attach to template: `retryTemplate.setRetryListener(listener)`
Source: [danvega/quick-bytes](https://github.com/danvega/quick-bytes) (Spring Boot 4.0.0-RC2)
### Circuit Breaker - Requires Resilience4j
**NOT native in Spring Boot 4.** For circuit breaker patterns, use Resilience4j:
```xml
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-circuitbreaker-resilience4j</artifactId>
</dependency>
<!-- Use the Boot 4-specific starter. The dedicated resilience4j-spring-boot4 module is currently 2.4.0 on Maven Central — confirm the latest at https://central.sonatype.com/artifact/io.github.resilience4j/resilience4j-spring-boot4 before pinning. -->
<dependency>
<groupId>io.github.resilience4j</groupId>
<artifactId>resilience4j-spring-boot4</artifactId>
</dependency>
```
```java
@Service
public class ProductService {
@CircuitBreaker(name = "productService", fallbackMethod = "fallbackFetch")
public List<Product> fetchFromUnreliableService() {
return externalClient.getAll();
}
private List<Product> fallbackFetch(Exception e) {
return Collections.emptyList();
}
}
```
**Configuration (application.yml):**
```yaml
resilience4j:
circuitbreaker:
instances:
productService:
failure-rate-threshold: 50
wait-duration-in-open-state: 30s
sliding-window-size: 10
```
**⚠️ Note:** Verify the current Resilience4j release before upgrading — see [the Resilience4j releases page](https://github.com/resilience4j/resilience4j/releases). The dedicated `resilience4j-spring-boot4` module is the right starter for Boot 4; the older `resilience4j-spring-boot3` is for Boot 3 stacks.
## 3. HTTP Service Client Simplification
**What's new:** `@ImportHttpServices` auto-configuration (Spring Framework 7.0) replaces manual `HttpServiceProxyFactory` bean wiring. `@HttpExchange` itself exists since Framework 6.0.
**Benefits:**
- Declarative interface-based clients
- Auto-configuration with @ImportHttpServices
- Less boilerplate
- Type-safe API definitions
**Template:** `http-service-client.java`
**Before Spring Boot 4:**
```java
@Bean
ProductClient productClient(RestClient.Builder builder) {
RestClient restClient = builder.baseUrl("http://api.example.com").build();
var factory = HttpServiceProxyFactory
.builderFor(RestClientAdapter.create(restClient))
.build();
return factory.createClient(ProductClient.class);
}
```
**With Spring Boot 4:**
```java
// 1. Define interface
@HttpExchange
public interface ProductClient {
@GetExchange(url = "/api/products/{id}")
Optional<ProductDTO> findById(@PathVariable Long id);
@PostExchange(url = "/api/products")
ProductDTO create(CreateProductRequest request);
}
// 2. Auto-configure — group organizes services sharing the same HTTP client config
@Configuration
@ImportHttpServices(group = "product", types = ProductClient.class)
public class ClientConfig {
// That's it! RestClient is the default client type.
}
```
**Features:**
- `@HttpExchange` - Mark interface as HTTP client
- `@GetExchange`, `@PostExchange`, `@PutExchange`, `@DeleteExchange` - HTTP methods
- API versioning support: `@GetExchange(url = "...", version = "2.0")`
- Path variables: `@PathVariable`
- Query params: `@RequestParam`
- Request body: Method parameter
**Configuration (application.yml):**
```yaml
spring:
http:
clients:
connect-timeout: 5s
serviceclient:
product: # Group name (matches @ImportHttpServices group)
base-url: http://localhost:8080
read-timeout: 10s
```
## 4. API Versioning
**Replaces:** Custom versioning implementations, external libraries
**Benefits:**
- Native Spring Boot support
- Clean URL structure (with header approach)
- Easy to test
- Works with HTTP Service Client
**Template:** `api-versioning-config.java`
**Configuration Option 1 - Properties (Recommended):**
```yaml
spring:
mvc:
apiversion:
default: "1.0"
supported: "1.0,2.0"
use:
header: X-API-Version
# Alternative strategies (use only one resolver):
# query-parameter: version
# path-segment: 1
# media-type-parameter[application/json]: version
```
**Configuration Option 2 - Java (`WebMvcConfigurer.configureApiVersioning`):**
```java
import org.springframework.web.accept.SemanticApiVersionParser;
import org.springframework.web.servlet.config.annotation.ApiVersionConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class ApiVersioningConfig implements WebMvcConfigurer {
@Override
public void configureApiVersioning(ApiVersionConfigurer configurer) {
configurer
.useRequestHeader("X-API-Version") // resolver
// .useQueryParam("version")
// .useMediaTypeParameter(MediaType.APPLICATION_JSON, "version")
// .usePathSegment(1)
.addSupportedVersions("1.0", "2.0")
.setDefaultVersion("1.0")
.setVersionParser(new SemanticApiVersionParser()); // optional — default
}
}
```
Notes: `ApiVersionConfigurer` lives in `org.springframework.web.servlet.config.annotation`. The default parser is `SemanticApiVersionParser` from `org.springframework.web.accept`. There are no `ApiVersionResolver.fromHeader(...)` / `ApiVersionParser.semantic()` static factories.
**Versioning Strategies:**
1. **Request Header** (recommended): `X-API-Version: 2.0`
2. **Query Parameter**: `/api/products?version=2.0`
3. **Media Type**: `Accept: application/json;ver=2.0`
4. **Path**: `/v2/api/products` (less common with native support)
**Controller Implementation:**
```java
@RestController
@RequestMapping("/api/products")
public class ProductController {
@GetMapping(value = "/search", version = "1.0")
public List<ProductVM> searchV1(@RequestParam("q") String query) {
return service.searchByTitle(query);
}
@GetMapping(value = "/search", version = "2.0")
public List<ProductEnrichedVM> searchV2(@RequestParam("q") String query) {
return service.searchWithDetails(query);
}
}
```
**Testing with RestTestClient:**
```java
client.get()
.uri("/api/products/search?q=test")
.apiVersion("2.0") // Sets X-API-Version header
.exchange()
.expectStatus().isOk();
```
**HTTP Service Client with Versioning:**
```java
@HttpExchange
public interface ProductClient {
@GetExchange(url = "/api/products/search", version = "1.0")
List<ProductVM> searchV1(@RequestParam("q") String query);
@GetExchange(url = "/api/products/search", version = "2.0")
List<ProductEnrichedVM> searchV2(@RequestParam("q") String query);
}
```
## 5. Spring Data AOT - Native Image Support
**Benefits:**
- Faster startup with GraalVM native images
- Better performance for cloud/serverless
- Reduced memory footprint
**Configuration (pom.xml):**
```xml
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<id>process-aot</id>
<goals>
<goal>process-aot</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
```
**When to use:**
- Cloud-native applications
- Serverless deployments (AWS Lambda, Google Cloud Functions)
- Applications needing fast startup
- Containerized microservices
**Limitations:**
- Reflection and dynamic proxies may need hints
- Some libraries may not be fully compatible
- Build time increases
## 6. JSpecify Null-Safety
**Benefits:**
- Compile-time null checking
- Better IDE support
- Improved code documentation
- Works with Kotlin null safety
**Template:** `package-info-jspecify.java`
**Package-level Configuration:**
```java
@NullMarked
package com.example.products;
import org.jspecify.annotations.NullMarked;
```
**Usage:**
```java
// All types are non-null by default
public class ProductEntity {
private Long id; // Non-null (required)
private String name; // Non-null (required)
@Nullable private String description; // Nullable (optional)
public @Nullable String getDescription() {
return description;
}
}
// Repository with Optional
public interface ProductRepository extends JpaRepository<ProductEntity, Long> {
// Good: Use Optional for potentially absent values
Optional<ProductEntity> findByName(String name);
// Good: List is never null
List<ProductEntity> findByStatus(String status);
}
// Controller with validation
@RestController
public class ProductController {
@GetMapping("/{id}")
public ProductVM getById(@PathVariable Long id) { // Non-null by default with @NullMarked
return service.findById(id);
}
@GetMapping("/search")
public List<ProductVM> search(
@RequestParam @Nullable String query, // Optional
@RequestParam(defaultValue = "0") int page
) {
return service.search(query, page);
}
}
```
**IDE Configuration:**
- IntelliJ IDEA: Settings → Editor → Inspections → Nullability problems
- Eclipse: Preferences → Java → Compiler → Errors/Warnings → Null analysis
**Best Practices:**
- Use @Nullable sparingly - most things should be non-null
- Prefer Optional<T> for return types over @Nullable
- Use @Nullable for optional fields in entities/records
- Validate at API boundaries (controllers, external integrations)
- Fail fast - throw exceptions early for invalid nulls
## Dependencies
Boot 4 uses modular starters. Add only what you need:
| Starter | Provides |
|---------|----------|
| `spring-boot-starter-webmvc` | Spring MVC (replaces `spring-boot-starter-web`) |
| `spring-boot-starter-restclient` | RestClient / RestTemplate |
| `spring-boot-starter-webclient` | WebClient (reactive) |
| `spring-boot-starter-aspectj` | AspectJ `@Aspect` support, Micrometer `@Timed`/`@Observed`, Resilience4j annotations. Not needed for native `@Retryable`/`@ConcurrencyLimit` |
**Verify versions:**
```xml
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.1.0</version>
</parent>
<properties>
<!-- Boot 4 baseline is 17. Recommended: 25 (LTS).
For newer releases see java-version-policy.md. -->
<java.version>25</java.version>
</properties>
```
## Migration from Spring Boot 3
This file covers new projects. For upgrades, use the `springboot-migration` skill and `../../springboot-migration/references/spring-boot-4-migration.md`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |