As an API designer, where should Optional appear and where should it be avoided, and how do construction choices reflect those decisions?

## Background: what Optional is for `Optional<T>` is a container that holds a value or nothing, and its real purpose is *communication*: it lets a method's type say "the result may be absent" so the caller is reminded to handle that case. Brian Goetz (Java's language architect) framed it narrowly — Optional was added "to provide a limited mechanism for library method **return types** where there needed to be a clear way to represent 'no result.'" Understanding that scope is what separates good Optional usage from cargo-culting it everywhere. ## Where Optional belongs: return types The canonical, recommended use is the return type of a method that may have no answer: ```java Optional<User> findById(long id); // clearly signals "maybe not found" ``` The caller cannot ignore the absent case as easily as they could ignore a possible `null`, and the chaining methods (`map`, `filter`, `orElseThrow`) let them handle it fluently. Finder/query/lookup methods are the textbook fit. ## Where Optional does *not* belong 1. **Fields / instance state.** Wrapping a field in Optional adds an extra heap object per instance, and `Optional` is **not `Serializable`**, which breaks serialization-based frameworks. Entities and DTOs should use a plain (possibly null) field; expose optionality through a getter that returns `Optional` if you want. 2. **Method parameters.** Making a parameter `Optional<T>` forces every caller to wrap their argument (`f(Optional.of(x))`), which is noisier than allowing null or providing overloads. Prefer overloading or a nullable parameter with documentation. 3. **Collection or array return types.** A collection already has a perfectly good "nothing" value — the empty collection. Returning `Optional<List<T>>` forces callers to unwrap *and then* check emptiness, two steps for one concept. Always return an empty `List`/`Set`/`Map` instead of an absent Optional of a collection. 4. **As a general null replacement everywhere.** Optional is heavier than a reference and is not meant to scrub every nullable variable. Use it at API seams where optionality is part of the contract. ## How construction choices encode design intent The three factories aren't just mechanics — each documents an assumption at the boundary: - **`Optional.ofNullable(source)`** at an *input* boundary: you're adapting a value that legitimately might be null (a `Map.get`, a nullable JDBC column, a third-party API). This is the workhorse for *producing* a return Optional from nullable internals. - **`Optional.of(value)`** when you've **established an invariant** that the value is non-null (e.g., you just built it, or a prior check guarantees it). Using `of` here is intentional fail-fast: if the invariant is ever violated, you get an immediate NPE pinpointing the bug rather than a silently-empty Optional that hides it. - **`Optional.empty()`** to express a *deliberate* no-result path (e.g., a guard clause that returns early when input is invalid). Choosing `of` vs `ofNullable` is therefore a small design statement: "I assert this is present" versus "this may be absent and that's fine." ## On the consumption side Design also dictates how callers should unwrap. Encourage `orElseThrow(() -> new DomainException(...))` for required values (meaningful failure), `orElseGet(...)` for costly defaults, and discourage bare `get()` (it reintroduces the runtime-crash risk). Establishing these as team conventions, ideally enforced by static analysis, keeps the API's optionality promise intact end to end. ## Performance and identity notes `Optional` is a value-based class: don't rely on its identity (`==`), don't synchronize on it, and remember each non-empty Optional is an extra allocation. For extremely hot inner loops, the wrapper cost can matter; primitive specializations (`OptionalInt/Long/Double`) avoid boxing for those types. None of this should scare you away from the return-type use case — just from sprinkling Optional everywhere. ## Summary - Optional is for **return types** that may have no result (finders/queries). - Avoid it for **fields, parameters, and collection returns** (use empty collections for the latter). - Construction encodes intent: `ofNullable` at nullable input seams, `of` to assert/fail-fast on an invariant, `empty` for a deliberate no-result. - Pair with `orElseThrow`/`orElseGet` on consumption; avoid bare `get()`.