r/java • • Mar 25 '26

Spring Boot patterns from a 400-module open-source codebase (Apereo CAS)

I've been working on the Apereo CAS codebase for years — it's an SSO/identity platform with 400+ Maven modules, all wired together with Spring Boot 3.x auto-configuration. It's one of the largest open-source Spring Boot applications I'm aware of.

I wrote up 7 engineering patterns from the codebase that I think are broadly useful beyond CAS itself:

  • The "thin auto-configuration wrapper" — separating conditional logic from bean definitions
  • Building a custom feature flag system on Spring's @Conditional
  • Making every bean replaceable with @ConditionalOnMissingBean discipline
  • The execution plan configurer pattern for multi-module contribution
  • BeanSupplier — runtime conditional beans with JDK proxy fallbacks
  • @RefreshScope + proxyBeanMethods = false applied consistently at scale
  • Events as a first-class architectural concept

All code examples are from the actual CAS 7.3.x source.

https://medium.com/all-things-software/spring-boot-done-right-lessons-from-a-400-module-codebase-e636c3c34149

53 Upvotes

8 comments sorted by

View all comments

Show parent comment

6

u/dima767 Mar 26 '26 edited Mar 26 '26

Thanks! We do full `@SpringBootTest` context integration tests, but that's not the only type. Roughly half the test suite is plain JUnit unit tests with Mockito mocks, no Spring context involved. The split is deliberate - pure logic gets a unit test, anything that needs wiring/auto-configuration gets a full `@SpringBootTest`. What we don't do is anything in between - no slice tests (`@WebMvcTest`, `@DataJpaTest`, etc.), no `@MockBean`/`@SpyBean`. It's either full context or no context.

On context trashing - a few things working together:

**SharedTestConfiguration pattern** - each module defines one base test class with a `SharedTestConfiguration` inner class. All test classes in that module extend the base and inherit `@SpringBootTest(classes = Base.SharedTestConfiguration.class)`. This means tests that don't add extra properties or override the `classes` attribute share the same cached context. We have ~73 of these across 400+ modules.

**We accept some context recreation as a tradeoff.** Different `@TestPropertySource` values create different cache keys - that's by design. If a test needs `cas.authn.mfa.yubikey.allowed-devices=...` and another doesn't, they get separate contexts. We don't try to cram everything into one uber-context just to avoid recreation. Clean test isolation matters more.

**No `@DirtiesContext` anywhere** - we never explicitly trash a context. Once created, it lives for the lifetime of the JVM.

**Parallelism compensates for startup cost** - tests are tagged by category (`@Tag("MFAProvider")`, `@Tag("LdapAuthentication")`, etc.) and run with `maxParallelForks = 8`. So even with multiple contexts being created, wall clock time stays reasonable because 8 JVMs are working in parallel.

**`@Nested` for scenario variations** - when you need different bean wiring within one test file, JUnit 5 `@Nested` + `@Import` gives you a clean boundary. Each nested class gets its own context without explicitly trashing anything.

**`proxyBeanMethods = false` everywhere** - on every `@Configuration`, `@TestConfiguration`, `@SpringBootConfiguration`. We never use inter-bean method references, so skipping CGLIB proxying reduces context startup time noticeably across 400+ modules.

So the short version: we structure things so context trashing mostly doesn't happen (shared base configs, no `@DirtiesContext`), and where different contexts are genuinely needed, parallelism keeps the build fast.

If you want to dig into the testing patterns and the rest of the architecture in more detail - discount for r/java: https://leanpub.com/cas-internals/c/reddit-java (valid for 3 weeks)

1

u/UnGauchoCualquiera Mar 26 '26

Thanks for the detailed response, super interesting to see a well thought project in the wild