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/mybatis/spring-boot-starter 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.

GO — Healthy across all four use cases

• Last commit 1d ago
• 4 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 56% of recent commits

_{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 mybatis/spring-boot-starter repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mybatis/spring-boot-starter.

What it runs against: a local clone of mybatis/spring-boot-starter — 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 mybatis/spring-boot-starter | 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 ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mybatis/spring-boot-starter. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mybatis/spring-boot-starter.git
#   cd spring-boot-starter
#
# 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 mybatis/spring-boot-starter and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mybatis/spring-boot-starter(\\.git)?\\b" \\
  && ok "origin remote is mybatis/spring-boot-starter" \\
  || miss "origin remote is not mybatis/spring-boot-starter (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 "mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisAutoConfiguration.java" \\
  && ok "mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisAutoConfiguration.java" \\
  || miss "missing critical file: mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisAutoConfiguration.java"
test -f "mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisProperties.java" \\
  && ok "mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisProperties.java" \\
  || miss "missing critical file: mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisProperties.java"
test -f "mybatis-spring-boot-autoconfigure/pom.xml" \\
  && ok "mybatis-spring-boot-autoconfigure/pom.xml" \\
  || miss "missing critical file: mybatis-spring-boot-autoconfigure/pom.xml"
test -f "mybatis-spring-boot-autoconfigure/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports" \\
  && ok "mybatis-spring-boot-autoconfigure/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports" \\
  || miss "missing critical file: mybatis-spring-boot-autoconfigure/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports"
test -f "mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/SpringBootVFS.java" \\
  && ok "mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/SpringBootVFS.java" \\
  || miss "missing critical file: mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/SpringBootVFS.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 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/mybatis/spring-boot-starter"
  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).

MyBatis Spring Boot Starter provides zero-configuration Spring Boot autoconfiguration for MyBatis 3.5+, eliminating boilerplate XML and Java configuration. It automatically wires SqlSessionFactory, SqlSessionTemplate, and mapper interface scanning into Spring Boot applications, with support for both traditional XML mappers and modern annotation-based SQL definitions. Multi-module Maven structure: mybatis-spring-boot-autoconfigure/ contains the core Spring Boot autoconfiguration classes (MybatisAutoConfiguration, MybatisProperties, ConfigurationCustomizer) and registers via META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. Companion modules include the main starter POM and a separate test-autoconfigure module for testing support.

Java developers building Spring Boot applications who want to use MyBatis as their SQL mapping framework without manual bean registration or extensive XML configuration. Teams migrating from Spring JDBC or pure Hibernate who prefer MyBatis's explicit SQL control.

Production-ready and actively maintained. The project targets Spring Boot 4.0+ (Java 17+) on master with multiple supported versions (2.3.x through 4.0.x) maintained in parallel. It has comprehensive CI/CD (GitHub Actions workflows for CI, CodeQL, Sonar, Coveralls) and Apache 2.0 licensing from the official MyBatis organization.

Standard open source risks apply.

Active development on master branch for Spring Boot 4.0 support. Version 4.0.2-SNAPSHOT is in progress (visible in pom.xml). Parallel maintenance of 3.0.x and 2.3.x branches visible in CI workflows. GitHub Actions workflows monitor quality through CodeQL security scanning, Sonar analysis, and Coveralls coverage reporting.

Clone the repo, build with Maven: git clone https://github.com/mybatis/spring-boot-starter.git && cd spring-boot-starter && ./mvnw clean install. This builds all modules including the autoconfigure JAR. For testing, run ./mvnw test in the mybatis-spring-boot-autoconfigure/ directory.

Daily commands: This is a library, not an executable project. Integration tests run via ./mvnw test. For a working example, create a new Spring Boot app with the starter dependency and place mapper XML in classpath:mapper/ or use @Mapper annotations on interfaces. The starter auto-scans and registers them.

• mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisAutoConfiguration.java — Core Spring Boot autoconfiguration class that bootstraps MyBatis integration; every contributor must understand how SqlSessionFactory and mappers are wired.
• mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisProperties.java — Configuration properties binding class (@ConfigurationProperties); essential for understanding all tunable MyBatis settings in Spring Boot.
• mybatis-spring-boot-autoconfigure/pom.xml — Maven POM for autoconfigure module; defines all dependency versions and Spring Boot compatibility constraints.
• mybatis-spring-boot-autoconfigure/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports — Spring Boot 3.2+ autoconfiguration entry point; determines which autoconfigurations are enabled at startup.
• mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/SpringBootVFS.java — Virtual filesystem abstraction for Spring Boot classpath scanning; critical for locating mapper XML and domain classes.
• mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisLanguageDriverAutoConfiguration.java — Autoconfiguration for custom MyBatis language drivers; enables dynamic SQL extension points.

