|
| 1 | +--- |
| 2 | +applyTo: '*' |
| 3 | +description: 'Quarkus development standards and instructions' |
| 4 | +--- |
| 5 | + |
| 6 | +- Instructions for high-quality Quarkus applications with Java 17 or later. |
| 7 | + |
| 8 | +## Project Context |
| 9 | + |
| 10 | +- Latest Quarkus version: 3.x |
| 11 | +- Java version: 17 or later |
| 12 | +- Use Maven or Gradle for build management. |
| 13 | +- Focus on clean architecture, maintainability, and performance. |
| 14 | + |
| 15 | +## Development Standards |
| 16 | + |
| 17 | + - Write clear and concise comments for each class, method, and complex logic. |
| 18 | + - Use Javadoc for public APIs and methods to ensure clarity for consumers. |
| 19 | + - Maintain a consistent coding style across the project, adhering to Java conventions. |
| 20 | + - Adhere to the Quarkus coding standards and best practices for optimal performance and maintainability. |
| 21 | + - Follow Jarkarta EE and MicroProfile conventions, ensuring clarity in package organization. |
| 22 | + - Use Java 17 or later features where appropriate, such as records and sealed classes. |
| 23 | + |
| 24 | + |
| 25 | +## Naming Conventions |
| 26 | + - Use PascalCase for class names (e.g., `ProductService`, `ProductResource`). |
| 27 | + - Use camelCase for method and variable names (e.g., `findProductById`, `isProductAvailable`). |
| 28 | + - Use ALL_CAPS for constants (e.g., `DEFAULT_PAGE_SIZE`). |
| 29 | + |
| 30 | +## Quarkus |
| 31 | + - Leverage Quarkus Dev Mode for faster development cycles. |
| 32 | + - Implement build-time optimizations using Quarkus extensions and best practices. |
| 33 | + - Configure native builds with GraalVM for optimal performance (e.g., use the quarkus-maven-plugin). |
| 34 | + - Use quarkus logging capabilities (JBoss, SL4J or JUL) for consistent logging practices. |
| 35 | + |
| 36 | +### Quarkus-Specific Patterns |
| 37 | +- Use `@ApplicationScoped` for singleton beans instead of `@Singleton` |
| 38 | +- Use `@Inject` for dependency injection |
| 39 | +- Prefer Panache repositories over traditional JPA repositories |
| 40 | +- Use `@Transactional` on service methods that modify data |
| 41 | +- Apply `@Path` with descriptive REST endpoint paths |
| 42 | +- Use `@Consumes(MediaType.APPLICATION_JSON)` and `@Produces(MediaType.APPLICATION_JSON)` for REST resources |
| 43 | + |
| 44 | +### REST Resources |
| 45 | +- Always use JAX-RS annotations (`@Path`, `@GET`, `@POST`, etc.) |
| 46 | +- Return proper HTTP status codes (200, 201, 400, 404, 500) |
| 47 | +- Use `Response` class for complex responses |
| 48 | +- Include proper error handling with try-catch blocks |
| 49 | +- Validate input parameters using Bean Validation annotations |
| 50 | +- Implement rate limiting for public endpoints |
| 51 | + |
| 52 | +### Data Access |
| 53 | +- Prefer Panache entities (extend `PanacheEntity`) over traditional JPA |
| 54 | +- Use Panache repositories (`PanacheRepository<T>`) for complex queries |
| 55 | +- Always use `@Transactional` for data modifications |
| 56 | +- Use named queries for complex database operations |
| 57 | +- Implement proper pagination for list endpoints |
| 58 | + |
| 59 | + |
| 60 | +### Configuration |
| 61 | +- Use `application.properties` or `application.yaml` for simple configuration |
| 62 | +- Use `@ConfigProperty` for type-safe configuration classes |
| 63 | +- Prefer environment variables for sensitive data |
| 64 | +- Use profiles for different environments (dev, test, prod) |
| 65 | + |
| 66 | + |
| 67 | +### Testing |
| 68 | +- Use `@QuarkusTest` for integration tests |
| 69 | +- Use JUnit 5 for unit tests |
| 70 | +- Use `@QuarkusIntegrationTest` for native build tests |
| 71 | +- Mock external dependencies using `@QuarkusTestResource` |
| 72 | +- Use RestAssured for REST endpoint testing (`@QuarkusTestResource`) |
| 73 | +- Use `@Transactional` for tests that modify the database |
| 74 | +- Use test-containers for database integration tests |
| 75 | + |
| 76 | +### Don't use these patterns: |
| 77 | +- Don't use field injection in tests (use constructor injection) |
| 78 | +- Don't hardcode configuration values |
| 79 | +- Don't ignore exceptions |
| 80 | + |
| 81 | + |
| 82 | +## Development Workflow |
| 83 | + |
| 84 | +### When creating new features: |
| 85 | +1. Create entity with proper validation |
| 86 | +2. Create repository with custom queries |
| 87 | +3. Create service with business logic |
| 88 | +4. Create REST resource with proper endpoints |
| 89 | +5. Write comprehensive tests |
| 90 | +6. Add proper error handling |
| 91 | +7. Update documentation |
| 92 | + |
| 93 | +## Security Considerations |
| 94 | + |
| 95 | +### When implementing security: |
| 96 | +- Use Quarkus Security extensions (e.g., `quarkus-smallrye-jwt`, `quarkus-oidc`). |
| 97 | +- Implement role-based access control (RBAC) using MicroProfile JWT or OIDC. |
| 98 | +- Validate all input parameters |
0 commit comments