How do named interfaces change what verify() allows, and why would you use them instead of relying on the default module API?

## The default exposure model Every Spring Modulith module has a **base package** (its root). By default: - Types **directly in the base package** are the module's **public API** — any other module may reference them (subject to allowed-dependency rules). - Types in **nested sub-packages** are **internal** — off-limits to other modules; `verify()` fails on cross-module access to them. That single, package-based boundary is often good enough. But it's coarse: sometimes you have types that must be `public` for framework or intra-module reasons yet shouldn't be part of the *cross-module contract*, or you want to offer **different contracts to different consumers**. ## Named interfaces: curated exposure A **named interface** is a *labeled slice* of a module's exposed surface, declared with `@org.springframework.modulith.NamedInterface`. Two common forms: 1. **Package-based** — mark a sub-package's `package-info.java`: ```java @org.springframework.modulith.NamedInterface("stock-api") package com.example.shop.inventory.stock; ``` Now the `stock` sub-package (normally internal!) becomes a named, exposed interface called `stock-api`. 2. **Type-based** — annotate specific types to assign them to a named interface. A module can declare **several** named interfaces, each a different contract. ## How this changes `verify()` - Consumers can be pinned to a specific slice through the **double-colon** allow syntax: ```java @org.springframework.modulith.ApplicationModule( allowedDependencies = { "inventory :: stock-api" }) package com.example.shop.order; ``` `order` may now reference **only** the `stock-api` named interface of `inventory`. Referencing any other exposed inventory type is a `verify()` violation. - If a module defines named interfaces, allow-list entries that name the module *without* a `:: interface` may resolve to the **unnamed/default** interface — so being explicit prevents surprises about which slice is actually granted. ## Why use them instead of the default API - **Narrow the blast radius**: publish a minimal, intentional contract; keep the rest reachable only inside the module even if it's `public`. - **Multiple contracts**: expose, say, `read-api` to most modules and `admin-api` to only one, each enforced. - **Expose a deliberately-nested package** as API without flattening your package structure. - **Documentation clarity**: named interfaces show up in the Documenter canvas, making the intended contract explicit. ## Gotchas - Naming a module in an allow-list is **string-matched**; the same applies to the interface name after `::` — a typo silently points at nothing valid and fails verification. - Promoting a nested package to a named interface **changes** it from internal to exposed — a deliberate widening; don't do it accidentally. - Named interfaces control *what's reachable*, not *who can reach it* by identity — access control is still 'any module allowed to depend on this slice'. Fine-grained per-consumer restriction is expressed on the **consumer's** allowedDependencies, not the producer. - Reflection-based access still bypasses the static check. ## When to use Reach for named interfaces once a module's honest contract is smaller than 'everything in the base package', or when one module must serve distinct APIs to distinct consumers. Otherwise the default exposure is simpler and sufficient.