Add a Custom Type Handler

1. Create your TypeHandler class implementing MyBatis TypeHandler interface (mybatis-spring-boot-autoconfigure/src/test/java/org/mybatis/spring/boot/autoconfigure/handler/DummyTypeHandler.java)
2. Annotate with @Component or register as a @Bean in your application configuration (mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisAutoConfiguration.java)
3. MyBatis autoconfiguration auto-discovers type handlers via Spring component scan and registers them with Configuration

Customize MyBatis Configuration at Runtime

1. Create a class implementing the ConfigurationCustomizer interface (mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/ConfigurationCustomizer.java)
2. Register your customizer as a @Bean in your Spring configuration (mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisAutoConfiguration.java)
3. The autoconfiguration will invoke customize() method on all ConfigurationCustomizer beans before SqlSessionFactory is created

Add a Custom Language Driver

1. Implement MyBatis LanguageDriver interface for your custom SQL syntax (mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisLanguageDriverAutoConfiguration.java)
2. Register as a @Bean; the language driver autoconfiguration will detect and register it (mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisLanguageDriverAutoConfiguration.java)
3. Reference your driver in mapper XML files or annotations with the lang attribute

Configure MyBatis Properties in application.yml

1. Review available properties bound by MybatisProperties class (mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisProperties.java)
2. Add mybatis.* prefixed properties to application.yml (e.g., mybatis.config-location, mybatis.mapper-locations, mybatis.type-handlers-package)
3. Properties are automatically resolved and passed to SqlSessionFactory configuration

• Spring Boot Autoconfiguration — Provides zero-configuration bootstrapping of MyBatis into Spring Boot applications; enables auto-discovery of type handlers, mappers, and language drivers via component scanning.
• MyBatis 3.5+ with MyBatis-Spring 4.0 — Core ORM framework for SQL mapping; MyBatis-Spring provides Spring integration (SqlSessionTemplate, MapperFactoryBean, mapper scanning).
• @ConfigurationProperties binding — Type-safe externalized configuration for all MyBatis settings; enables property validation and IDE autocomplete in application.yml.
• Spring ResourcePatternResolver (SpringBootVFS) — Abstracts classpath scanning for XML mappers and domain class packages; works seamlessly with Spring Boot's nested JAR structure and custom class loaders.

• Conditional autoconfiguration based on presence of SqlSessionFactory on classpath

  • Why: Avoids forcing MyBatis dependency if not used; allows opt-in integration.
  • Consequence: Users must explicitly add mybatis-spring-boot-starter dependency; reduces surprise bean creation.

• SPI hooks (ConfigurationCustomizer, SqlSessionFactoryBeanCustomizer) instead of direct configuration mutations

  • Why: Allows multiple beans to customize configuration without ordering conflicts; follows Spring's bean lifecycle conventions.
  • Consequence: Configuration customization is distributed across multiple beans; harder to debug if order matters.

• Mapper scanning via MapperScannerConfigurer rather than manual @Mapper annotation

  • Why: Supports legacy XML-based mapper definitions and avoids annotation pollution.
  • Consequence: Requires explicit basePackages configuration; not discoverable via classpath scanning alone.

• Does not provide ORM-level abstraction (no JPA replacement); MyBatis remains low-level SQL mapping.
• Does not handle transaction management explicitly; delegates to Spring's TransactionManager.
• Does not generate mappers dynamically from domain classes; requires explicit XML or annotation-based mapper definitions.
• Does not provide connection pooling; relies on Spring Boot DataSource autoconfiguration (HikariCP, Tomcat pool, etc.).

