Helidon Best Practices

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.