/java-rules

name: java-rules
description: "Java coding rules: style, patterns, security, testing. Triggers: .java, pom.xml, build.gradle, Spring, Spring Boot, JPA, Hibernate, JUnit, Maven, Gradle."
effort: medium
user-invocable: false
allowed-tools: Read

Java Rules

These rules come from `app/rules/java/` in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in Java. Apply them when writing or reviewing Java code.

Java Coding Style

Naming

• PascalCase: classes, interfaces, enums, records, annotations.
• camelCase: methods, variables, parameters.
• UPPER_SNAKE: constants (`static final`).
• Package names: lowercase, dot-separated, reverse domain (`com.company.project`).
• No Hungarian notation. No `I` prefix on interfaces.

Modern Java (17+)

• Use `record` for immutable data carriers. No need for Lombok in most cases.
• Use `sealed` classes/interfaces for restricted hierarchies.
• Use pattern matching: `if (obj instanceof String s)` instead of cast.
• Use `switch` expressions with arrow syntax and exhaustiveness.
• Use text blocks (`"""`) for multiline strings (SQL, JSON, HTML).

Types

• Use `var` for local variables when the type is obvious from the right-hand side.
• Use `Optional<T>` for return types that may be absent. Never for fields or params.
• Prefer `List.of()`, `Map.of()`, `Set.of()` for immutable collections.
• Use `Stream` for collection transformations. Avoid streams for simple iterations.

Classes

• Prefer composition over inheritance. Use interfaces for abstraction.
• Keep classes focused: single responsibility.
• Use `final` on classes not designed for extension.
• Use `private` constructors + static factory methods for controlled instantiation.
• Records over POJOs for value types. Lombok only if records are insufficient.

Methods

• Max 20-30 lines per method. Extract when longer.
• Use `@Override` on every overridden method.
• Return empty collections over `null`. Use `Collections.emptyList()` or `List.of()`.
• Avoid checked exceptions for programming errors. Use runtime exceptions.

Formatting

• Use project formatter (Google Java Format or IDE-configured).
• Use `@SuppressWarnings` sparingly and with specific warning names.
• Use `final` for parameters and local variables where practical.

Nullability

• Annotate with `@Nullable` / `@NonNull` from JSpecify or JetBrains.
• Use `Objects.requireNonNull()` at public API boundaries.
• Never return `null` from collections or arrays. Return empty.
• Use `Optional` for genuinely optional return values.

Documentation

• Javadoc on all public classes and methods.
• Use `@param`, `@return`, `@throws` tags for public API methods.
• Skip Javadoc for obvious getters, `toString()`, and `equals()`.

Java Frameworks

Spring Boot

• Use Spring Boot 3+ with Java 17+ minimum.
• Use `@RestController` for REST APIs. Return `ResponseEntity` for status control.
• Use `@Valid` + Jakarta Bean Validation for request validation.
• Use profiles (`@Profile`) for environment-specific configuration.
• Use `application.yml` over `application.properties` for readability.
• Externalize config: env vars > config files > hardcoded defaults.

Spring Data JPA

• Use repository interfaces extending `JpaRepository`.
• Use `@Query` with JPQL for custom queries. Use native queries only when needed.
• Use `@EntityGraph` to prevent N+1 queries in associations.
• Use `Specification` for dynamic query building.
• Always use `@Transactional` at the service layer, not repository.

Spring Security

• Use `SecurityFilterChain` bean configuration (not `WebSecurityConfigurerAdapter`).
• Use `@PreAuthorize` / `@Secured` for method-level authorization.
• Use BCrypt for password encoding: `new BCryptPasswordEncoder()`.
• Configure CORS, CSRF, and session management explicitly.
• Use OAuth2 Resource Server for JWT validation in APIs.

Hibernate / JPA

• Use `FetchType.LAZY` by default on all associations.
• Use `@BatchSize` or `@Fetch(FetchMode.SUBSELECT)` to avoid N+1.
• Use `@Version` for optimistic locking on entities.
• Use DTOs (records) for read queries. Do not expose entities in APIs.
• Use Flyway or Liquibase for schema migrations.

Quarkus / Micronaut

• Use for microservices and serverless where startup time matters.
• Use compile-time DI (Micronaut) or build-time optimization (Quarkus).
• Use reactive patterns with Mutiny (Quarkus) or Reactor (Micronaut).
• Use native image builds with GraalVM for production deployments.

Build Tools

• Use Gradle (Kotlin DSL) for new projects. Maven for enterprise legacy.
• Use dependency management to unify versions across modules.
• Use Bill of Materials (BOM) imports for consistent Spring versions.
• Use Spotless or Checkstyle for enforced code formatting.

Logging

• Use SLF4J facade with Logback or Log4j2 backend.
• Use structured logging with MDC for correlation IDs.
• Use parameterized logging: `log.info("User {} created", userId)`.
• Never log sensitive data (passwords, tokens, PII).

Java Patterns

Error Handling

• Use unchecked exceptions for programming errors (`IllegalArgumentException`).
• Use checked exceptions only for recoverable conditions the caller must handle.
• Create domain exception hierarchy: `AppException` -> `NotFoundException`, etc.
• Never catch `Exception` or `Throwable` broadly. Catch specific types.
• Use `try-with-resources` for all `AutoCloseable` resources.

Immutability

• Use `record` for immutable value objects (Java 16+).
• Use `List.copyOf()`, `Map.copyOf()` to create unmodifiable copies.
• Make fields `private final`. No setters unless mutation is required.
• Return defensive copies of mutable collections from getters.
• Use builder pattern for constructing immutable objects with many fields.

Optional

• Use `Optional<T>` as return type for methods that may not return a value.
• Chain: `optional.map(...).orElseThrow(...)`. Avoid `isPresent()` + `get()`.
• Never use `Optional` for fi