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 Configura