If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/javastacks/spring-boot-best-practice shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Solo project — review before adopting

• Last commit 2mo ago
• Apache-2.0 licensed
• Tests present
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live javastacks/spring-boot-best-practice repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/javastacks/spring-boot-best-practice.

What it runs against: a local clone of javastacks/spring-boot-best-practice — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in javastacks/spring-boot-best-practice | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 90 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of javastacks/spring-boot-best-practice. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/javastacks/spring-boot-best-practice.git
#   cd spring-boot-best-practice
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of javastacks/spring-boot-best-practice and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "javastacks/spring-boot-best-practice(\\.git)?\\b" \\
  && ok "origin remote is javastacks/spring-boot-best-practice" \\
  || miss "origin remote is not javastacks/spring-boot-best-practice (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "pom.xml" \\
  && ok "pom.xml" \\
  || miss "missing critical file: pom.xml"
test -f "javastack-spring-boot-starter/src/main/java/cn/javastack/springboot/starter/config/TestServiceAutoConfiguration.java" \\
  && ok "javastack-spring-boot-starter/src/main/java/cn/javastack/springboot/starter/config/TestServiceAutoConfiguration.java" \\
  || miss "missing critical file: javastack-spring-boot-starter/src/main/java/cn/javastack/springboot/starter/config/TestServiceAutoConfiguration.java"
test -f "javastack-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports" \\
  && ok "javastack-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports" \\
  || miss "missing critical file: javastack-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports"
test -f "spring-boot-aop/src/main/java/cn/javastack/springboot/aop/aspect/CalcAspect.java" \\
  && ok "spring-boot-aop/src/main/java/cn/javastack/springboot/aop/aspect/CalcAspect.java" \\
  || miss "missing critical file: spring-boot-aop/src/main/java/cn/javastack/springboot/aop/aspect/CalcAspect.java"
test -f "spring-boot-actuator/src/main/java/cn/javastack/springboot/actuator/endpoint/TestEndpoint.java" \\
  && ok "spring-boot-actuator/src/main/java/cn/javastack/springboot/actuator/endpoint/TestEndpoint.java" \\
  || miss "missing critical file: spring-boot-actuator/src/main/java/cn/javastack/springboot/actuator/endpoint/TestEndpoint.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 90 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~60d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/javastacks/spring-boot-best-practice"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A comprehensive Spring Boot 4.x best-practices reference repository with 35+ runnable example modules demonstrating production patterns across auto-configuration, REST services, messaging (ActiveMQ/RabbitMQ/Kafka), data access (JPA/MyBatis/MongoDB), caching, scheduling, Docker deployment, and Spring Cloud integration. It serves as both a learning resource and an upgrade/migration guide for Spring Boot 4.x and Spring Framework 7.x. Maven multi-module monorepo: root pom.xml aggregates 35+ topic-specific modules (spring-boot-web, spring-boot-redis, spring-boot-kafka, javastack-spring-boot-starter, etc.). Each module is self-contained with its own src/main/java, src/main/resources, and application.yml configuration. The javastack-spring-boot-starter/ and javastack-spring-boot-starter-sample/ pair demonstrates custom starter development; auto-configuration is configured via META-INF/spring.factories and META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports.

Java developers and architects learning Spring Boot or upgrading to Spring Boot 4.x; developers building microservices who need reference implementations of real-world patterns (custom starters, multi-datasource setups, message queue integration); DevOps engineers configuring containerized Spring applications with Docker and native images.

Actively maintained and production-ready. The project has been updated to support Spring Boot 4.0.3 and Java 21, indicating ongoing maintenance. Organized as a well-structured Maven multi-module project with 35+ example modules covering real-world scenarios. No CI/CD pipeline or automated test suite visible in the file listing, which is a minor gap for a reference project, but the breadth of examples and recent Spring 4.x support suggest active stewardship.

