Skip to content

Spring Boot Standards

Status: 🟢 Active  |  Owner: Java Guild

Approved Version

Spring Boot 3.2.x (minimum 3.2.0). Spring Boot 2.x is deprecated and must not be used for new services.

Project Structure

src/
├── main/
│   ├── java/com/acme/<domain>/
│   │   ├── domain/          # Domain model (no Spring annotations here)
│   │   ├── application/     # Use cases, command/query handlers
│   │   ├── infrastructure/
│   │   │   ├── persistence/ # JPA repositories, entities
│   │   │   ├── web/         # REST controllers, DTOs
│   │   │   └── messaging/   # Kafka producers/consumers
│   │   └── <ServiceName>Application.java
│   └── resources/
│       ├── application.yml
│       ├── application-local.yml
│       └── db/migration/    # Flyway migrations
└── test/
    ├── java/...
    └── resources/
        └── application-test.yml

Required Dependencies (All New Services)

dependencies {
    // Core
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation 'org.springframework.boot:spring-boot-starter-actuator'

    // Persistence
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.flywaydb:flyway-core'

    // Observability
    implementation 'io.micrometer:micrometer-registry-prometheus'
    implementation 'io.micrometer:micrometer-tracing-bridge-otel'

    // Security
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'

    // Testing
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.testcontainers:postgresql'
    testImplementation 'org.testcontainers:kafka'
}

Configuration Standards

# application.yml — required actuator and management config
management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus,metrics
  endpoint:
    health:
      show-details: when-authorized
      probes:
        enabled: true  # Enables /health/liveness and /health/readiness

spring:
  application:
    name: order-service
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 3000
      idle-timeout: 600000

Forbidden Practices

  • ❌ @Autowired on fields — use constructor injection only.
  • ❌ @Component on domain objects — domain must not depend on Spring.
  • ❌ @Transactional on controllers — transactions belong on the service/use-case layer.
  • ❌ Business logic in @RestController classes.

Last reviewed: 2025-Q4  |  Owner: Java Guild