java-springboot

name	java-springboot
description	Spring Boot best practices for Java 21 backend work. Use when creating, reviewing, refactoring, or testing backend/**/*.java, Spring Boot controllers/services/configuration, REST APIs, external clients, resilience, logging, validation, or Flyway-backed persistence in this repository.

Spring Boot Best Practices

Source: adapted from github/awesome-copilot skill java-springboot and this repository's .github/copilot-instructions.md Java conventions.

When to Use

• Creating or editing Java files under backend/**/*.java
• Reviewing Spring Boot controller, service, repository, or configuration code
• Adding API endpoints, external service clients, database access, logging, or resilience behavior
• Debugging Java code quality issues before a PR or architecture review

Procedure

1. Read .github/copilot-instructions.md and .github/instructions/java.instructions.md before changing backend code.
2. Prefer Java 21 language features where they simplify the code: records for immutable DTOs, pattern matching where it improves clarity, and sealed classes only for real closed hierarchies.
3. Use constructor injection only. Required dependencies should be private final; do not use field @Autowired.
4. Keep Spring components focused: controllers handle HTTP concerns, services hold business rules, repositories handle persistence, and configuration classes bind external settings.
5. Use DTOs and Bean Validation for request/response contracts. Do not expose persistence entities directly from controllers.
6. Use @ConfigurationProperties for structured configuration and environment variables or Key Vault references for values that differ by environment.
7. Never hardcode credentials, subscription IDs, connection strings, or secrets in Java files or application.yml.
8. Configure explicit timeouts for every external call. Use Resilience4j circuit breakers, retries, and rate limiters where calls cross process or service boundaries.
9. Use SLF4J parameterized logging and structured JSON logging. Propagate correlation IDs through MDC and never use System.out.
10. Use Flyway for schema changes. Add new migration files only; never rewrite existing migrations.
11. Validate behavior with focused tests: unit tests for services, MVC slice tests for controllers, and integration tests where Spring wiring or persistence is the risk.

Review Checklist

• Constructor injection and private final dependencies
• Clear DTOs and validation on API boundaries
• No secret or subscription ID literals
• Explicit timeouts and Resilience4j around external calls
• Parameterized logging with correlation ID propagation
• No edits to existing Flyway migration files
• Tests added or updated for the changed behavior