Low-to-moderate risk. As a learning/reference repository rather than a framework library, it has no published dependencies to break downstream users. However, without visible test automation or CI pipeline, example quality relies on manual verification. The tight coupling to Spring Boot 4.0.3 (Spring Framework 7.x, Java 21) means examples may become stale quickly if Spring versions advance; contributors should verify compatibility. Single-maintainer risk is typical for Chinese open-source educational projects.

No recent commit history or PR data visible in the provided file listing. The project baseline is Spring Boot 4.0.3 (released early 2024), suggesting it was updated within the past year. The presence of both legacy spring.factories and modern AutoConfiguration.imports registration mechanisms indicates the maintainer is supporting both old and new Spring Boot versions during the transition period.

git clone https://github.com/javastacks/spring-boot-best-practice.git
cd spring-boot-best-practice
mvn clean install
cd spring-boot-quick-start  # or any specific module
mvn spring-boot:run

Daily commands: Most modules run identically: cd <module-name> && mvn spring-boot:run. Web modules (spring-boot-web, spring-boot-activemq) start an embedded Tomcat on port 8080 by default; check the module's application.yml for custom ports or configuration. The custom starter (javastack-spring-boot-starter) must be built first (mvn clean install) before javastack-spring-boot-starter-sample can run, since the sample depends on the starter artifact.

• pom.xml — Root Maven POM defining the multi-module project structure, Spring Boot 4.0.3 baseline, and dependency management for all 600 files.
• javastack-spring-boot-starter/src/main/java/cn/javastack/springboot/starter/config/TestServiceAutoConfiguration.java — Core auto-configuration example demonstrating Spring Boot's @Configuration and @ConditionalOnClass patterns essential for understanding starter mechanics.
• javastack-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports — Spring Boot 4.x service provider interface for auto-configuration discovery; replaces legacy spring.factories as the load-bearing entry point.
• spring-boot-aop/src/main/java/cn/javastack/springboot/aop/aspect/CalcAspect.java — Foundational AOP aspect implementation showing @Aspect, @Pointcut, and interceptor patterns used across middleware modules.
• spring-boot-actuator/src/main/java/cn/javastack/springboot/actuator/endpoint/TestEndpoint.java — Custom actuator endpoint demonstrating observability, metrics, and health-check patterns critical for production readiness.
• spring-boot-admin-server/src/main/java/cn/javastack/springboot/admin/server/Application.java — Administrative UI bootstrap showing integration of Spring Boot Admin for runtime monitoring and management across the fleet.
• javastack-spring-boot-starter-sample/src/main/resources/application.yml — Sample configuration demonstrating YAML property binding and externalized configuration patterns expected in all sub-modules.

Add a Custom Auto-Configuration Module

1. Create a new Maven module folder, e.g., spring-boot-custom-feature/ (pom.xml)
2. Add a module POM with spring-boot-starter-* dependencies matching your feature (web, data, messaging, etc.) (spring-boot-custom-feature/pom.xml)
3. Create an auto-configuration class mirroring TestServiceAutoConfiguration.java: use @Configuration, @Bean, @ConditionalOnClass, @ConditionalOnMissingBean (spring-boot-custom-feature/src/main/java/cn/javastack/springboot/feature/config/CustomAutoConfiguration.java)
4. Register the auto-configuration in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports (spring-boot-custom-feature/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports)
5. Create a sample consumer module following javastack-spring-boot-starter-sample pattern; declare your module as a dependency in its pom.xml (spring-boot-custom-feature-sample/pom.xml)

Add a Custom Actuator Endpoint