1. Mapper location scanning requires classpath:mapper/** pattern by default—placing XMLs elsewhere requires explicit spring.mybatis.mapper-locations config. 2. Version coupling is strict: Spring Boot 4.0 requires Java 17+ and MyBatis-Spring 4.0; mixing versions (e.g., Spring Boot 2.7 with Spring Boot 3 starter) fails silently at runtime. 3. Multiple MapperScannerConfigurer or @MapperScan annotations can conflict with the autoconfigured scanner; use only one approach. 4. MyBatis type handlers and interceptors must be registered via ConfigurationCustomizer beans, not direct Configuration mutation, to integrate with the autoconfigured SqlSessionFactory.

• Spring Boot Autoconfiguration (@AutoConfiguration) — Understanding how MybatisAutoConfiguration conditionally registers beans (via @ConditionalOnClass, @ConditionalOnProperty) is essential to knowing when the starter activates and how to override it.
• MapperScannerConfigurer & @Mapper annotation scanning — This starter automatically configures MyBatis mapper interface discovery; knowing how it scans basePackages and @Mapper annotations helps debug missing mapper beans.
• SqlSessionFactory bean lifecycle & customization hooks — MybatisAutoConfiguration creates and customizes the central SqlSessionFactory bean; ConfigurationCustomizer and SqlSessionFactoryBeanCustomizer are the extension points for adding interceptors, type handlers, or plugins.
• Spring Resource abstraction & classpath scanning — The starter uses Spring's ResourceLoader and patterns like classpath:mapper/** to locate MyBatis XML mapper files; understanding classpath: vs classpath*: is critical for config.
• Conditional bean registration with @ConditionalOn* annotations — The autoconfiguration uses @ConditionalOnClass(SqlSessionFactory), @ConditionalOnMissingBean, and @ConditionalOnProperty to avoid conflicts and allow opt-out via config.
• VirtualFileSystem (MyBatis ClassLoaderWrapper pattern) — SpringBootVFS bridges MyBatis's resource loading with Spring Boot's layered JAR and custom ClassLoader hierarchy; critical for native image and modular app support.
• Configuration properties via @ConfigurationProperties — MybatisProperties binds spring.mybatis.* YAML/properties to Java objects; understanding nested properties, defaults, and validation is essential for end-user configuration.

• mybatis/mybatis-3 — Core MyBatis library; this starter wraps its configuration. Required dependency.
• mybatis/mybatis-spring — Spring integration library that MyBatis Spring Boot Starter depends on; provides SqlSessionFactory and MapperScannerConfigurer beans that the autoconfiguration wraps.
• spring-projects/spring-boot — Parent framework; autoconfiguration pattern and @ConditionalOn* annotations come from here.
• mybatis/mybatis-spring-boot-starter — The main starter POM that users add to their build; this repo IS that—primary entry point for users.

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 integration tests for MybatisAutoConfiguration with various Spring Boot versions

The repo has CI workflows (ci.yaml) but there's no visible test directory structure shown for the autoconfigure module. The MybatisAutoConfiguration.java class is a critical entry point that needs comprehensive integration tests covering different Spring Boot configurations, datasource setups, and language driver combinations. This ensures compatibility across versions and prevents regressions.

• [ ] Create mybatis-spring-boot-autoconfigure/src/test/java/org/mybatis/spring/boot/autoconfigure directory structure
• [ ] Add MybatisAutoConfigurationTest.java with tests for SqlSessionFactory bean creation, mapper scanner registration, and custom configuration application
• [ ] Add MybatisLanguageDriverAutoConfigurationTest.java for language driver discovery and registration
• [ ] Add test cases for MybatisDependsOnDatabaseInitializationDetector with different database initialization strategies
• [ ] Add test configuration files in src/test/resources for different scenarios (with/without type aliases, custom interceptors, etc.)

Add tests for MybatisProperties configuration binding with validation

MybatisProperties.java is a critical @ConfigurationProperties class but there's no visible test coverage shown. This class deserves dedicated tests to verify that Spring Boot's configuration metadata (additional-spring-configuration-metadata.json) correctly maps to all properties, and that nested objects (like ConfigurationCustomizer) are properly bound.

• [ ] Create mybatis-spring-boot-autoconfigure/src/test/java/org/mybatis/spring/boot/autoconfigure/MybatisPropertiesTest.java
• [ ] Add tests for property binding from application.yml/properties files using @SpringBootTest
• [ ] Add tests for validation of mybatis.* properties including type, default values, and edge cases
• [ ] Add tests verifying the additional-spring-configuration-metadata.json matches actual MybatisProperties fields
• [ ] Add tests for nested configuration objects and their defaults

Add unit tests for SpringBootVFS class with various classpath scenarios

The SpringBootVFS.java class extends MyBatis' VirtualFileSystem to work with Spring Boot's resource loading but has no visible dedicated tests. This utility is critical for mapper discovery and should be tested against different Spring Boot resource scenarios including JAR execution, IDE execution, and custom resource loaders.

• [ ] Create mybatis-spring-boot-autoconfigure/src/test/java/org/mybatis/spring/boot/autoconfigure/SpringBootVFSTest.java
• [ ] Add tests for resource resolution using Spring's ResourcePatternResolver in different contexts
• [ ] Add tests for classpath scanning in JAR files and exploded directories
• [ ] Add tests for ResourceLoader fallback behavior and error handling
• [ ] Add tests for compatibility with Spring Boot's custom ResourceLoaders

• Add test coverage for MybatisDependsOnDatabaseInitializationDetector.java—this class handles initialization ordering with Spring Boot schema initialization but appears to lack dedicated unit tests in the Groovy test suite.
• Improve documentation in ConfigurationCustomizer.java interface with concrete example showing how to register custom MyBatis interceptors or type handlers; currently lacks usage examples.
• Add integration test validating that spring.mybatis.mapper-locations correctly handles Spring Resource patterns like classpath*:mappers/**/*.xml across JAR and file system contexts.

