339 lines
20 KiB
Plaintext
339 lines
20 KiB
Plaintext
---
|
|
description: This rule provides comprehensive best practices and coding standards for developing robust, maintainable, and performant Spring Boot applications, covering code structure, performance, security, testing, and common pitfalls.
|
|
globs: *.java
|
|
---
|
|
# Spring Boot Best Practices and Coding Standards
|
|
|
|
This document outlines best practices and coding standards for developing applications with Spring Boot. Following these guidelines will help ensure that your applications are robust, maintainable, performant, and secure.
|
|
|
|
## 1. Code Organization and Structure
|
|
|
|
### 1.1 Directory Structure
|
|
|
|
Adopt a layered architecture to separate concerns and improve maintainability. A recommended directory structure is:
|
|
|
|
|
|
src/
|
|
├── main/
|
|
│ ├── java/
|
|
│ │ └── com/example/app/
|
|
│ │ ├── Application.java (Main entry point)
|
|
│ │ ├── config/ (Configuration classes)
|
|
│ │ ├── controller/ (REST controllers)
|
|
│ │ ├── service/ (Business logic services)
|
|
│ │ ├── repository/ (Data access repositories)
|
|
│ │ ├── model/ (Data transfer objects (DTOs), entities)
|
|
│ │ ├── exception/ (Custom exceptions)
|
|
│ │ ├── util/ (Utility classes)
|
|
│ │ └── security/ (Security-related classes)
|
|
│ └── resources/
|
|
│ ├── application.properties/application.yml (Application configuration)
|
|
│ ├── static/ (Static resources like HTML, CSS, JavaScript)
|
|
│ └── templates/ (View templates, e.g., Thymeleaf)
|
|
└── test/
|
|
├── java/
|
|
│ └── com/example/app/
|
|
│ ├── controller/ (Controller tests)
|
|
│ ├── service/ (Service tests)
|
|
│ └── repository/ (Repository tests)
|
|
└── resources/
|
|
├── application.properties/application.yml (Test-specific configuration)
|
|
|
|
|
|
* **Root Package:** Choose a meaningful root package name (e.g., `com.yourcompany.appname`).
|
|
* **Modularization:** For larger applications, consider breaking down the application into modules (e.g., using Maven or Gradle modules) based on business domains or features.
|
|
|
|
### 1.2 File Naming Conventions
|
|
|
|
* **Classes:** Use PascalCase (e.g., `UserController`, `ProductService`).
|
|
* **Interfaces:** Use PascalCase, often prefixed with `I` (e.g., `ProductRepository`, `IOrderService`). Consider omitting the `I` prefix if it doesn't add value.
|
|
* **Methods:** Use camelCase (e.g., `getUserById`, `calculateTotal`).
|
|
* **Variables:** Use camelCase (e.g., `userName`, `productPrice`).
|
|
* **Constants:** Use UPPER_SNAKE_CASE (e.g., `MAX_RETRIES`, `DEFAULT_TIMEOUT`).
|
|
* **Configuration Files:** Use lowercase with hyphens (e.g., `application.properties`, `bootstrap.yml`).
|
|
|
|
### 1.3 Module Organization
|
|
|
|
For larger projects, break down the application into modules. Each module should represent a distinct business domain or feature.
|
|
|
|
* **Maven/Gradle Modules:** Use Maven or Gradle to manage module dependencies and build processes.
|
|
* **Clear Boundaries:** Define clear interfaces between modules to promote loose coupling.
|
|
* **Independent Deployments:** Design modules to be independently deployable, if possible.
|
|
|
|
### 1.4 Component Architecture
|
|
|
|
* **Controllers:** Handle incoming requests and delegate to services. Keep controllers thin.
|
|
* **Services:** Implement business logic. Services should be transactional.
|
|
* **Repositories:** Provide data access abstraction. Use Spring Data JPA or other data access technologies.
|
|
* **Models:** Represent data structures. Use DTOs for transferring data between layers and entities for persistence.
|
|
|
|
### 1.5 Code Splitting Strategies
|
|
|
|
* **Feature-Based Splitting:** Group code related to a specific feature into its own package or module.
|
|
* **Layer-Based Splitting:** Separate code based on layers (e.g., presentation, business logic, data access).
|
|
* **Horizontal vs. Vertical Slicing:** Consider horizontal slicing (grouping similar functionalities across features) or vertical slicing (grouping all functionalities for a specific feature) based on project needs.
|
|
|
|
## 2. Common Patterns and Anti-Patterns
|
|
|
|
### 2.1 Design Patterns Specific to Spring Boot
|
|
|
|
* **Dependency Injection (DI):** Use constructor injection for required dependencies and setter injection for optional dependencies.
|
|
* **Inversion of Control (IoC):** Let the Spring container manage the lifecycle and dependencies of your beans.
|
|
* **Aspect-Oriented Programming (AOP):** Use AOP for cross-cutting concerns like logging, security, and transaction management.
|
|
* **Repository Pattern:** Use Spring Data repositories for simplified data access.
|
|
* **Service Layer Pattern:** Decouple controllers from business logic by introducing a service layer.
|
|
* **Template Method Pattern:** Use `JdbcTemplate` or `RestTemplate` for consistent data access or external API calls.
|
|
* **Factory Pattern:** Use `@Configuration` classes and `@Bean` methods to define and configure beans.
|
|
|
|
### 2.2 Recommended Approaches for Common Tasks
|
|
|
|
* **Configuration:** Use `application.properties` or `application.yml` for externalized configuration. Use `@ConfigurationProperties` to bind configuration properties to a class.
|
|
* **Logging:** Use SLF4J for logging abstraction and a suitable logging implementation (e.g., Logback or Log4j2).
|
|
* **Exception Handling:** Use `@ControllerAdvice` to handle exceptions globally. Create custom exception classes for specific error scenarios.
|
|
* **Validation:** Use JSR-303 Bean Validation for validating request parameters and request bodies. Use `@Validated` annotation with appropriate groups.
|
|
* **Data Transfer:** Use DTOs to transfer data between layers to avoid exposing internal data structures.
|
|
* **Asynchronous Operations:** Use `@Async` annotation and `TaskExecutor` to perform asynchronous operations.
|
|
* **Caching:** Use Spring's caching abstraction with implementations like Ehcache, Caffeine, or Redis.
|
|
* **Scheduling:** Use `@Scheduled` annotation to schedule tasks.
|
|
* **Transaction Management:** Use `@Transactional` annotation for managing transactions.
|
|
|
|
### 2.3 Anti-Patterns and Code Smells to Avoid
|
|
|
|
* **God Class:** A class that does too much. Break it down into smaller, more focused classes.
|
|
* **Long Method:** A method that is too long and complex. Extract smaller methods.
|
|
* **Feature Envy:** A method that accesses data from another object more than its own. Move the method to the other object.
|
|
* **Data Clumps:** Groups of data that frequently appear together. Create a new class to encapsulate the data clump.
|
|
* **Primitive Obsession:** Using primitive data types instead of creating meaningful domain objects.
|
|
* **Shotgun Surgery:** Making small changes in many different places. Refactor the code to centralize the changes.
|
|
* **Spaghetti Code:** Code that is difficult to understand and maintain due to its tangled structure.
|
|
* **Copy-Paste Programming:** Duplicating code instead of reusing existing code. Create reusable components or methods.
|
|
* **Field Injection:** Use constructor injection instead for required dependencies.
|
|
* **Tight Coupling:** Classes that are highly dependent on each other. Decouple the classes using interfaces or abstract classes.
|
|
* **Ignoring Exceptions:** Catching exceptions but not handling them properly. Log the exception and take appropriate action.
|
|
* **Over-Engineering:** Making the code too complex for the problem it solves. Keep it simple and only add complexity when needed.
|
|
|
|
### 2.4 State Management Best Practices
|
|
|
|
* **Stateless Services:** Design services to be stateless whenever possible. This improves scalability and testability.
|
|
* **Session Management:** Use Spring Session to manage user sessions in a distributed environment. Store session data in a persistent store like Redis or a database.
|
|
* **Caching:** Use caching to store frequently accessed data. Choose a suitable caching strategy (e.g., LRU, FIFO).
|
|
* **Database:** Use a relational database or a NoSQL database to persist data.
|
|
* **Distributed Transactions:** Use distributed transaction management techniques like two-phase commit (2PC) or Saga pattern for transactions spanning multiple services.
|
|
|
|
### 2.5 Error Handling Patterns
|
|
|
|
* **Global Exception Handling:** Use `@ControllerAdvice` and `@ExceptionHandler` to handle exceptions globally.
|
|
* **Custom Exceptions:** Create custom exception classes for specific error scenarios.
|
|
* **Logging:** Log exceptions with sufficient context information (e.g., request parameters, user ID).
|
|
* **Error Responses:** Return meaningful error responses with appropriate HTTP status codes and error messages.
|
|
* **Retry Mechanism:** Implement a retry mechanism for transient errors.
|
|
* **Circuit Breaker:** Use a circuit breaker pattern to prevent cascading failures.
|
|
* **Dead Letter Queue:** Use a dead letter queue to handle messages that cannot be processed.
|
|
|
|
## 3. Performance Considerations
|
|
|
|
### 3.1 Optimization Techniques
|
|
|
|
* **Database Query Optimization:** Use indexes, optimize queries, and avoid N+1 queries.
|
|
* **Caching:** Use caching to reduce database load and improve response times.
|
|
* **Connection Pooling:** Use connection pooling to reuse database connections.
|
|
* **Asynchronous Operations:** Use asynchronous operations to offload long-running tasks from the main thread.
|
|
* **Load Balancing:** Use load balancing to distribute traffic across multiple instances.
|
|
* **Gzip Compression:** Use Gzip compression to reduce the size of HTTP responses.
|
|
* **Code Profiling:** Use profiling tools to identify performance bottlenecks.
|
|
|
|
### 3.2 Memory Management
|
|
|
|
* **Object Pooling:** Use object pooling to reuse objects and reduce object creation overhead.
|
|
* **Avoid Memory Leaks:** Ensure that objects are properly garbage collected.
|
|
* **Use Appropriate Data Structures:** Choose data structures that are efficient for the operations you perform.
|
|
* **Optimize Collections:** Use appropriate collection types (e.g., `ArrayList` vs. `LinkedList`) based on usage patterns.
|
|
* **Lazy Loading:** Use lazy loading to load data only when it is needed.
|
|
|
|
### 3.3 Rendering Optimization
|
|
|
|
* **Template Caching:** Cache frequently used templates to reduce rendering time.
|
|
* **Minimize DOM Manipulations:** Minimize DOM manipulations in the view layer.
|
|
* **Use CDN:** Use a Content Delivery Network (CDN) to serve static resources.
|
|
|
|
### 3.4 Bundle Size Optimization
|
|
|
|
* **Code Splitting:** Split the code into smaller bundles to reduce the initial load time.
|
|
* **Tree Shaking:** Remove unused code from the bundles.
|
|
* **Minification:** Minify the code to reduce the bundle size.
|
|
* **Compression:** Compress the bundles to reduce the transfer size.
|
|
|
|
### 3.5 Lazy Loading Strategies
|
|
|
|
* **Lazy Initialization:** Initialize objects only when they are first accessed.
|
|
* **Virtual Proxy:** Use a virtual proxy to delay the loading of an object until it is needed.
|
|
* **Database Lazy Loading:** Use lazy loading features provided by JPA or other data access technologies.
|
|
|
|
## 4. Security Best Practices
|
|
|
|
### 4.1 Common Vulnerabilities and How to Prevent Them
|
|
|
|
* **SQL Injection:** Use parameterized queries or ORM frameworks to prevent SQL injection attacks.
|
|
* **Cross-Site Scripting (XSS):** Sanitize user input and use output encoding to prevent XSS attacks.
|
|
* **Cross-Site Request Forgery (CSRF):** Use CSRF tokens to prevent CSRF attacks.
|
|
* **Authentication and Authorization:** Implement strong authentication and authorization mechanisms.
|
|
* **Session Management:** Secure session management to prevent session hijacking.
|
|
* **Denial of Service (DoS):** Implement rate limiting and other measures to prevent DoS attacks.
|
|
* **Insecure Direct Object References (IDOR):** Implement access control checks to prevent unauthorized access to objects.
|
|
* **Security Misconfiguration:** Properly configure security settings to prevent misconfigurations.
|
|
* **Using Components with Known Vulnerabilities:** Keep dependencies up-to-date to address known vulnerabilities.
|
|
* **Insufficient Logging and Monitoring:** Implement sufficient logging and monitoring to detect and respond to security incidents.
|
|
|
|
### 4.2 Input Validation
|
|
|
|
* **Whitelisting:** Validate input against a whitelist of allowed values.
|
|
* **Regular Expressions:** Use regular expressions to validate input format.
|
|
* **Data Type Validation:** Validate that input is of the expected data type.
|
|
* **Length Validation:** Validate that input is within the allowed length limits.
|
|
* **Encoding Validation:** Validate that input is properly encoded.
|
|
|
|
### 4.3 Authentication and Authorization Patterns
|
|
|
|
* **OAuth 2.0:** Use OAuth 2.0 for delegated authorization.
|
|
* **JWT (JSON Web Token):** Use JWT for stateless authentication.
|
|
* **Role-Based Access Control (RBAC):** Implement RBAC to control access to resources based on user roles.
|
|
* **Attribute-Based Access Control (ABAC):** Implement ABAC for fine-grained access control based on attributes.
|
|
* **Spring Security:** Leverage Spring Security for authentication and authorization.
|
|
|
|
### 4.4 Data Protection Strategies
|
|
|
|
* **Encryption:** Encrypt sensitive data at rest and in transit.
|
|
* **Hashing:** Hash passwords and other sensitive data using strong hashing algorithms.
|
|
* **Salting:** Use salting to protect against rainbow table attacks.
|
|
* **Data Masking:** Mask sensitive data when it is displayed or used for non-production purposes.
|
|
* **Tokenization:** Tokenize sensitive data to replace it with non-sensitive tokens.
|
|
|
|
### 4.5 Secure API Communication
|
|
|
|
* **HTTPS:** Use HTTPS for secure communication.
|
|
* **TLS/SSL:** Use TLS/SSL to encrypt data in transit.
|
|
* **API Keys:** Use API keys to authenticate API clients.
|
|
* **Rate Limiting:** Implement rate limiting to prevent abuse.
|
|
* **Input Validation:** Validate all input to prevent injection attacks.
|
|
* **Output Encoding:** Encode output to prevent XSS attacks.
|
|
|
|
## 5. Testing Approaches
|
|
|
|
### 5.1 Unit Testing Strategies
|
|
|
|
* **Test-Driven Development (TDD):** Write tests before writing the code.
|
|
* **Mocking:** Use mocking frameworks (e.g., Mockito) to isolate the unit under test.
|
|
* **Assertion Libraries:** Use assertion libraries (e.g., AssertJ) for expressive assertions.
|
|
* **Code Coverage:** Aim for high code coverage.
|
|
* **Test Naming:** Use clear and descriptive test names.
|
|
* **Arrange-Act-Assert:** Structure tests using the Arrange-Act-Assert pattern.
|
|
|
|
### 5.2 Integration Testing
|
|
|
|
* **Test Slices:** Use Spring Boot's test slices (e.g., `@WebMvcTest`, `@DataJpaTest`) to test specific parts of the application.
|
|
* **TestContainers:** Use Testcontainers to run integration tests with real dependencies (e.g., databases, message queues).
|
|
* **Spring Test:** Use Spring's testing support for integration tests.
|
|
* **Database Testing:** Use an in-memory database or a test database for database integration tests.
|
|
|
|
### 5.3 End-to-End Testing
|
|
|
|
* **Selenium:** Use Selenium to automate browser-based end-to-end tests.
|
|
* **REST Assured:** Use REST Assured to test REST APIs.
|
|
* **Headless Browser:** Use a headless browser for faster end-to-end tests.
|
|
|
|
### 5.4 Test Organization
|
|
|
|
* **Test Packages:** Create separate packages for unit tests, integration tests, and end-to-end tests.
|
|
* **Test Classes:** Create test classes that correspond to the classes under test.
|
|
* **Test Suites:** Use test suites to group related tests.
|
|
|
|
### 5.5 Mocking and Stubbing
|
|
|
|
* **Mockito:** Use Mockito for mocking dependencies.
|
|
* **Spring MockMvc:** Use Spring MockMvc for testing controllers.
|
|
* **WireMock:** Use WireMock for stubbing external services.
|
|
* **Avoid Over-Mocking:** Mock only the dependencies that are necessary to isolate the unit under test.
|
|
|
|
## 6. Common Pitfalls and Gotchas
|
|
|
|
### 6.1 Frequent Mistakes Developers Make
|
|
|
|
* **Not Understanding Spring Boot Concepts:** Jumping into Spring Boot without a solid understanding of Spring and Dependency Injection.
|
|
* **Overusing `@Autowired`:** Using `@Autowired` for field injection instead of constructor injection.
|
|
* **Not Using Spring Boot Starters:** Manually adding dependencies instead of using Spring Boot Starters.
|
|
* **Not Externalizing Configuration:** Hardcoding configuration values instead of using `application.properties` or `application.yml`.
|
|
* **Not Handling Exceptions Properly:** Ignoring exceptions or not providing meaningful error responses.
|
|
* **Not Writing Tests:** Neglecting to write unit tests and integration tests.
|
|
* **Using `System.out.println` for Logging:** Using `System.out.println` instead of a proper logging framework.
|
|
* **Not Securing the Application:** Failing to implement proper security measures.
|
|
* **Not Monitoring the Application:** Not setting up proper monitoring and alerting.
|
|
|
|
### 6.2 Edge Cases to Be Aware Of
|
|
|
|
* **Null Values:** Handle null values gracefully.
|
|
* **Empty Collections:** Handle empty collections properly.
|
|
* **Large Datasets:** Optimize performance for large datasets.
|
|
* **Concurrency Issues:** Handle concurrency issues properly.
|
|
* **Network Errors:** Handle network errors gracefully.
|
|
|
|
### 6.3 Version-Specific Issues
|
|
|
|
* **Spring Boot Version Compatibility:** Ensure that dependencies are compatible with the Spring Boot version.
|
|
* **Java Version Compatibility:** Ensure that the Java version is compatible with the Spring Boot version.
|
|
* **Third-Party Library Compatibility:** Ensure that third-party libraries are compatible with the Spring Boot version.
|
|
|
|
### 6.4 Compatibility Concerns
|
|
|
|
* **Browser Compatibility:** Ensure that the application is compatible with different browsers.
|
|
* **Operating System Compatibility:** Ensure that the application is compatible with different operating systems.
|
|
* **Device Compatibility:** Ensure that the application is compatible with different devices.
|
|
|
|
### 6.5 Debugging Strategies
|
|
|
|
* **Logging:** Use logging to trace the execution flow and identify errors.
|
|
* **Debuggers:** Use debuggers to step through the code and inspect variables.
|
|
* **Profiling Tools:** Use profiling tools to identify performance bottlenecks.
|
|
* **Remote Debugging:** Use remote debugging to debug applications running on remote servers.
|
|
* **Heap Dumps:** Use heap dumps to analyze memory usage.
|
|
* **Thread Dumps:** Use thread dumps to analyze thread activity.
|
|
|
|
## 7. Tooling and Environment
|
|
|
|
### 7.1 Recommended Development Tools
|
|
|
|
* **IDE:** IntelliJ IDEA, Eclipse, or Visual Studio Code.
|
|
* **Build Tool:** Maven or Gradle.
|
|
* **Version Control:** Git.
|
|
* **Database Client:** DBeaver or SQL Developer.
|
|
* **API Testing Tool:** Postman or Insomnia.
|
|
|
|
### 7.2 Build Configuration
|
|
|
|
* **Maven:** Use `pom.xml` to define dependencies and build configuration.
|
|
* **Gradle:** Use `build.gradle` to define dependencies and build configuration.
|
|
* **Spring Boot Maven Plugin:** Use the Spring Boot Maven Plugin for packaging and running the application.
|
|
* **Spring Boot Gradle Plugin:** Use the Spring Boot Gradle Plugin for packaging and running the application.
|
|
|
|
### 7.3 Linting and Formatting
|
|
|
|
* **Checkstyle:** Use Checkstyle to enforce coding style guidelines.
|
|
* **PMD:** Use PMD to find potential code defects.
|
|
* **FindBugs/SpotBugs:** Use FindBugs/SpotBugs to find potential bugs.
|
|
* **EditorConfig:** Use EditorConfig to maintain consistent coding styles across different editors.
|
|
* **IntelliJ IDEA Code Style:** Configure IntelliJ IDEA's code style settings to match the project's coding style.
|
|
|
|
### 7.4 Deployment Best Practices
|
|
|
|
* **Containerization:** Use Docker to containerize the application.
|
|
* **Orchestration:** Use Kubernetes or Docker Swarm to orchestrate containers.
|
|
* **Cloud Deployment:** Deploy the application to a cloud platform (e.g., AWS, Azure, Google Cloud).
|
|
* **Configuration Management:** Use configuration management tools (e.g., Spring Cloud Config) to manage configuration in a distributed environment.
|
|
* **Monitoring:** Set up monitoring to track application performance and health.
|
|
* **Logging:** Aggregate logs to a central location for analysis.
|
|
|
|
### 7.5 CI/CD Integration
|
|
|
|
* **Continuous Integration (CI):** Use a CI server (e.g., Jenkins, Travis CI, CircleCI) to automatically build and test the application.
|
|
* **Continuous Delivery (CD):** Use a CD pipeline to automatically deploy the application to production.
|
|
* **Automated Testing:** Automate unit tests, integration tests, and end-to-end tests.
|
|
* **Code Quality Checks:** Integrate code quality checks (e.g., Checkstyle, PMD, FindBugs/SpotBugs) into the CI pipeline. |