1. In the target module (e.g., spring-boot-actuator), create a new class annotated with @Endpoint and @Component (spring-boot-actuator/src/main/java/cn/javastack/springboot/actuator/endpoint/CustomEndpoint.java)
2. Define @ReadOperation, @WriteOperation, or @DeleteOperation methods matching TestEndpoint.java patterns (spring-boot-actuator/src/main/java/cn/javastack/springboot/actuator/endpoint/CustomEndpoint.java)
3. Update spring-boot-actuator/src/main/resources/application.yml to expose the new endpoint: management.endpoints.web.exposure.include=info,health,custom (spring-boot-actuator/src/main/resources/application.yml)
4. Optionally add metrics or observations in the endpoint using Micrometer patterns shown in MetricsConfig.java (spring-boot-actuator/src/main/java/cn/javastack/springboot/actuator/metrics/MetricsConfig.java)

Add a New AOP Aspect for Cross-Cutting Concerns

1. In spring-boot-aop module, create a new aspect class annotated with @Aspect and @Component (spring-boot-aop/src/main/java/cn/javastack/springboot/aop/aspect/CustomAspect.java)
2. Define @Pointcut expressions targeting controller methods, service methods, or specific annotations following CalcAspect.java pattern (spring-boot-aop/src/main/java/cn/javastack/springboot/aop/aspect/CustomAspect.java)
3. Implement @Before, @After, @Around, or @AfterReturning methods to intercept and decorate joinpoints (spring-boot-aop/src/main/java/cn/javastack/springboot/aop/aspect/CustomAspect.java)
4. Ensure spring-boot-aop/pom.xml includes spring-boot-starter-aop dependency for proxy creation (spring-boot-aop/pom.xml)
5. Create a

Spring Boot 4.x baseline: Examples assume Java 21+ and Spring Framework 7.x; running on older JDK versions will fail. Dual configuration formats: Both META-INF/spring.factories and META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports are present in the starter module—use .imports for new code (Spring Boot 3.0+), .factories only for legacy compatibility. Explicit dependency declarations: Each module's pom.xml must explicitly declare feature dependencies (e.g., spring-boot-starter-webflux, spring-boot-starter-data-redis); they are not inherited from the root POM. Application starter class naming: The root cn.javastack.springboot.starter.Application in the starter module is a bare stub; actual runnable examples are in sibling modules with their own Application classes. Missing profiles for test databases: The spring-boot-jpa, spring-boot-datasource, and other data-access modules do not show H2/test container profiles in the snippet—verify application.yml for database connectivity requirements before running.

• Spring Boot Auto-Configuration — Core Spring Boot mechanism demonstrated in TestServiceAutoConfiguration.java and .imports files; essential for understanding how Spring Boot intelligently configures beans based on classpath and properties
• Conditional Bean Registration (@ConditionalOnClass, @ConditionalOnProperty) — Pattern used in auto-configuration classes to enable/disable features based on classpath presence or configuration properties; critical for writing optional starters
• Custom Spring Boot Starter Development — The javastack-spring-boot-starter pair demonstrates creating reusable, distributable Spring Boot modules with auto-configuration; essential skill for framework authors and enterprise tool builders
• Application Context Hierarchies & Multi-Datasource Routing — The spring-boot-datasource module demonstrates routing requests across multiple database connections; critical for enterprise systems handling sharded or multi-tenant data
• Spring Bean Lifecycle & Lifecycle Callbacks (@PostConstruct, InitializingBean, DisposableBean) — Demonstrated in starter configuration and messaging examples; essential for understanding when beans are created, configured, and destroyed, especially for resource cleanup
• Message-Driven Beans & Async Processing (JmsTemplate, @JmsListener, @RabbitListener) — Core patterns in ActiveMQ, RabbitMQ, and Kafka modules; essential for building event-driven and asynchronous microservices
• Spring Data Repository Abstraction (CrudRepository, JpaRepository) — Underlying framework for JPA, MongoDB, and Redis data-access modules; provides uniform query and CRUD semantics across different data stores

