java-springboot-standards

Java Spring Boot Standards (your monorepo)

Apply these standards when writing or modifying Java/Spring Boot code in this workspace (Agentic Loop / your service services and related APIs). Patterns are derived from the SpringBootProdTemplate reference and existing Agentic Loop services.

Toolchain baseline: Java 25 (Corretto), Spring Boot 4.x, Gradle 9.x. Do NOT add explicit version pins — the BOM/platform manages versions.

1. Architecture & layering

Controller -> Orchestration service -> granular services -> repository/client. Keep controllers thin (no business logic). Program to interfaces.

• Each service has an interface (IFooService) and an impl (impl/FooService).
• Inject collaborators via constructor with @RequiredArgsConstructor. Never use field @Autowired.
• No try-catch or Azure/external SDK calls inside controllers. Move all I/O to the service layer and let exceptions surface to GlobalExceptionHandler.
• Centralize domain not-found handling in the service layer — controllers must not repeat orElseThrow(() -> new EntityNotFoundException(...)). See §7 Service-layer not-found and Optional lookups.

// GOOD
@Service
@RequiredArgsConstructor
@Slf4j
public class FooOrchestrationService implements IFooOrchestrationService {
    private final ICreateFooService createFooService;
    private final IFooRetrievalService fooRetrievalService;
}

// BAD
@Service
public class FooService {
    @Autowired private CreateFooService createFooService; // field injection, concrete type
}

2. Java 25 language features — prefer modern syntax

Actively use Java 25 constructs instead of verbose equivalents:

• Records for all immutable value types, DTOs, config holders, internal results:

  public record ErrorDetail(String field, String message) { }
  public record AppHealthSummary(String resourceId, String status, Instant checkedAt) { }
  

• Sealed classes for closed domain hierarchies (e.g. health check result variants):

  public sealed interface CheckResult permits OkResult, DegradedResult, DownResult { }
  

• Pattern matching for instanceof — no explicit cast:

  // GOOD
  if (result instanceof DegradedResult dr) { log.warn("Degraded: {}", dr.reason()); }
  // BAD
  if (result instanceof DegradedResult) { DegradedResult dr = (DegradedResult) result; }
  

• Pattern matching for switch (finalized):

  String label = switch (result) {
      case OkResult ok      -> "UP";
      case DegradedResult d -> "DEGRADED: " + d.reason();
      case DownResult dn    -> "DOWN";
  };
  

• Text blocks for multi-line strings (JSON templates, SQL, YAML snippets):

  String body = """
      {"resourceId": "%s", "status": "DOWN"}
      """.formatted(resourceId);
  

• var for local variables where the type is obvious from the right-hand side. Do not use var for fields or where it obscures the type.
• Virtual threads — Spring Boot 4 enables virtual threads by default (spring.threads.virtual.enabled=true). Do NOT create raw Thread objects or tune thread-pool sizes for I/O-bound work; let the container manage concurrency.