java-helidon

# Helidon Best Practices Your goal is to help me write high-quality Helidon applications by following established best practices. ## Helidon 3 → 4 API changes Helidon 4 renamed or resignatured APIs that appear widely in their Helidon 3 form. The left column does not compile on Helidon 4. Check generated code against this table before returning it. | Do not use (Helidon 3) | Use (Helidon 4) | | ---------------------------------------------------------- | ------------------------------------------------------------------ | | `io.helidon.common.http.Http.Status` | `io.helidon.http.Status` | | `io.helidon.webserver.Service` | `io.helidon.webserver.http.HttpService` | | `Routing.Rules`, `update(Routing.Rules)` | `HttpRules`, `routing(HttpRules)` | | `request.path().param("id")` | `request.path().pathParameters().get("id")` | | `String s = column.as(String.class)` | `column.getString()` or `column.get(String.class)` | | `dbClient.execute(exec -> ...)` returning `Single`/`Multi` | `dbClient.execute()` returning `Optional<DbRow>` / `Stream<DbRow>` | | `javax.*` | `jakarta.*` | | `helidon-microprofile-tests-junit5` | `helidon-microprofile-testing-junit5` | `Value.as(Class)` in Helidon 4 returns `OptionalValue<T>`, not `T`. This is the single most common Helidon 4 compile error in generated code. ## Project Setup & Structure - **Programming Model:** Determine whether the project uses Helidon SE or Helidon MP before generating code. Do not mix the two programming models unless explicitly required. - **Java Version:** Use Java 21 or later for Helidon 4 applications. - **Build Tool:** Use Maven (`pom.xml`) or Gradle (`build.gradle`) for dependency management. - **Dependency Management:** Use the Helidon BOM or platform to keep Helidon module versions aligned. - **Package Structure:** Organize code by feature or domain, such as `com.example.app.order` and `com.example.app.customer`, rather than only by technical layer. ## Helidon SE - **Explicit Composition:** Construct services and dependencies explicitly in the application bootstrap layer. - **Constructor Injection:** Pass required dependencies through constructors and declare dependency fields as `private final`. - **HTTP Services:** Group related routes in focused `HttpService` implementations. - **Business Logic:** Keep business logic outside route handlers. - **Virtual Threads:** Prefer straightforward blocking code with Helidon 4 virtual-thread-based request handling. Do not introduce reactive complexity without a clear reason. Helidon 4 is not reactive; do not generate `Single`, `Multi`, or `CompletionStage` chains. ## Helidon MP - **Jakarta and MicroProfile:** Prefer standard Jakarta EE and Eclipse MicroProfile APIs when available. - **Dependency Injection:** Use CDI with constructor injection for required dependencies. - **Bean Scopes:** Use CDI scopes such as `@ApplicationScoped` and `@RequestScoped` intentionally. - **Normal-Scoped Beans:** Add a non-private no-argument constructor to normal-scoped beans that use constructor injection, so the CDI client proxy can be created portably. - **Business Logic:** Keep Jakarta REST resource classes thin and delegate business operations to service classes. - **Portability:** Prefer portable Jakarta and MicroProfile APIs over Helidon-specific APIs when portability is important. ## Configuration - **Externalized Configuration:** Store non-secret configuration in `application.yaml` or `application.properties`. - **Helidon SE Configuration:** Use Helidon Config and pass configuration values or typed configuration objects to components. - **Helidon MP Configuration:** Use MicroProfile Config for injected application settings. - **Environment Overrides:** Use environment variables or deployment-specific configuration sources for environment-dependent values. - **Secrets Management:** Never hardcode credentials, API keys, tokens, or private certificates. ## Web Layer - **DTOs:** Use dedicated request and response models. Do not expose persistence entities directly through APIs. - **Validation:** Validate path parameters, query parameters, headers, and request bodies before invoking business logic. - **Status Codes:** Return appropriate HTTP status codes for successful, invalid, unauthorized, forbidden, missing, and failed requests. On `PUT` and `DELETE`, return 404 when the target does not exist rather than succeeding unconditionally. - **Error Handling:** Use centralized error handling in Helidon SE and Jakarta REST `ExceptionMapper` implementations in Helidon MP. - **Sensitive Information:** Do not expose stack traces, database details, filesystem paths, or internal exception messages to clients. ### Helidon SE Example Use an `HttpService` to register routes programmatically. Keep request handlers small and delegate business logic to a service. ```java import io.helidon.http.Status; import io.helidon.webserver.http.HttpRules; import io.helidon.webserver.http.HttpService; import io.helidon.webserver.http.ServerRequest; import io.helidon.webserver.http.ServerResponse; public final class CustomerHttpService implements HttpService { private final CustomerService customerService; public CustomerHttpService(CustomerService customerService) { this.customerService = customerService; } @Override public void routing(HttpRules rules) { rules.get("/{id}", this::findById); } private void findById(ServerRequest request, ServerResponse response) { var id = request.path().pathParameters().get("id"); customerService.findById(id) .ifPresentOrElse( response::send, () -> response.status(Status.NOT_FOUND_404).send() ); } } ``` Register the HTTP service when constructing the server: ```java import io.helidon.webserver.WebServer; WebServer server = WebServer.builder() .routing(routing -> routing.register("/customers", customerHttpService)) .build() .start(); ``` ### Helidon MP Example Use Jakarta REST annotations for endpoints and CDI for dependency injection. ```java import jakarta.enterprise.context.RequestScoped; import jakarta.inject.Inject; import jakarta.ws.rs.GET; import jakarta.ws.rs.Path; import jakarta.ws.rs.PathParam; import jakarta.ws.rs.Produces; import jakarta.ws.rs.core.MediaType; import jakarta.ws.rs.core.Response; @Path("/customers") @RequestScoped @Produces(MediaType.APPLICATION_JSON) public class CustomerResource { private final CustomerService customerService; protected CustomerResource() { this.customerService = null; } @Inject public CustomerResource(CustomerService customerService) { this.customerService = customerService; } @GET @Path("/{id}") public Response findById(@PathParam("id") String id) { return customerService.findById(id) .map(customer -> Response.ok(customer).build()) .orElseGet(() -> Response.status(Response.Status.NOT_FOUND).build()); } } ``` ## Service Layer - **Transactions:** Define transaction boundaries around complete business operations. - **Entity Mapping:** Map persistence entities to API models at the service boundary so that service method signatures expose only API models. A service returning `Optional<CustomerEntity>` where the caller expects `Optional<Customer>` is a common generated-code compile error. - **Concurrency:** Avoid mutable shared state in application-scoped components unless access is properly coordinated. ### Helidon SE Example Helidon SE services are normally plain Java classes with explicitly supplied dependencies. ```java public final class CustomerService { private final CustomerRepository customerRepository; public CustomerService(CustomerRepository customerRepository) { this.customerRepository = customerRepository; } public Optional<Customer> findById(String id) { if (id == null || id.isBlank()) { throw new IllegalArgumentException("Customer ID is required"); } return customerRepository.findById(id); } public Customer create(CreateCustomerRequest request) { if (request.name() == null || request.name().isBlank()) { throw new IllegalArgumentException("Customer name is required"); } var customer = new Customer(request.id(), request.name().trim()); customerRepository.save(customer); return customer; } } ``` Construct the dependency graph explicitly: ```java var repository = new DbCustomerRepository(dbClient); var service = new CustomerService(repository); var httpService = new CustomerHttpService(service); ``` ### Helidon MP Example Use CDI scopes and constructor injection. Apply transactions at the service layer when a business operation changes persistent state. Map the persistence entity to the API model here, so the service never leaks `CustomerEntity` to callers. ```java import jakarta.enterprise.context.ApplicationScoped; import jakarta.inject.Inject; import jakarta.transaction.Transactional; @ApplicationScoped public class CustomerService { private final JpaCustomerRepository customerRepository; protected CustomerService() { this.customerRepository = null; } @Inject public CustomerService(JpaCustomerRepository customerRepository) { this.customerRepository = customerRepository; } public Optional<Customer> findById(String id) { if (id == null || id.isBlank()) { throw new IllegalArgumentException("Customer ID is required"); } return customerRepository.findById(id) .map(Customer::fromEntity); } @Transactional public Customer create(CreateCustomerRequest request) { if (request.name() == null || request.name().isBlank()) { throw new IllegalArgumentException("Customer name is required"); } var entity = new CustomerEntity(request.id(), request.name().trim()); customerRepository.save(entity); return Customer.fromEntity(entity); } } ``` ## Data Layer - **Database Access:** Use Helidon DB Client, Jakarta Persistence, or another persistence mechanism already established by the project. - **Parameterized Queries:** Always use parameter binding or prepared statements. Never concatenate untrusted input into SQL. - **Column Accessors:** Read a typed column value with `column("name").getString()` (or `getInt()`, `getLong()`, and so on) or with `column("name").get(String.class)`. `DbColumn.as(String.class)` returns an `OptionalValue<String>` in Helidon 4, not a `String`. - **Nullable Columns:** Read nullable columns through `asOptional()` or another optional-aware accessor. Direct `getString()` and similar accessors throw when the column value is null. - **Row Mapping:** For whole-row mapping, `DbRow.as(Customer.class)` returns the mapped instance directly, but requires a `DbMapper` registered through a `DbMapperProvider` service-loader entry. Prefer explicit column reads for a small number of simple repositories, and introduce a `DbMapper` when the same row shape is mapped in several places. - **Migrations:** Use a database migration tool for schema changes rather than automatic destructive schema updates. - **Entity Separation:** Do not expose database entities directly as API contracts. ### Helidon SE Example Use Helidon DB Client with parameterized statements. Map database rows into application models inside the repository. ```java import io.helidon.dbclient.DbClient; public final class DbCustomerRepository implements CustomerRepository { private static final String FIND_BY_ID = "SELECT id, name FROM customers WHERE id = :id"; private static final String INSERT = "INSERT INTO customers (id, name) VALUES (:id, :name)"; private final DbClient dbClient; public DbCustomerRepository(DbClient dbClient) { this.dbClient = dbClient; } @Override public Optional<Customer> findById(String id) { return dbClient.execute() .createGet(FIND_BY_ID) .addParam("id", id) .execute() .map(row -> new Customer( row.column("id").getString(), row.column("name").getString() )); } @Override public void save(Customer customer) { dbClient.execute() .createInsert(INSERT) .addParam("id", customer.id()) .addParam("name", customer.name()) .execute(); } } ``` Named statements can also be stored in configuration instead of embedding SQL in Java: ```yaml db: source: "jdbc" connection: url: "jdbc:postgresql://localhost:5432/customers" username: ${DB_USERNAME} password: ${DB_PASSWORD} statements: find-customer-by-id: > SELECT id, name FROM customers WHERE id = :id ``` Reference the named statement by name instead of passing SQL text: ```java return dbClient.execute() .createNamedGet("find-customer-by-id") .addParam("id", id) .execute() .map(row -> new Customer( row.column("id").getString(), row.column("name").getString() )); ``` ### Helidon MP Example Use Jakarta Persistence in a CDI-managed repository. Keep transaction boundaries in the service layer. The repository works in entities; the service maps them to API models. ```java import jakarta.enterprise.context.ApplicationScoped; import jakarta.persistence.EntityManager; import jakarta.persistence.PersistenceContext; @ApplicationScoped public class JpaCustomerRepository { @PersistenceContext private EntityManager entityManager; public Optional<CustomerEntity> findById(String id) { return Optional.ofNullable(entityManager.find(CustomerEntity.class, id)); } public void save(CustomerEntity customer) { entityManager.persist(customer); } } ``` Define the persistence entity separately from the public API model: ```java import jakarta.persistence.Column; import jakarta.persistence.Entity; import jakarta.persistence.Id; import jakarta.persistence.Table; @Entity @Table(name = "customers") public class CustomerEntity { @Id private String id; @Column(nullable = false) private String name; protected CustomerEntity() { } public CustomerEntity(String id, String name) { this.id = id; this.name = name; } public String id() { return id; } public String name() { return name; } } ``` The API model stays free of persistence annotations and owns the mapping: ```java public record Customer(String id, String name) { public static Customer fromEntity(CustomerEntity entity) { return new Customer(entity.id(), entity.name()); } } ```