new java and springboot base best practices

instructions/java.instructions.md

@@ -0,0 +1,64 @@
+---
+description: 'Guidelines for building Java base applications'
+applyTo: '**/*.java'
+---
+
+# Java Development
+
+## General Instructions
+
+- First, prompt the user if they want to integrate static analysis tools (SonarQube, PMD, Checkstyle)
+  into their project setup. If yes, provide guidance on tool selection and configuration.
+- If the user declines static analysis tools or wants to proceed without them, continue with implementing the Best practices, bug patterns and code smell prevention guidelines outlined below.
+- Address code smells proactively during development rather than accumulating technical debt.
+- Focus on readability, maintainability, and performance when refactoring identified issues.
+- Use IDE / Code editor reported warnings and suggestions to catch common patterns early in development.
+
+## Best practices
+
+- **Records**: For classes primarily intended to store data (e.g., DTOs, immutable data structures), **Java Records should be used instead of traditional classes**.
+- **Pattern Matching**: Utilize pattern matching for `instanceof` and `switch` expression to simplify conditional logic and type casting.
+- **Type Inference**: Use `var` for local variable declarations to improve readability, but only when the type is explicitly clear from the right-hand side of the expression.
+- **Immutability**: Favor immutable objects. Make classes and fields `final` where possible. Use collections from `List.of()`/`Map.of()` for fixed data. Use `Stream.toList()` to create immutable lists.
+- **Streams and Lambdas**: Use the Streams API and lambda expressions for collection processing. Employ method references (e.g., `stream.map(Foo::toBar)`).
+- **Null Handling**: Avoid returning or accepting `null`. Use `Optional<T>` for possibly-absent values and `Objects` utility methods like `equals()` and `requireNonNull()`.
+
+### Naming Conventions
+
+- Follow Google's Java style guide:
+  - `UpperCamelCase` for class and interface names.
+  - `lowerCamelCase` for method and variable names.
+  - `UPPER_SNAKE_CASE` for constants.
+  - `lowercase` for package names.
+- Use nouns for classes (`UserService`) and verbs for methods (`getUserById`).
+- Avoid abbreviations and Hungarian notation.
+
+### Bug Patterns
+
+| Rule ID | Description                                                 | Example / Notes                                                                                  |
+| ------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `S2095` | Resources should be closed                                  | Use try-with-resources when working with streams, files, sockets, etc.                           |
+| `S1698` | Objects should be compared with `.equals()` instead of `==` | Especially important for Strings and boxed primitives.                                           |
+| `S1905` | Redundant casts should be removed                           | Clean up unnecessary or unsafe casts.                                                            |
+| `S3518` | Conditions should not always evaluate to true or false      | Watch for infinite loops or if-conditions that never change.                                     |
+| `S108`  | Unreachable code should be removed                          | Code after `return`, `throw`, etc., must be cleaned up.                                          |
+
+## Code Smells
+
+| Rule ID | Description                                            | Example / Notes                                                               |
+| ------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| `S107`  | Methods should not have too many parameters            | Refactor into helper classes or use builder pattern.                          |
+| `S121`  | Duplicated blocks of code should be removed            | Consolidate logic into shared methods.                                        |
+| `S138`  | Methods should not be too long                         | Break complex logic into smaller, testable units.                             |
+| `S3776` | Cognitive complexity should be reduced                 | Simplify nested logic, extract methods, avoid deep `if` trees.                |
+| `S1192` | String literals should not be duplicated               | Replace with constants or enums.                                              |
+| `S1854` | Unused assignments should be removed                   | Avoid dead variables—remove or refactor.                                      |
+| `S109`  | Magic numbers should be replaced with constants        | Improves readability and maintainability.                                     |
+| `S1188` | Catch blocks should not be empty                       | Always log or handle exceptions meaningfully.                                 |
+
+## Build and Verification
+
+- After adding or modifying code, verify the project continues to build successfully.
+- If the project uses Maven, run `mvn clean install`.
+- If the project uses Gradle, run `./gradlew build` (or `gradlew.bat build` on Windows).
+- Ensure all tests pass as part of the build.

instructions/springboot.instructions.md

