Quarkus Service Conventions

Contract

Enforces Quarkus (CDI / Panache / RESTEasy Reactive / Mutiny) idioms when writing Java for a Quarkus service. Apply whenever the project is Quarkus — do NOT reach for Spring Boot annotations, naming, or layout. Every rule below is mandatory.

Rules

1. Naming and package layout

• A REST endpoint class is named <Name>Resource (e.g. MarketResource, OrderResource).

Never <Name>Controller.

• REST endpoint classes live in a resource/ package. Never controller/.
• Standard packages: resource/, service/, repository/, domain/ (entities),

dto/, config/, mapper/.

2. REST endpoints (JAX-RS)

• Class-level: @Path("/markets"). Method-level: @GET / @POST / @PUT / @DELETE

plus a method-level @Path("/{id}") for sub-paths.

• Path variables: @PathParam("id"). Query params: @QueryParam("page").
• Produce/consume JSON with @Produces(MediaType.APPLICATION_JSON) /

@Consumes(MediaType.APPLICATION_JSON).

• Never use Spring @RestController, @GetMapping, @PostMapping, @RequestMapping,

@PathVariable, or @RequestParam.

3. CDI beans and injection

• Annotate service/bean classes @ApplicationScoped. Never @Service, @Component,

@RestController, or @Singleton (@Singleton is non-proxyable — interception breaks).

• Inject dependencies with @Inject (constructor injection or field injection). Never

@Autowired.

4. Panache entities (active record)

• Entity extends PanacheEntity (JPA) or extends PanacheMongoEntity (MongoDB,

annotated @MongoEntity(collection = "...")).

• Declare public fields with NO getters and NO setters — Panache generates accessors at

build time. Do not write private fields + boilerplate getters/setters.

• Query with static finders on the entity: Market.find("slug", slug),

Market.findById(id), Market.listAll(). For an Optional, use .firstResultOptional(). Never inject a JpaRepository/CrudRepository.

5. Reactive (Mutiny)

• Reactive methods return Uni<T> (single) or Multi<T> (stream). Never

CompletableFuture, Reactor Mono/Flux, or a blocking T.

• Compose with .chain(...), .onItem()..., .onFailure().... Handle absence with

.onItem().ifNull().failWith(() -> ...).

• Never make a blocking call inside a Uni/Multi pipeline (it stalls the event loop).
• To consume one cold Uni from two subscribers, share it with .memoize().indefinitely()

— do not call .subscribe() twice on the same cold Uni.

6. Logging

• Use JBoss Logging: private static final Logger log = Logger.getLogger(Foo.class);

(org.jboss.logging.Logger). Or CDI-inject it: @Inject Logger log;.

• Format with log.infof("fetch slug=%s", slug) / log.errorf(ex, "failed slug=%s", slug).
• Never use SLF4J LoggerFactory.getLogger(...) or {} placeholders.

7. Configuration

• Bind a group of properties with @ConfigMapping(prefix = "market") on an INTERFACE with

method accessors (int maxPageSize();). For a single value, use @ConfigProperty(name = "market.max-page-size", defaultValue = "100").

• Never @ConfigurationProperties or @Value.
• The settings file is src/main/resources/application.properties. Never application.yml.
• DB seed/import data goes in src/main/resources/import.sql (Hibernate auto-loads it in dev/test).

8. Exceptions

• Map a domain exception to an HTTP response with an ExceptionMapper<E> annotated

@Provider, or a @ServerExceptionMapper method (RESTEasy Reactive).

• Never @RestControllerAdvice or @ExceptionHandler.

9. Validation

• Validate a request body or bean param with @Valid on the parameter, combined with Bean

Validation constraints (@NotNull, @NotBlank) on the DTO.

10. Tests

• Integration test: @QuarkusTest; replace a bean with @InjectMock; assert with

RestAssured given().when().get("/markets/unknown").then().statusCode(404).

• Never @SpringBootTest, @WebMvcTest, @MockBean, or MockMvc.
• Pure unit test (no CDI): plain JUnit 5 + Mockito —

@ExtendWith(MockitoExtension.class) with @Mock / @InjectMocks. No @QuarkusTest.