• spring-projects/spring-boot — Official Spring Boot repository; source of truth for auto-configuration, starter conventions, and framework behavior demonstrated in this project
• spring-cloud/spring-cloud-examples — Companion set of microservice patterns (service discovery, config servers, circuit breakers) that build on top of Spring Boot foundations covered here
• alibaba/spring-cloud-alibaba — Chinese ecosystem variant adding Nacos, Sentinel, and Dubbo integrations to Spring Cloud; users of this repo often transition to cloud-native patterns
• baomidou/mybatis-plus — Companion to the spring-boot-mybatis-plus module; enhanced ORM framework demonstrating advanced Spring Boot data-access patterns
• spring-projects/spring-data-examples — Official Spring Data reference implementations (Redis, MongoDB, JPA, Elasticsearch) mirrored in multiple modules of this repository

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Spring Boot 4.x migration guide and compatibility tests for javastack-spring-boot-starter

The repo claims adaptation to Spring Boot 4.x but the javastack-spring-boot-starter module uses the legacy spring.factories approach. Spring Boot 4.x deprecated this in favor of org.springframework.boot.autoconfigure.AutoConfiguration.imports. Adding comprehensive migration documentation and test cases would help contributors understand the upgrade path and verify backward compatibility.

• [ ] Create comprehensive migration guide document comparing spring.factories vs AutoConfiguration.imports in javastack-spring-boot-starter/
• [ ] Add integration tests in javastack-spring-boot-starter/src/test/ verifying TestServiceAutoConfiguration loads correctly in both Spring Boot 3.x and 4.x contexts
• [ ] Update javastack-spring-boot-starter-sample to validate the starter works end-to-end with Spring Boot 4.0.3 baseline
• [ ] Document version compatibility matrix in README.md showing which Spring Boot versions each example targets

Add GitHub Actions CI workflow for multi-version Spring Boot testing

With Spring Boot 4.x as baseline and legacy support claims, there's no visible CI configuration to verify all modules build and tests pass across Spring Boot versions. This prevents regressions and ensures examples remain valid.

• [ ] Create .github/workflows/maven-test.yml to run 'mvn clean test' matrix across Spring Boot 3.2.x, 3.3.x, and 4.0.x
• [ ] Ensure the workflow tests each module (spring-boot-actuator, spring-boot-activemq, javastack-spring-boot-starter, etc.) independently
• [ ] Add a Java 21 baseline requirement check given the baseline Java version mentioned in README
• [ ] Include test coverage reporting for core modules in the workflow output

Create missing unit and integration test modules for spring-boot-actuator example

The spring-boot-actuator module demonstrates custom endpoints (TestEndpoint), metrics (MetricsConfig), and observations (IndexObservation) but has no visible src/test directory. Adding comprehensive tests would provide contributors with testing patterns for Spring Boot observability features.

• [ ] Create spring-boot-actuator/src/test/java/cn/javastack/springboot/actuator/endpoint/ with unit tests for TestEndpoint covering all exposed operations
• [ ] Add spring-boot-actuator/src/test/java/cn/javastack/springboot/actuator/observation/ tests verifying IndexObservation correctly instruments requests
• [ ] Create spring-boot-actuator/src/test/java/cn/javastack/springboot/actuator/metrics/ integration tests validating MetricsConfig metrics are properly registered and exported
• [ ] Add spring-boot-actuator/src/test/resources/application-test.yml with test-specific actuator endpoint configuration

• Add integration tests for the custom starter (javastack-spring-boot-starter): currently no visible test directory under the starter module. Create src/test/java/cn/javastack/springboot/starter/config/TestServiceAutoConfigurationTest.java using @SpringBootTest to verify auto-configuration conditional logic and bean registration.
• Document Spring Boot 4.x migration differences: create a MIGRATION.md file explaining breaking changes from Spring Boot 3.x (e.g., removal of spring.factories preference for .imports, Java 21 minimum, Jakarta EE namespace), with before/after code snippets from actual modules.
• Add a new module spring-boot-feign demonstrating Spring Cloud OpenFeign client patterns (declarative REST client); this is a common microservice tool mentioned in Spring Cloud ecosystem but not present in the current 35+ modules. Follow the pattern of spring-boot-rest-services but using @FeignClient annotations.

