Microsphere Spring

Microsphere Projects for Spring Framework

Microsphere Spring is a modular library of Spring Framework extensions that solves real-world challenges in production Spring applications. It enhances dependency injection, configuration management, web endpoint handling, event processing, caching, and JDBC monitoring — all while remaining a drop-in addition to any existing Spring application.

Table of Contents

• Features
• Modules
• Prerequisites
• Getting Started
• Usage Examples
• Building from Source
• Documentation
• Getting Help
• Contributing
• Maintainers
• License

Features

• Parallel bean instantiation — resolves bean dependency graphs and initializes independent singletons concurrently to reduce startup time
• Listenable Environment — intercept property resolution and profile activation events via EnvironmentListener and PropertyResolverListener
• Enhanced @PropertySource — @ResourcePropertySource adds wildcard resource patterns, ordering control, inheritance, auto-refresh on change, and built-in YAML/JSON support (@YamlPropertySource, @JsonPropertySource)
• TTL caching — @EnableTTLCaching / @TTLCacheable extend Spring Cache with per-entry time-to-live configuration, including Redis support
• Web endpoint registry — collects WebEndpointMapping metadata from Spring MVC, WebFlux, and classic Servlet at startup for introspection and routing
• Handler method interception — HandlerMethodInterceptor / HandlerMethodArgumentInterceptor provide AOP-style hooks around MVC and WebFlux controller invocations
• P6Spy JDBC monitoring — @EnableP6DataSource wraps existing DataSource beans transparently for SQL tracing
• Google Guice integration — @EnableGuice bridges Guice @Inject injection points into the Spring bean lifecycle
• Rich testing utilities — EmbeddedTomcatContextLoader, EnableEmbeddedDatabase, AbstractWebFluxTest, and servlet/MVC test helpers

Modules

Module	Purpose	Key Annotations / APIs
microsphere-spring-parent	Parent POM with dependency management	—
microsphere-spring-dependencies	External dependency BOM	—
microsphere-spring-context	Core context & configuration extensions	@ResourcePropertySource, @YamlPropertySource, @JsonPropertySource, @EnableTTLCaching, @EnableConfigurationBeanBinding
microsphere-spring-web	Shared web abstractions	WebEndpointMapping, HandlerMethodInterceptor, @EnableWebExtension, @Idempotent
microsphere-spring-webmvc	Spring MVC extensions	@EnableWebMvcExtension, MethodHandlerInterceptor, ReversedProxyHandlerMapping
microsphere-spring-webflux	Reactive web extensions	@EnableWebFluxExtension, InterceptingHandlerMethodProcessor, ReversedProxyHandlerMapping
microsphere-spring-jdbc	JDBC / P6Spy integration	@EnableP6DataSource
microsphere-spring-guice	Google Guice bridge	@EnableGuice
microsphere-spring-test	Testing utilities	@EnableEmbeddedDatabase, EmbeddedTomcatContextLoader, AbstractWebFluxTest

Prerequisites

• Java 17 or later
• Maven 3.6+ (or use the included mvnw / mvnw.cmd wrapper)
• Spring Framework 6.0.x – 7.0.x (main branch) or 4.3.x – 5.3.x (1.x branch)

Getting Started

1. Import the BOM

