quarkus

• Apply these instructions only when the project uses Quarkus (io.quarkus dependencies or the Quarkus Maven/Gradle plugin).
• Check the project’s existing Quarkus and Java versions (pom.xml, build.gradle, quarkus.platform.version) before suggesting changes; keep them unless asked to upgrade. For new projects target the recommended stream from https://code.quarkus.io/api/streams (3.40 at the time of testing; 4.0 is still beta) and Java 21+ (Java 17 minimum). Never hard-code a patch version in advice; use the Quarkus BOM.

Dependencies and build

• Add features through Quarkus extensions (./mvnw quarkus:add-extension -Dextensions=... or quarkus extension add), versions managed by the platform BOM.
• Use Quarkus REST (quarkus-rest, quarkus-rest-jackson) for new projects and explicit migrations. In an existing RESTEasy Classic (quarkus-resteasy*) project keep that stack: the two are incompatible and mixing them fails the build.
• Use ./mvnw quarkus:dev (or ./gradlew quarkusDev) for development; keep the Maven/Gradle wrapper.

CDI and code

• Use constructor injection; @Inject is optional on a single constructor. Avoid field injection in production code.
• Prefer @ApplicationScoped beans; use jakarta.* imports only.
• Use records for DTOs. Keep REST resources thin and delegate to services.
• Use @ConfigMapping interfaces for grouped, typed configuration; @ConfigProperty for single values. Never hard-code secrets; use env vars or a secret store, and profiles (%dev, %test, %prod).
• Use quarkus.log.* and JBoss Logging (or SLF4J) for logging.

REST and validation

• Return explicit status codes and map errors centrally rather than try/catch in each resource. In Quarkus REST projects use RestResponse/Response, @ResponseStatus and @ServerExceptionMapper; in RESTEasy Classic projects these are unavailable, so use Jakarta REST Response and an ExceptionMapper annotated @Provider.
• Validate input with Hibernate Validator (quarkus-hibernate-validator, @Valid).
• Add quarkus-smallrye-health and metrics (quarkus-micrometer-registry-prometheus, or another Micrometer registry extension; quarkus-micrometer alone exports nothing) for production services; expose them only to trusted networks.

Data

• Use Hibernate ORM with Panache (quarkus-hibernate-orm-panache); prefer the repository pattern (PanacheRepository<T>) for non-trivial domains, active record for simple ones.
• Put @Transactional on service or resource methods that modify data; paginate list queries.
• Manage schema with Flyway or Liquibase in production, not drop-and-create.
• Rely on Dev Services for databases and brokers in dev/test; do not configure URLs for them in %dev/%test.

Security

• Use quarkus-oidc (or quarkus-smallrye-jwt) for authentication, and @RolesAllowed/quarkus.http.auth.permission.* for authorization. Secure endpoints by default.

Testing

• Use @QuarkusTest with RestAssured for application tests, @QuarkusIntegrationTest for packaged jar/native/container tests, and @InjectMock for CDI mocks.
• Use Dev Services and QuarkusTestResourceLifecycleManager for external dependencies; use continuous testing in dev mode.
• Run *IT tests with ./mvnw verify -DskipITs=false (Failsafe; the generated pom sets skipITs=true), not test. Test artifacts are quarkus-junit (3.31+) or quarkus-junit5 (older); keep what the project uses.

Avoid

• Reflection-heavy libraries without @RegisterForReflection when targeting native.
• Blocking calls on the event loop (use @Blocking or virtual threads with @RunOnVirtualThread).
• Swallowing exceptions or hard-coding configuration values.

Upgrading Quarkus: run quarkus update (https://quarkus.io/guides/update-quarkus) and read the version’s migration guide at https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.20 (change the version) before editing.