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.

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.

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:

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.

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.

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:

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.

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);
    }
}