• High · Permissive Security Configuration in Admin Client — spring-boot-admin-client/SecurityPermitAllConfig.java. The file 'spring-boot-admin-client/src/main/java/cn/javastack/springboot/admin/client/SecurityPermitAllConfig.java' suggests a security configuration that permits all access. This is a dangerous practice that bypasses Spring Security's protection mechanisms entirely. This configuration should only be used in development/testing environments, never in production. Fix: Replace permissive security configuration with proper authorization rules. Implement role-based access control (RBAC) and use @EnableWebSecurity with custom SecurityFilterChain beans that define specific endpoint protections. Never use permitAll() for all requests in production.
• Medium · Potential Insecure Deserialization Risk — spring-boot-activemq/src/main/resources/application.yml. The presence of ActiveMQ integration (spring-boot-activemq module) combined with permissive security configurations suggests potential exposure to deserialization attacks. ActiveMQ's default configuration can be vulnerable to remote code execution through malicious serialized objects if not properly configured. Fix: Configure ActiveMQ with serialization filters to only allow trusted classes. Set 'org.apache.activemq.openwire.OpenWireFormat.maxInactivityDuration' and implement proper message validation. Use Spring's message converter with explicit type trust lists.
• Medium · Missing Dependency Version Management — pom.xml (root and submodules). The pom.xml file specifies dependencies without explicit version pinning for the parent project. This can lead to transitive dependency vulnerabilities if parent versions are updated without proper security review. The Spring Boot 4.x baseline should have all dependencies explicitly verified for known CVEs. Fix: Use a centralized dependency management approach with explicit version specifications. Implement Maven dependency management sections to lock critical dependencies. Run regular security scans using 'mvn dependency-check' or similar tools to identify CVEs.
• Medium · Actuator Endpoint Exposure Risk — spring-boot-actuator/config/SecurityConfig.java and endpoint/TestEndpoint.java. The spring-boot-actuator module exposes custom endpoints and metrics (TestEndpoint.java, MetricsConfig.java) with unclear access controls. Actuator endpoints can expose sensitive system information including environment variables, thread dumps, and heap dumps if not properly secured. Fix: Explicitly configure actuator endpoint security using 'management.endpoints.web.exposure.exclude' and 'management.endpoints.web.exposure.include'. Implement authentication/authorization for all actuator endpoints. Set 'management.endpoints.web.base-path' to a non-standard path and use network-level access controls.
• Medium · Spring Boot 4.x Legacy Configuration Files — javastack-spring-boot-starter/src/main/resources/META-INF/spring.factories. The presence of 'META-INF/spring.factories' indicates legacy Spring Boot auto-configuration approach. Spring Boot 4.x should use 'META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports' exclusively. Mixed usage can lead to unexpected behavior and potential security misconfigurations. Fix: Migrate from spring.factories to AutoConfiguration.imports. Remove the legacy spring.factories file and ensure all auto-configurations are properly registered in the imports file using the modern approach.
• Low · Missing CSRF Protection Configuration — spring-boot-actuator/controller/LoginController.java and config/SecurityConfig.java. The LoginController and SecurityConfig classes do not show explicit CSRF protection configuration. While Spring Security enables CSRF by default for state-changing operations, explicit configuration documentation is missing, which could lead to misconfiguration in similar projects. Fix: Explicitly configure CSRF protection in SecurityConfig with proper token validation. Document CSRF configuration in all SecurityFilterChain beans. Implement SameSite cookie attributes for additional protection.
• Low · No Evidence of Input Validation Framework — spring-boot-actuator/pojo/User.java and similar model classes. The User.java POJO and other model classes lack visible validation annotations (@NotNull, @Email, @ValidPassword, etc.). This increases the risk of accepting invalid input that could bypass business logic or cause application errors. Fix: Implement comprehensive input validation using Jakarta Bean Validation (formerly JSR-380

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.