@@ -0,0 +1,58 @@
+---
+description: 'Guidelines for building Spring Boot base applications'
+applyTo: '**/*.java, **/*.kt'
+---
+
+# Spring Boot Development
+
+## General Instructions
+
+- Make only high confidence suggestions when reviewing code changes.
+- Write code with good maintainability practices, including comments on why certain design decisions were made.
+- Handle edge cases and write clear exception handling.
+- For libraries or external dependencies, mention their usage and purpose in comments.
+
+## Spring Boot Instructions
+
+### Dependency Injection
+
+- Use constructor injection for all required dependencies.
+- Declare dependency fields as `private final`.
+
+### Configuration
+
+- Use YAML files (`application.yml`) for externalized configuration.
+- Environment Profiles: Use Spring profiles for different environments (dev, test, prod)
+- Configuration Properties: Use @ConfigurationProperties for type-safe configuration binding
+- Secrets Management: Externalize secrets using environment variables or secret management systems
+
+### Code Organization
+
+- Package Structure: Organize by feature/domain rather than by layer
+- Separation of Concerns: Keep controllers thin, services focused, and repositories simple
+- Utility Classes: Make utility classes final with private constructors
+
+### Service Layer
+
+- Place business logic in `@Service`-annotated classes.
+- Services should be stateless and testable.
+- Inject repositories via the constructor.
+- Service method signatures should use domain IDs or DTOs, not expose repository entities directly unless necessary.
+
+### Logging
+
+- Use SLF4J for all logging (`private static final Logger logger = LoggerFactory.getLogger(MyClass.class);`).
+- Do not use concrete implementations (Logback, Log4j2) or `System.out.println()` directly.
+- Use parameterized logging: `logger.info("User {} logged in", userId);`.
+
+### Security & Input Handling
+
+- Use parameterized queries | Always use Spring Data JPA or `NamedParameterJdbcTemplate` to prevent SQL injection.
+- Validate request bodies and parameters using JSR-380 (`@NotNull`, `@Size`, etc.) annotations and `BindingResult`
+
+## Build and Verification
+
+- After adding or modifying code, verify the project continues to build successfully.
+- If the project uses Maven, run `mvn clean install`.
+- If the project uses Gradle, run `./gradlew build` (or `gradlew.bat build` on Windows).
+- Ensure all tests pass as part of the build.

prompts/java-docs.prompt.md

@@ -0,0 +1,24 @@
+---
+mode: 'agent'
+tools: ['changes', 'codebase', 'editFiles', 'problems']
+description: 'Ensure that Java types are documented with Javadoc comments and follow best practices for documentation.'
+---
+
+# Java Documentation (Javadoc) Best Practices
+
+- Public and protected members should be documented with Javadoc comments.
+- It is encouraged to document package-private and private members as well, especially if they are complex or not self-explanatory.
+- The first sentence of the Javadoc comment is the summary description. It should be a concise overview of what the method does and end with a period.
+- Use `@param` for method parameters. The description starts with a lowercase letter and does not end with a period.
+- Use `@return` for method return values.
+- Use `@throws` or `@exception` to document exceptions thrown by methods.
+- Use `@see` for references to other types or members.
+- Use `{@inheritDoc}` to inherit documentation from base classes or interfaces.
+  - Unless there is major behavior change, in which case you should document the differences.
+- Use `@param <T>` for type parameters in generic types or methods.
+- Use `{@code}` for inline code snippets.
+- Use `<pre>{@code ... }</pre>` for code blocks.
+- Use `@since` to indicate when the feature was introduced (e.g., version number).
+- Use `@version` to specify the version of the member.
+- Use `@author` to specify the author of the code.
+- Use `@deprecated` to mark a member as deprecated and provide an alternative.

prompts/java-junit.prompt.md

@@ -0,0 +1,64 @@
+---
+mode: 'agent'
+tools: ['changes', 'codebase', 'editFiles', 'problems', 'search']
+description: 'Get best practices for JUnit 5 unit testing, including data-driven tests'
+---
+
+# JUnit 5+ Best Practices
+
+Your goal is to help me write effective unit tests with JUnit 5, covering both standard and data-driven testing approaches.
+
+## Project Setup
+
+- Use a standard Maven or Gradle project structure.
+- Place test source code in `src/test/java`.
+- Include dependencies for `junit-jupiter-api`, `junit-jupiter-engine`, and `junit-jupiter-params` for parameterized tests.
+- Use build tool commands to run tests: `mvn test` or `gradle test`.
+
+## Test Structure
+
+- Test classes should have a `Test` suffix, e.g., `CalculatorTests` for a `Calculator` class.
+- Use `@Test` for test methods.
+- Follow the Arrange-Act-Assert (AAA) pattern.
+- Name tests using a descriptive convention, like `methodName_should_expectedBehavior_when_scenario`.
+- Use `@BeforeEach` and `@AfterEach` for per-test setup and teardown.
+- Use `@BeforeAll` and `@AfterAll` for per-class setup and teardown (must be static methods).
+- Use `@DisplayName` to provide a human-readable name for test classes and methods.
+
+## Standard Tests
+
+- Keep tests focused on a single behavior.
+- Avoid testing multiple conditions in one test method.
+- Make tests independent and idempotent (can run in any order).
+- Avoid test interdependencies.
+
+## Data-Driven (Parameterized) Tests
+
+- Use `@ParameterizedTest` to mark a method as a parameterized test.
+- Use `@ValueSource` for simple literal values (strings, ints, etc.).
+- Use `@MethodSource` to refer to a factory method that provides test arguments as a `Stream`, `Collection`, etc.
+- Use `@CsvSource` for inline comma-separated values.
+- Use `@CsvFileSource` to use a CSV file from the classpath.
+- Use `@EnumSource` to use enum constants.
+
+## Assertions
+
+- Use the static methods from `org.junit.jupiter.api.Assertions` (e.g., `assertEquals`, `assertTrue`, `assertNotNull`).
+- For more fluent and readable assertions, consider using a library like AssertJ (`assertThat(...).is...`).
+- Use `assertThrows` or `assertDoesNotThrow` to test for exceptions.
+- Group related assertions with `assertAll` to ensure all assertions are checked before the test fails.
+- Use descriptive messages in assertions to provide clarity on failure.
+
+## Mocking and Isolation
+
+- Use a mocking framework like Mockito to create mock objects for dependencies.
+- Use `@Mock` and `@InjectMocks` annotations from Mockito to simplify mock creation and injection.
+- Use interfaces to facilitate mocking.
+
+## Test Organization
+
+- Group tests by feature or component using packages.
+- Use `@Tag` to categorize tests (e.g., `@Tag("fast")`, `@Tag("integration")`).
+- Use `@TestMethodOrder(MethodOrderer.OrderAnnotation.class)` and `@Order` to control test execution order when strictly necessary.
+- Use `@Disabled` to temporarily skip a test method or class, providing a reason.
+- Use `@Nested` to group tests in a nested inner class for better organization and structure.