Worked examples (before = base's Spring default → after = Quarkus)

Resource naming + JAX-RS

java
// BEFORE
@RestController
@RequestMapping("/markets")
public class MarketController {
  @GetMapping("/{slug}")
  public Market find(@PathVariable String slug) { ... }
}
// AFTER
@Path("/markets")
@ApplicationScoped
public class MarketResource {
  @GET @Path("/{slug}")
  @Produces(MediaType.APPLICATION_JSON)
  public Market find(@PathParam("slug") String slug) { ... }
}

CDI bean + injection

java
// BEFORE
@Service
public class MarketService {
  @Autowired private MarketRepository repo;
}
// AFTER
@ApplicationScoped
public class MarketService {
  private final MarketRepository repo;
  @Inject public MarketService(MarketRepository repo) { this.repo = repo; }
}

Panache entity

java
// BEFORE
@Entity
public class Market {
  @Id @GeneratedValue private Long id;
  private String name;
  public String getName() { return name; }
  public void setName(String n) { this.name = n; }
}
// AFTER
@Entity
public class Market extends PanacheEntity {
  public String name;
  public String status;   // public fields, accessors generated at build time
}

Panache query → Optional

java
// BEFORE
Optional<Market> m = marketRepository.findBySlug(slug);
// AFTER
Optional<Market> m = Market.find("slug", slug).firstResultOptional();

Reactive method

java
// BEFORE
public CompletableFuture<Order> placeOrder(OrderRequest req) { ... }
// AFTER
public Uni<Order> placeOrder(OrderRequest req) {
  return validate(req).chain(this::persist).chain(this::notifyFulfillment);
}

Logging

java
// BEFORE
private static final Logger log = LoggerFactory.getLogger(MarketService.class);
log.info("fetch slug={}", slug);
// AFTER
private static final Logger log = Logger.getLogger(MarketService.class);
log.infof("fetch slug=%s", slug);

Configuration

java
// BEFORE
@ConfigurationProperties(prefix = "market")
public class MarketProps { private int maxPageSize; /* getters */ }
// AFTER
@ConfigMapping(prefix = "market")
public interface MarketConfig { int maxPageSize(); Duration cacheTtl(); }

Exception → 404

java
// BEFORE
@RestControllerAdvice
class Handler {
  @ExceptionHandler(MarketNotFoundException.class)
  ResponseEntity<?> h(MarketNotFoundException e) { return ResponseEntity.status(404).build(); }
}
// AFTER
@Provider
public class MarketNotFoundMapper implements ExceptionMapper<MarketNotFoundException> {
  public Response toResponse(MarketNotFoundException e) {
    return Response.status(404).entity(ErrorResponse.from(e)).build();
  }
}

Integration test

java
// BEFORE
@WebMvcTest(MarketController.class)
class T { @Autowired MockMvc mvc; @MockBean MarketService svc; }
// AFTER
@QuarkusTest
class MarketResourceTest {
  @InjectMock MarketService svc;
  @Test void notFound() {
    given().when().get("/markets/unknown").then().statusCode(404);
  }
}

Edge cases & exceptions

• Single application-wide bean that must be interceptable/proxyable → still

@ApplicationScoped, not @Singleton. @Singleton exists but breaks proxying/interception.

• MongoDB entity → extends PanacheMongoEntity + @MongoEntity(collection = "markets");

same public-fields rule.

• Repository pattern instead of active record → a PanacheRepository<Market> bean is

allowed, but do not mix active-record static finders and an injected repository in the same bounded context; pick one.

• YAML config is only available with the quarkus-config-yaml extension; default and

idiomatic is application.properties.

• Two cold-Uni subscribers → memoize(); a hot/already-resolved Uni can be subscribed

freely.

• Field injection is acceptable in Quarkus (package-private @Inject field avoids proxy

issues) — unlike Spring where constructor injection is strongly preferred. Either is fine here.

Do / Don't

• Never @RestController / @GetMapping; always @Path + @GET on a *Resource.
• Never @Service / @Autowired; always @ApplicationScoped + @Inject.
• Never @Singleton for a normal bean; always @ApplicationScoped.
• Never private entity fields + getters/setters; always public Panache fields.
• Never inject a JpaRepository; always static Panache finders.
• Never CompletableFuture/Mono/Flux; always Uni/Multi.
• Never block inside a Uni/Multi; always compose with .chain/.onItem.
• Never SLF4J + {}; always JBoss Logger + infof/errorf + %s.
• Never @ConfigurationProperties/@Value/application.yml; always

@ConfigMapping/@ConfigProperty + application.properties.

• Never @RestControllerAdvice; always ExceptionMapper/@ServerExceptionMapper.
• Never @SpringBootTest/@MockBean/MockMvc; always @QuarkusTest/@InjectMock/RestAssured.

Common mistakes (base's wrong defaults)

• Names the endpoint *Controller and annotates @RestController because "Java REST service"

reads as Spring.

• Uses @Service + field @Autowired for the service bean.
• Writes a JPA entity with private fields and full getter/setter boilerplate.
• Injects a Spring-Data-style repository instead of calling Panache static finders.
• Returns CompletableFuture/Mono for an async method.
• Reaches for SLF4J LoggerFactory and {} placeholders.
• Defaults config to application.yml + @ConfigurationProperties.
• Handles exceptions with @RestControllerAdvice/@ExceptionHandler.
• Tests with @SpringBootTest/@WebMvcTest + @MockBean + MockMvc.

Quick checklist

• ] *Resource in resource/, JAX-RS annotations only
• ] @ApplicationScoped + @Inject (never @Service/@Autowired/@Singleton)
• ] Panache entity: extends PanacheEntity, public fields, static finders
• ] Reactive returns Uni/Multi, no blocking inside pipeline
• ] JBoss Logger + infof/errorf + %s
• ] @ConfigMapping/@ConfigProperty + application.properties
• ] ExceptionMapper/@ServerExceptionMapper for error responses
• ] @QuarkusTest + @InjectMock + RestAssured; unit = Mockito only