Spring Boot OpenFeature — Wiki
1. What is this?
A Spring Boot starter that plugs OpenFeature — an open standard for feature-flag management — into Spring Boot apps. It gives you a ready-made Client bean, a health indicator, a declarative @ToggleOnFlag annotation, and one starter module per flag backend (Unleash, ConfigCat, Flagsmith, flagd, Flipt, GrowthBook, Statsig, and more).
It is a Java 17 / Spring Boot 4 multi-module Maven library, not an application. See overview/what-is-this for the module map.
2. Get started
- Main command:
./mvnw clean verify(builds all modules, runs checkstyle + tests).make helplists the same Maven commands as targets (make build,make test-module MODULE=<dir>,make coverage). - Required environment: Java 17, no external services for the library build. The runnable examples need a Unleash instance (or use the bundled fake/mock servers).
./setup.shinstalls the pre-commit hooks and the project skills. - Expected output: all modules
BUILD SUCCESS; theunleash-simpleexample answers on port9998with flag-driven responses. - Design read:
docs/is the design home (the OpenSpec workflow was retired 2026-11-14) — see overview/design-docs. - First files to read:
spring-boot-openfeature-autoconfigure/.../ClientAutoConfiguration.java— the central wiringspring-boot-starter-openfeature-unleash/.../UnleashAutoConfiguration.java— the reference provider patternspring-openfeature/.../aop/ToggleOnFlagAspect.java— the annotation feature
- Safe first change: add a new provider starter by copying the Unleash module (see features/provider-starters).
- Tempting dangerous change: editing
ClientAutoConfigurationconditions or the@AutoConfigureBeforeordering — breaking these silently disables flag evaluation (see risks/fragile-behavior).
3. Why does it exist?
Spring Boot apps want feature flags, but wiring the OpenFeature SDK by hand means managing provider lifecycle, event logging, evaluation context, and health checks per backend. This project makes that wiring automatic and provider-agnostic: add one starter dependency, set a few spring.openfeature.* properties, and flags work.
4. What happens when I run it?
Spring Boot auto-configuration kicks in (registered via META-INF/spring/...AutoConfiguration.imports):
- The provider auto-config (e.g.
UnleashAutoConfiguration) builds aFeatureProviderbean fromspring.openfeature.<provider>.*properties. OpenFeatureAPIAutoConfigurationexposes the OpenFeature SDK's globalOpenFeatureAPIand installs event logging.- If Spring Security is on the classpath,
SecurityAutoConfigurationadds a hook that injectsuserId/authoritiesinto every flag evaluation. ClientAutoConfigurationregisters the provider (waiting for readiness) and exposes theClientbean.
The full sequence: flows/startup-flow.
5. Where is data saved?
The library itself stores nothing. Flag data lives in the external provider (Unleash server, env vars, etc.). Optional local state: Unleash's backupFile property writes a local JSON cache of fetched flags.
6. What are the important moving parts?
- features/toggle-on-flag —
@ToggleOnFlagAOP annotation for declarative flag-gated methods - features/provider-starters — the per-backend starter modules and their shared pattern
- features/health-indicator — Actuator health check for the flag provider
- features/security-integration — automatic
userId/authoritiesevaluation context - features/multi-provider — combining several providers behind one client
- concepts/customizers — extension points (
ClientCustomizer,OpenFeatureAPICustomizer, provider customizers) - entities/configuration-properties — all
spring.openfeature.*property prefixes
7. What should I avoid breaking?
- The auto-configuration ordering (
@AutoConfigureBefore) — providers must exist before theClientbean is built. - The
OpenFeatureAPIsingleton — it is global SDK state; the project intentionally funnels all mutations through auto-config. - The Unleash module as reference implementation — new providers are expected to mirror it.
- Details: risks/fragile-behavior.
8. Where do I look first?
| Question | Page |
|---|---|
How does a provider become a Client? |
flows/startup-flow |
How does @ToggleOnFlag decide to run a method? |
flows/flag-evaluation |
| How do I add a new provider? | features/provider-starters + docs/provider-starter-contract.md |
| What build commands and profiles exist? | reference/build-and-modules |
| Where is a design decision written down? | overview/design-docs |
| What is planned but not built? | docs/backlog.md (see overview/design-docs) |