kumaran-is Iron Law: Always load the java-spring-api skill and consult Spring MCP before writing Java code; never generate Spring WebFlux patterns from memory.
Java Coding Standards
Standards for readable, maintainable Java (21+) code in Spring Boot Reactive Web Flux services.
Core Principles
- Prefer clarity over cleverness
- Immutable by default; minimize shared mutable state
- Fail fast with meaningful exceptions
- Consistent naming and package structure
Key Rules
| Rule | Standard |
|---|---|
| Naming | Classes: PascalCase, methods/fields: camelCase, constants: UPPER_SNAKE_CASE |
| Immutability | Favor records and final fields; getters only, no setters. Exception: R2DBC entities require setters for framework binding |
| Optional | Return Optional from find* methods; use map/flatMap, never .get(). In reactive code, Mono<T> replaces Optional<T> — use switchIfEmpty() instead |
| Streams | Short pipelines for transforms; prefer loops for complex logic |
| Exceptions | Unchecked domain exceptions; avoid broad catch (Exception) |
| Generics | No raw types; prefer bounded generics for reusable utilities |
| Null handling | @NonNull by default; Bean Validation on inputs |
| Logging | SLF4J with structured key=value pairs |
| Testing | JUnit 5 + AssertJ + Mockito + WebTestClient for reactive; deterministic, no sleeps |
Project Structure
src/main/java/com/company/<service>/
config/ → controller/ → service/ → repository/ → model/entity/ → model/dto/ → exception/
src/main/resources/application.yml
src/test/java/... (mirrors main)
Code Examples & Detailed Patterns
For naming examples, immutability patterns, Optional usage, streams, exception handling, generics, logging, formatting, code smells, and testing expectations, Read reference/java-standards-examples.md.
Remember: Keep code intentional, typed, and observable. Optimize for maintainability over micro-optimizations unless proven necessary.
Error Handling
Checked vs unchecked exceptions: Use unchecked (RuntimeException subclasses) for programming errors. Use checked exceptions only for recoverable conditions the caller must handle.
Optional misuse: Never call .get() without .isPresent() or use .orElseThrow(). Prefer map/flatMap chains.