prompts/java-springboot.prompt.md

@@ -0,0 +1,66 @@
+---
+mode: 'agent'
+tools: ['changes', 'codebase', 'editFiles', 'problems', 'search']
+description: 'Get best practices for developing applications with Spring Boot.'
+---
+
+# Spring Boot Best Practices
+
+Your goal is to help me write high-quality Spring Boot applications by following established best practices.
+
+## Project Setup & Structure
+
+- **Build Tool:** Use Maven (`pom.xml`) or Gradle (`build.gradle`) for dependency management.
+- **Starters:** Use Spring Boot starters (e.g., `spring-boot-starter-web`, `spring-boot-starter-data-jpa`) to simplify dependency management.
+- **Package Structure:** Organize code by feature/domain (e.g., `com.example.app.order`, `com.example.app.user`) rather than by layer (e.g., `com.example.app.controller`, `com.example.app.service`).
+
+## Dependency Injection & Components
+
+- **Constructor Injection:** Always use constructor-based injection for required dependencies. This makes components easier to test and dependencies explicit.
+- **Immutability:** Declare dependency fields as `private final`.
+- **Component Stereotypes:** Use `@Component`, `@Service`, `@Repository`, and `@Controller`/`@RestController` annotations appropriately to define beans.
+
+## Configuration
+
+- **Externalized Configuration:** Use `application.yml` (or `application.properties`) for configuration. YAML is often preferred for its readability and hierarchical structure.
+- **Type-Safe Properties:** Use `@ConfigurationProperties` to bind configuration to strongly-typed Java objects.
+- **Profiles:** Use Spring Profiles (`application-dev.yml`, `application-prod.yml`) to manage environment-specific configurations.
+- **Secrets Management:** Do not hardcode secrets. Use environment variables, or a dedicated secret management tool like HashiCorp Vault or AWS Secrets Manager.
+
+## Web Layer (Controllers)
+
+- **RESTful APIs:** Design clear and consistent RESTful endpoints.
+- **DTOs (Data Transfer Objects):** Use DTOs to expose and consume data in the API layer. Do not expose JPA entities directly to the client.
+- **Validation:** Use Java Bean Validation (JSR 380) with annotations (`@Valid`, `@NotNull`, `@Size`) on DTOs to validate request payloads.
+- **Error Handling:** Implement a global exception handler using `@ControllerAdvice` and `@ExceptionHandler` to provide consistent error responses.
+
+## Service Layer
+
+- **Business Logic:** Encapsulate all business logic within `@Service` classes.
+- **Statelessness:** Services should be stateless.
+- **Transaction Management:** Use `@Transactional` on service methods to manage database transactions declaratively. Apply it at the most granular level necessary.
+
+## Data Layer (Repositories)
+
+- **Spring Data JPA:** Use Spring Data JPA repositories by extending `JpaRepository` or `CrudRepository` for standard database operations.
+- **Custom Queries:** For complex queries, use `@Query` or the JPA Criteria API.
+- **Projections:** Use DTO projections to fetch only the necessary data from the database.
+
+## Logging
+
+- **SLF4J:** Use the SLF4J API for logging.
+- **Logger Declaration:** `private static final Logger logger = LoggerFactory.getLogger(MyClass.class);`
+- **Parameterized Logging:** Use parameterized messages (`logger.info("Processing user {}...", userId);`) instead of string concatenation to improve performance.
+
+## Testing
+
+- **Unit Tests:** Write unit tests for services and components using JUnit 5 and a mocking framework like Mockito.
+- **Integration Tests:** Use `@SpringBootTest` for integration tests that load the Spring application context.
+- **Test Slices:** Use test slice annotations like `@WebMvcTest` (for controllers) or `@DataJpaTest` (for repositories) to test specific parts of the application in isolation.
+- **Testcontainers:** Consider using Testcontainers for reliable integration tests with real databases, message brokers, etc.
+
+## Security
+
+- **Spring Security:** Use Spring Security for authentication and authorization.
+- **Password Encoding:** Always encode passwords using a strong hashing algorithm like BCrypt.
+- **Input Sanitization:** Prevent SQL injection by using Spring Data JPA or parameterized queries. Prevent Cross-Site Scripting (XSS) by properly encoding output.