Add microsphere-spring-dependencies to your <dependencyManagement> block so you never need to manage individual module versions:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.microsphere-projects</groupId>
            <artifactId>microsphere-spring-dependencies</artifactId>
            <version>${microsphere-spring.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Choose the version that matches your Spring Framework line:

Branch	Spring Framework compatibility	Latest version
main	6.0.x – 7.0.x	0.2.19
1.x	4.3.x – 5.3.x	0.1.19

2. Add individual modules

Include only the modules you need — no version required after importing the BOM:

<dependencies>
    <!-- Core context enhancements -->
    <dependency>
        <groupId>io.github.microsphere-projects</groupId>
        <artifactId>microsphere-spring-context</artifactId>
    </dependency>

    <!-- Spring MVC extensions (optional) -->
    <dependency>
        <groupId>io.github.microsphere-projects</groupId>
        <artifactId>microsphere-spring-webmvc</artifactId>
    </dependency>
</dependencies>

Usage Examples

Auto-refreshable property source — @ResourcePropertySource

@ResourcePropertySource extends Spring's @PropertySource with wildcard patterns, ordering, inheritance, and live reload when the underlying file changes.

@Configuration
@ResourcePropertySource(
        name = "app-config",
        value = "classpath*:/META-INF/config/*.properties",
        autoRefreshed = true   // reload whenever any matched file changes
)
public class AppConfig {
    @Autowired
    private Environment environment;
}

YAML and JSON property sources

@Configuration
@YamlPropertySource("classpath:/config/application.yaml")
@JsonPropertySource("classpath:/config/feature-flags.json")
public class AppConfig {
}

TTL caching — @EnableTTLCaching and @TTLCacheable

Add per-entry time-to-live to any Spring-managed cache (including Redis):

@Configuration
@EnableTTLCaching
public class CachingConfig {
}

// In a service bean:
@TTLCacheable(cacheNames = "products", ttl = 300, timeUnit = TimeUnit.SECONDS)
public Product findById(Long id) { ...}

Spring MVC extensions — @EnableWebMvcExtension

Enable handler method interception, web endpoint metadata collection, and more with a single annotation:

@Configuration
@EnableWebMvcExtension(
        interceptHandlerMethods = true,   // wrap controller methods
        registerWebEndpointMappings = true // expose endpoint metadata at startup
)
public class WebConfig {
}

Implement HandlerMethodInterceptor to add cross-cutting behavior around any controller invocation:

@Component
public class LoggingInterceptor implements HandlerMethodInterceptor {
    @Override
    public void beforeExecute(HandlerMethod handlerMethod, Object[] args, ...) {
        log.info("Invoking {}", handlerMethod.getMethod().getName());
    }
}

P6Spy JDBC monitoring — @EnableP6DataSource

Wrap every existing DataSource bean for transparent SQL tracing without changing application code:

@Configuration
@EnableP6DataSource
public class DataSourceConfig {
}

Google Guice integration — @EnableGuice

Allow Guice @Inject-annotated fields to be satisfied by Spring-managed beans:

@Configuration
@EnableGuice
public class IntegrationConfig {
}

Building from Source

You don't need to build from source to use the library. Only do this if you want to try unreleased changes or contribute to the project.

# Clone the repository
git clone https://github.com/microsphere-projects/microsphere-spring.git
cd microsphere-spring

# Linux / macOS
./mvnw package

# Windows
mvnw.cmd package

Run the full test suite:

# Linux / macOS
./mvnw verify

# Windows
mvnw.cmd verify

Documentation

Resource	Link
Interactive docs (DeepWiki)
Interactive docs (Zread)
GitHub Wiki	microsphere-spring wiki
Release notes	release-notes.md

JavaDoc

• microsphere-spring-context
• microsphere-spring-web
• microsphere-spring-webmvc
• microsphere-spring-webflux
• microsphere-spring-jdbc
• microsphere-spring-guice
• microsphere-spring-test

Getting Help

• Bug reports and feature requests — search the existing issues first; if not found, open a new issue and include your Spring and Java versions, a minimal reproducer, and the full stack trace if applicable
• Questions and discussions — use GitHub Discussions
• Interactive documentation — ask questions directly against the codebase via DeepWiki or Zread

Contributing

Contributions are welcome! Please:

1. Read the Code of Conduct before participating
2. Fork the repository and create a feature branch from main
3. Write or update tests for any changed behavior
4. Submit a pull request — the CI build (Maven + JUnit) must pass

Maintainers

Name	Role	Contact
Mercy Ma	Lead architect & developer	mercyblitz@gmail.com

The project is developed under the Microsphere Projects organisation.

License

Microsphere Spring is released under the Apache License 2.0.