Structuring a Boot application

Boot will run anything: one class with a controller, a repository and a main method starts fine. The structure question is about the second year, when there are forty features and someone needs to change one without reading the other thirty-nine. The layout that survives is packages by feature, layers that each do one thing, DTOs at the edge, and tests that load exactly the slice they test.

#Package by feature, not by layer

The layer-first layout (controllers/, services/, repositories/) puts every unrelated thing together and every related thing apart. Changing "orders" means touching four packages, and nothing stops PaymentController from calling OrderRepository directly. Feature-first turns the package into the boundary:

com.acme.shop
├── ShopApplication.java             ← @SpringBootApplication, nothing else
├── orders
│   ├── OrderController.java         ← public: the HTTP surface
│   ├── OrderService.java            ← package-private
│   ├── OrderRepository.java         ← package-private
│   ├── Order.java                   ← the entity, package-private
│   ├── OrderDto.java                ← public: what other features and clients see
│   └── OrderPlaced.java             ← public: an event other features may listen to
├── payments
└── inventory

Java's package-private visibility does the enforcement for free. OrderRepository without public cannot be injected from payments; if payments needs an order, it goes through OrderService's public methods or listens for OrderPlaced. A feature's public surface is deliberately small, and a pull request that adds public to a repository is a design conversation. Spring Modulith formalises the same idea and can verify at test time that no package reaches into another's internals; the plain-Java version gets most of the benefit.

The main class stays boring on purpose. @SpringBootApplication scans downwards from its package, so it sits at the root and contains SpringApplication.run and nothing else. Beans that need configuration go in a @Configuration inside the feature that owns them.

#Layers that earn their keep

Three layers, each with a job it does not share:

A "thin controller" is one you could delete and replace with a Kafka listener that calls the same service. A "service that earns its keep" is one whose methods read like the product's verbs: placeOrder, cancelOrder, not saveOrder. If a service method is one line that calls the repository, the question is whether the method is misnamed or whether the layer is doing nothing yet; both are fine, as long as the transaction boundary is there, because @Transactional belongs on the service method and nowhere else:

@Service
class OrderService {
    private final OrderRepository orders;
    private final ApplicationEventPublisher events;
 
    @Transactional
    OrderDto place(PlaceOrder cmd) {
        var order = Order.place(cmd.customerId(), cmd.lines());   // the domain enforces its invariants
        orders.save(order);
        events.publishEvent(new OrderPlaced(order.id()));
        return OrderDto.from(order);
    }
}

#DTOs and mappers

The JPA entity does not leave the service. Returning it from a controller couples the API to the database schema, serialises lazy collections outside the transaction (the LazyInitializationException, or worse, the query storm when open-in-view hides it), and leaks fields that were never meant to be public. @JsonIgnore on an entity is the smell that says the entity is being used as a DTO.

Records make DTOs cheap:

public record OrderDto(UUID id, String status, List<LineDto> lines, Instant placedAt) {
    static OrderDto from(Order o) {
        return new OrderDto(o.getId(), o.getStatus().name(),
            o.getLines().stream().map(LineDto::from).toList(), o.getPlacedAt());
    }
    public record LineDto(String sku, int quantity) {
        static LineDto from(OrderLine l) { return new LineDto(l.getSku(), l.getQuantity()); }
    }
}

A static from per DTO is enough for most services and is greppable. MapStruct generates the same code from an interface when there are dozens of them; it is worth it when mapping is the bulk of the boilerplate and not before. Inbound requests get their own record (PlaceOrderRequest), separate from the outbound OrderDto, because the two change for different reasons.

#Where validation lives

Three places, three kinds of rule:

1. The request shape, at the controller, with Bean Validation: @Valid @RequestBody PlaceOrderRequest req, constraints on the record's components. Fails with 400 before any code of yours runs.
2. Domain invariants, in the domain: an order cannot be placed with zero lines, a cancellation cannot follow shipment. These live in Order.place(...) and order.cancel(), throwing a domain exception, because they must hold no matter which entry point (HTTP, Kafka, a batch job) reaches the domain.
3. Data integrity, in the database: unique constraints, foreign keys, not-null. The last line, and the only one that holds under concurrent writers.

