---
name: java-quarkus-development
description: Java Quarkus development guidelines for building cloud-native applications with fast startup, minimal memory footprint, and GraalVM native builds
---

# Java Quarkus Development Best Practices

## Core Principles

- Write clean, efficient, and well-documented Java code using Quarkus best practices
- Focus on fast startup and minimal memory footprint via GraalVM native builds
- Leverage Quarkus extensions for common functionality
- Design for containerized and serverless deployments
- Follow SOLID principles and microservices architecture patterns

## Development Workflow

### Quarkus Dev Mode
- Use `quarkus dev` for rapid iteration with live reload
- Leverage continuous testing during development
- Use Dev UI for debugging and configuration inspection
- Take advantage of Dev Services for local development

## Configuration

### Type-Safe Configuration
- Use `@ConfigProperty` for type-safe configuration injection
- Group related configs with `@ConfigMapping` interfaces
- Validate configuration at startup
- Document configuration properties

### Profile-Based Configuration
- Use `%dev`, `%test`, `%prod` prefixes for environment-specific configs
- Override configs via environment variables in production
- Keep sensitive values out of source control
- Use `.env` files for local development

## Dependency Injection

### CDI Annotations
- Use `@Inject` for dependency injection
- Use `@Named` to qualify implementations
- Use `@Singleton`, `@ApplicationScoped`, `@RequestScoped` appropriately
- Prefer constructor injection for required dependencies

### Bean Discovery
- Understand Quarkus build-time bean discovery
- Use `@IfBuildProfile` for conditional beans
- Avoid reflection-heavy patterns for native builds

## REST API Development

### RESTEasy Reactive
- Use `@Path`, `@GET`, `@POST`, etc. for endpoint definitions
- Return proper HTTP status codes
- Use `@Valid` for input validation
- Implement exception mappers for consistent error responses

### Reactive Patterns
- Use Mutiny for reactive programming
- Leverage `Uni` and `Multi` for async operations
- Combine reactive with imperative code where appropriate

## Data Access

### Hibernate ORM with Panache
- Use Panache for simplified JPA patterns
- Leverage Active Record or Repository patterns
- Use `PanacheEntity` for entities with built-in operations
- Implement custom queries with `find` and `list` methods

### Database Operations
- Use Flyway or Liquibase for migrations
- Configure connection pooling with Agroal
- Use reactive database clients for non-blocking I/O

## Testing

### JUnit 5 Integration
- Use `@QuarkusTest` for integration tests
- Use `@QuarkusIntegrationTest` for native image tests
- Leverage test profiles for different configurations

### REST Endpoint Testing
- Use rest-assured for endpoint testing
- Test both success and error scenarios
- Verify response bodies and status codes
- Test authentication and authorization

## Performance Optimization

### Native Image Optimization
- Build native images with GraalVM for production
- Test native builds regularly during development
- Use `@RegisterForReflection` when needed
- Minimize reflection usage

### Memory and Startup
- Monitor memory usage in containers
- Optimize for serverless cold starts
- Use lazy initialization where appropriate

## Observability

### Health Checks
- Use MicroProfile Health for liveness and readiness probes
- Implement custom health checks for dependencies
- Configure Kubernetes probes based on health endpoints

### Metrics
- Use MicroProfile Metrics for application metrics
- Export metrics in Prometheus format
- Add custom metrics for business operations

### Distributed Tracing
- Use OpenTracing/OpenTelemetry integration
- Propagate trace context across services
- Configure sampling appropriately for production

## Security

- Use Quarkus Security extensions
- Implement authentication with OIDC or JWT
- Configure CORS for web clients
- Validate and sanitize all inputs
- Use HTTPS in production

## Containerization

- Use Quarkus container image extensions
- Build multi-stage Dockerfiles for native images
- Configure resource limits appropriately
- Use distroless or minimal base images