The MyBatis Spring Boot Starter project demonstrates reasonable security practices with automated CI/CD workflows (CodeQL, Sonar, Coveralls) and use of Maven Wrapper for build consistency. However, the analysis is limited by incomplete visibility into critical files (truncated POM, no source code review). Primary concerns are: (1) incomplete dependency verification due to truncated POM file, (2) potential SQL injection risks in MyBatis configuration if parameterized queries aren't enforced, (3) lack of visible input validation patterns, and (4) no confirmation of secrets management best practices. The project uses established security scanning tools (CodeQL, Sonar) which is positive. Recommend: complete POM review, OWASP dependency scanning in CI/CD, explicit documentation of secure MyBatis mapping patterns, and verification of sensitive property handling in MybatisProperties.

• Medium · Incomplete Dependency Information — pom.xml (mybatis-spring-boot-autoconfigure/pom.xml). The POM file provided appears truncated at the optional dependencies section. The MyBatis dependency declaration is cut off ('my'), making it impossible to verify if all dependencies are properly versioned and free from known vulnerabilities. This incomplete configuration could mask dependency issues. Fix: Ensure complete pom.xml is available for analysis. Use 'mvn dependency:check' or OWASP Dependency-Check to identify vulnerable dependencies. Maintain explicit version pinning for all dependencies.
• Low · Maven Wrapper Configuration — .mvn/wrapper/MavenWrapperDownloader.java. The project uses Maven Wrapper (.mvn/wrapper/). While this is a best practice for build consistency, the wrapper JAR files should be verified to ensure they haven't been tampered with. MavenWrapperDownloader.java could be a vector if it downloads from insecure sources. Fix: Verify that maven-wrapper.properties specifies HTTPS URLs only. Run 'mvn wrapper:wrapper' to regenerate wrapper with latest secure version. Include wrapper verification in CI/CD pipeline.
• Low · No Evidence of Input Validation Framework — mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/. While the codebase appears to be a Spring Boot autoconfiguration module for MyBatis integration, there is no visible evidence of input validation patterns in the file structure. MyBatis XML mappers can be vulnerable to SQL injection if parameterized queries are not used consistently. Fix: Ensure all MyBatis mappers use parameterized queries with #{} syntax instead of ${} for user input. Add validation in ConfigurationCustomizer and SqlSessionFactoryBeanCustomizer classes. Document secure mapping practices.
• Low · Missing Security Configuration Documentation — mybatis-spring-boot-autoconfigure/src/main/java/org/mybatis/spring/boot/autoconfigure/MybatisProperties.java. The MybatisProperties.java file likely contains configuration options, but without visibility into its contents, it's unclear if security-sensitive properties (DB passwords, connection strings) are properly handled. Spring Boot properties can inadvertently expose secrets if not marked as @Sensitive. Fix: Mark sensitive properties with @Sensitive annotation in MybatisProperties. Use Spring Cloud Config or external vaults (HashiCorp Vault, AWS Secrets Manager) for credential management. Never log sensitive configuration values.
• Low · No Visible HTTPS/TLS Configuration — .mvn/settings.xml, .mvn/maven.config. The .mvn/maven.config and settings.xml files are present but not shown. There's no visible enforcement of HTTPS for Maven Central or dependency repositories, which could lead to MITM attacks during dependency downloads. Fix: Configure Maven to require HTTPS repositories. Add <blocked>true</blocked> for HTTP repositories. Use repository mirrors with HTTPS. Consider using Maven Dependency Check or Sonatype Nexus for artifact scanning.

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.