A rule enforced only in the controller is a rule the message listener will break. Errors get one shape: a @RestControllerAdvice maps domain exceptions to ProblemDetail responses (spring.mvc.problemdetails.enabled=true does the same for the framework's own errors), so a client sees RFC 9457 problem JSON with a type, a title and a status, never a stack trace.

#Testing slices

@SpringBootTest loads everything, connects to everything, and takes ten seconds before the first assertion. Boot's slices load one layer:

@WebMvcTest(OrderController.class)
class OrderControllerTest {
    @Autowired MockMvc mvc;
    @MockitoBean OrderService service;
 
    @Test void rejectsAnEmptyOrder() throws Exception {
        mvc.perform(post("/orders").contentType(APPLICATION_JSON).content("""
                {"customerId":"c1","lines":[]}"""))
           .andExpect(status().isBadRequest());
    }
}

The service layer needs no slice: it is plain Java with constructor injection, so a unit test constructs it with a fake repository and runs in milliseconds. A test pyramid for a Boot service is mostly those, then slices, then a few @SpringBootTest runs that prove the wiring, and the whole suite finishes before the coffee does.

#Under the hood: what a slice test actually loads

@SpringBootTest walks up from the test's package to find @SpringBootConfiguration (your main class), builds a context from it, and runs every auto-configuration the classpath allows: a datasource, JPA, Kafka listeners, security, Tomcat if webEnvironment says so. A slice annotation is the same bootstrapper with two changes. It carries @ImportAutoConfiguration with a curated list of auto-configurations for that layer, and it installs a TypeExcludeFilter so component scanning from the main class keeps only the beans of that layer: @WebMvcTest keeps @Controller, @ControllerAdvice, @JsonComponent, converters, filters and WebMvcConfigurers and drops @Service, @Repository and @Component; @DataJpaTest keeps @Repository and entities, adds an embedded database (or the Testcontainers one through @ServiceConnection), and wraps every test in a rolled-back transaction. That is why a controller test that "cannot find bean OrderService" is behaving correctly: the service was filtered out, and @MockitoBean is how you say what it should return.

The filter is what the package layout feeds. @SpringBootApplication on the main class means @ComponentScan from that package, and a slice test scans the same tree through the exclude filter; a main class moved into com.acme.shop.app scans only app, and a @Configuration in com.acme.shop.orders silently vanishes from every test and from production alike. Package-private visibility works with the same scanner: Spring instantiates beans reflectively and does not care whether the class is public, so class OrderService (no modifier) is a perfectly good bean that no other package can name, and injection across the boundary fails at compile time rather than at wiring time.

Contexts are cached across tests keyed by their configuration (the annotations, properties, mocks and profiles), so ten @WebMvcTests with the same shape share one context, and one test with a different properties value forces a second. A suite that takes minutes usually has many distinct keys; @MockitoBean declarations are part of the key, so mocking a different set of beans in each test class is the common cause of "every test starts a context".

Open-in-view is a filter too: OpenEntityManagerInViewInterceptor, registered by JpaWebConfiguration when spring.jpa.open-in-view is true, binds an EntityManager to the request thread before the controller runs and closes it after the response is written. A lazy collection touched during JSON serialisation therefore finds a live persistence context and loads, one query per element, on a connection held for the whole request, including the time spent writing the response to a slow client. With it off, the same access throws LazyInitializationException, which is the error you want, because it points at the DTO that should have been built inside the service's transaction.

#Walkthrough: the module that leaked into three others

A retail platform kept everything in one Boot application and grew to fifty packages. A change to the Order entity broke the build in payments, shipping and reporting.

public class Order { ... }                       // public entity
public interface OrderRepository extends JpaRepository<Order, UUID> { ... }   // public
 
// in shipping
@Service class ShippingService { ShippingService(OrderRepository orders) { ... } }   // reaches into orders

1. Every entity and repository was public because the first generator made them so. shipping injected OrderRepository directly, ran its own queries against Order, and mapped its fields. So did payments and reporting. The orders team renamed a column and moved a status enum; three other teams' code stopped compiling and one team's report silently returned zero rows.
2. The build had no boundary check. The only signal that shipping depended on the internals of orders was the import statement, which no review had flagged in two years.
3. The fix was mechanical and slow: Order and OrderRepository went package-private; orders exposed OrderService.find(UUID) returning an OrderDto and published OrderPlaced/OrderShipped events; each of the three consumers was moved onto that surface, feature by feature, behind a Spring Modulith ApplicationModules.verify() test that failed on any cross-package access to a non-exposed type.
4. reporting turned out to need read access to eight modules' data. Rather than eight public surfaces, it got its own read model, filled from the events, which is also what it would have been as a separate service.
5. Two quarters later, orders was extracted into its own deployable in a week, because the boundary already existed. The monolith had become modular before it became distributed, which is the only order in which that works.

The compiler enforces package-private for free; a verify test enforces it against reflection-happy frameworks. Neither is a substitute for deciding what each feature's surface is, but both make the decision stick.

#Try it yourself

@WebMvcTest(OrderController.class)
class OrderControllerTest { @Autowired OrderService service; ... }

#Misconceptions

• "Package-private beans do not work with Spring." Spring instantiates reflectively and ignores visibility; package-private is the cheapest module boundary Java has.
• "@WebMvcTest is a fast @SpringBootTest." It is a different context: the web layer only, services filtered out, mocks required. That is the feature.
• "Open-in-view is a performance optimisation." It holds a connection for the whole request and turns lazy access into N+1 queries during serialisation. It hides the missing DTO; off is the fix.
• "Returning the entity is fine if I add @JsonIgnore where needed." The annotation is the symptom: the API is coupled to the schema, and every new field is public by default.
• "Feature packages mean no shared code." Shared infrastructure (a RestClient config, an error advice, a Clock bean) lives in a common or platform package; what does not cross is domain internals.

#Going deeper

• Spring Boot reference, "Testing → Auto-configured Tests" for every slice and what each imports; TypeExcludeFilter and WebMvcTypeExcludeFilter source.
• Spring Framework reference, "Context Caching" in the TestContext framework.
• Spring Modulith reference, "Fundamentals" and "Verifying Application Module Structure".
• Vlad Mihalcea, "The Open Session In View anti-pattern", and Boot's JpaWebConfiguration source.
• Oliver Drotbohm, "Architecturally evident Java applications" (talk), on package-by-feature and the events between features.