Skip to content

README.md

Latest commit

 

History

History
289 lines (218 loc) · 20.7 KB

README.md

File metadata and controls

289 lines (218 loc) · 20.7 KB

Microsphere Spring

Microsphere Projects for Spring Framework

Ask DeepWiki Maven Build Codecov Maven License

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

  • 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.27
1.x 4.3.x – 5.3.x 0.1.27

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) Ask DeepWiki
Interactive docs (Zread) zread
GitHub Wiki microsphere-spring wiki
Release notes release-notes.md

JavaDoc

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

The project is developed under the Microsphere Projects organisation.

License

Microsphere Spring is released under the Apache License 2.0.