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

…