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/tuguangquan/mybatis 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

• 14 active contributors
• Distributed ownership (top contributor 40% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 4y ago

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

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tuguangquan/mybatis(\\.git)?\\b" \\
  && ok "origin remote is tuguangquan/mybatis" \\
  || miss "origin remote is not tuguangquan/mybatis (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 "src/main/java/org/apache/ibatis/binding/MapperProxy.java" \\
  && ok "src/main/java/org/apache/ibatis/binding/MapperProxy.java" \\
  || miss "missing critical file: src/main/java/org/apache/ibatis/binding/MapperProxy.java"
test -f "src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java" \\
  && ok "src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java" \\
  || miss "missing critical file: src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java"
test -f "src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java" \\
  && ok "src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java" \\
  || miss "missing critical file: src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java"
test -f "src/main/java/org/apache/ibatis/builder/annotation/MapperAnnotationBuilder.java" \\
  && ok "src/main/java/org/apache/ibatis/builder/annotation/MapperAnnotationBuilder.java" \\
  || miss "missing critical file: src/main/java/org/apache/ibatis/builder/annotation/MapperAnnotationBuilder.java"
test -f "src/main/java/org/apache/ibatis/cache/Cache.java" \\
  && ok "src/main/java/org/apache/ibatis/cache/Cache.java" \\
  || miss "missing critical file: src/main/java/org/apache/ibatis/cache/Cache.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 1439 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1409d)"
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/tuguangquan/mybatis"
  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).

This is a Chinese-annotated source code repository of Apache MyBatis 3.3.0, a Java ORM framework that maps objects to SQL statements and stored procedures. It decouples SQL from Java code using XML descriptors or annotations, making relational database interactions simpler than traditional ORM tools. The core value is enabling developers to write explicit, optimized SQL while maintaining type-safe Java bindings. Monolithic Java JAR structure organized into 18 logical modules under src/main/java/org/apache/ibatis/: logging adapters, parsing, type handlers, reflection utilities, data sources, transactions, session management, SQL builders, mappers, scripting engines, annotations, executors, and plugins. Each module follows the Adapter design pattern for pluggability (e.g., org.apache.ibatis.logging/* supports SLF4J, Log4j, JDK14, or no-op).

Java developers learning MyBatis internals, and Chinese-speaking engineers who prefer source code documentation in their native language. Contributors to the MyBatis project itself, and teams building custom extensions or debugging deep framework behavior.

This is a mature, production-ready framework (MyBatis 3.3.0 released in 2014), but this specific annotated fork is a learning resource, not the canonical source. The official MyBatis project has 2.4k+ GitHub stars and active maintenance; this fork focuses on educational value rather than new features. Suitable for reference and study, not for deploying as a library.

This is a fork with historical annotations (2014-era version), not the current MyBatis release (now at 3.5+). Using this in production introduces version lag and missing security patches. Single-maintainer learning project with no CI/CD indicators (.travis.yml exists but integration status unclear), and no recent commit metadata visible to confirm activity level.

This is a static educational snapshot, not an active development project. The README points readers to learning resources (Jianshu blog posts on adapter patterns, XML parsing, type handling). The parent POM references mybatis-parent version 32-SNAPSHOT, indicating it tracks a development branch of the official MyBatis project.

Clone and import into Maven: git clone https://github.com/tuguangquan/mybatis.git && cd mybatis && mvn clean install. Requires Maven 3.x and JDK 6+. Then import the mybatis-parent module from https://github.com/mybatis/parent to satisfy parent POM dependency (version 32-SNAPSHOT).

Daily commands: mvn clean package builds the JAR. No runnable demo server—this is a library. To test: mvn test (junit tests exist under implied src/test). To explore: import into IDE and trace through org.apache.ibatis.reflection.MetaObjectTest (mentioned in README as entry point) or unit tests under binding, builder, and executor modules.

• src/main/java/org/apache/ibatis/binding/MapperProxy.java — Core JDK dynamic proxy implementation that intercepts all mapper method calls; essential for understanding how MyBatis translates annotation/XML definitions into executable SQL.
• src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java — Entry point for parsing mybatis-config.xml files; establishes global configuration, dataSource, cache, and mapper registry initialization.
• src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java — Parses individual mapper XML files and registers SQL statements, result maps, and cache configurations; foundational for statement discovery.
• src/main/java/org/apache/ibatis/builder/annotation/MapperAnnotationBuilder.java — Annotation-based counterpart to XML parsing; processes @Select, @Insert, @Update, @Delete and related annotations on mapper interfaces.
• src/main/java/org/apache/ibatis/cache/Cache.java — Abstract cache interface with decorator pattern implementations; critical for understanding MyBatis' multi-level caching strategy and LRU/FIFO eviction.
• src/main/java/org/apache/ibatis/executor/Executor.java — Abstract executor interface handling statement execution, result mapping, and transaction management; the actual bridge between parsed SQL and database operations.
• src/main/java/org/apache/ibatis/builder/SqlSourceBuilder.java — Converts raw SQL strings with parameter placeholders (#{}, ${}) into executable SqlSource objects; essential for dynamic SQL processing.

Add a new SQL statement (XML-based mapper)

1. Create or edit a mapper XML file under src/main/resources with <mapper namespace="your.package.YourMapper"> (src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java)
2. Add <select>, <insert>, <update>, or <delete> element with id and SQL body; use #{param} for bind variables (src/main/java/org/apache/ibatis/builder/xml/XMLStatementBuilder.java)
3. Register the mapper XML in mybatis-config.xml under <mappers> section (src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java)
4. Define a matching mapper interface method signature (return type, parameter names); MyBatis will bind via MapperRegistry (src/main/java/org/apache/ibatis/binding/MapperRegistry.java)

Add a new annotation-based mapper method

1. Define a method in your mapper interface with @Select/@Insert/@Update/@Delete annotation containing SQL string (src/main/java/org/apache/ibatis/annotations/Select.java)
2. Use @Param("paramName") on method parameters to bind them to #{paramName} placeholders in SQL (src/main/java/org/apache/ibatis/annotations/Param.java)
3. Optionally add @Results/@ResultMap to customize result object mapping (src/main/java/org/apache/ibatis/annotations/Results.java)
4. Register the mapper interface in XMLConfigBuilder via <mappers><mapper class="your.YourMapper"/></mappers> or programmatically (src/main/java/org/apache/ibatis/builder/annotation/MapperAnnotationBuilder.java)

Implement a custom TypeHandler for Java ↔ JDBC type conversion

1. Create a class extending BaseTypeHandler<YourJavaType> implementing setNonNullParameter() and getNullableResult() methods (src/main/java/org/apache/ibatis/type/TypeHandler.java)
2. Register the handler in mybatis-config.xml under <typeHandlers><typeHandler javaType="..." jdbcType="..." handler="..."/></typeHandlers> (src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java)
3. The handler will be auto-invoked during setParameters() (→ JDBC) and result mapping (→ Java object) (src/main/java/org/apache/ibatis/executor/StatementHandler.java)

Configure caching for a mapper namespace

1. Add <cache> element in mapper XML (or @CacheNamespace on mapper interface) to enable namespace-level cache (src/main/java/org/apache/ibatis/annotations/CacheNamespace.java)
2. Optionally specify eviction policy (LRU, FIFO, SOFT, WEAK) and size in cache attributes (src/main/java/org/apache/ibatis/cache/decorators/LruCache.java)
3. Add <select> flushCache="false" to statements that should NOT invalidate cache on execution (reads only) (src/main/java/org/apache/ibatis/builder/xml/XMLStatementBuilder.java)
4. Cache is managed by TransactionalCacheManager and invalidated by insert/update/delete unless useCache=false (src/main/java/org/apache/ibatis/cache/TransactionalCacheManager.java)

Parent POM requirement: Build fails unless you separately clone and install mybatis-parent (version 32-SNAPSHOT) from https://github.com/mybatis/parent—the README mentions this but it's easy to miss. Snapshot version: pom.xml declares version 3.3.0-SNAPSHOT and parent 32-SNAPSHOT, so clean builds expect SNAPSHOT repos in your Maven settings. TSQL/SQLPL test files: The repo includes src/test SQL scripts (114KB TSQL, 3.7KB SQLPL) for database testing—ensure your test DB (likely SQL Server) is reachable if running full test suite. Reflection complexity: The org.apache.ibatis.reflection package uses deep introspection and property expression parsing; modifying object binding without understanding MetaObject and ObjectFactory can cause subtle mapping failures.

• Dynamic Proxy (Java reflection) — MyBatis uses java.lang.reflect.Proxy in MapperProxy to intercept calls on mapper interfaces and route them to SQL statements without boilerplate—understanding this is essential to grok how mapper.selectById() becomes a query.
• Type Handler pattern (JDBC type mapping) — MyBatis bridges Java and SQL types via TypeHandler implementations (e.g., IntegerTypeHandler, DateTypeHandler). Custom type handlers are a common extension point, and understanding this pattern is critical for non-standard database columns.
• Interceptor/Plugin pattern (AOP without Spring) — org.apache.ibatis.plugin.Interceptor allows hooking into the execution pipeline (parameter binding, query execution, result mapping) without modifying core code—essential for logging, profiling, or custom caching.
• SQL Template Parsing (#{ } vs ${ } placeholders) — SqlSourceBuilder distinguishes parameterized #{} (safe, prevents SQL injection) from variable ${} (dangerous, for column/table names only). Misunderstanding this distinction is a common security bug.
• MetaObject (reflection facade for object property access) — The org.apache.ibatis.reflection.MetaObject class wraps any Java object and provides unified property access (nested properties, array indexing, Map keys) used throughout binding and result mapping—critical for dynamic result mapping in complex scenarios.
• Executor abstraction (caching, batching, lazy loading) — MyBatis provides multiple Executor implementations (Simple, Batch, Reuse) and decorators (Caching). Choosing the right executor significantly impacts query performance, N+1 query problems, and memory usage.
• XPath-based configuration parsing — MyBatis XML mappers are parsed via XPath (XPathParser), not simple DOM or SAX. Understanding this enables custom DTD extensions and property substitution in mapper files.

• mybatis/mybatis-3 — The canonical upstream MyBatis 3.x repository—this fork is a learning annotation of that codebase, so refer to the original for current patches and releases.
• mybatis/parent — Parent POM project required to build this repository; defines shared Maven plugins, dependencies, and build configuration for all MyBatis modules.
• mybatis/spring — Spring integration layer for MyBatis; complements this core ORM with Spring Data, transaction management, and dependency injection support.
• alibaba/druid — Popular data source pool and SQL monitoring tool used alongside MyBatis in production Java applications—solves connection pooling and performance diagnostics.
• eluder/orm-benchmark — Comparative benchmarks of ORM frameworks (Hibernate, MyBatis, jOOQ, etc.)—helps understand MyBatis' performance trade-offs vs. alternatives in this ecosystem.

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 comprehensive Chinese comments to org.apache.ibatis.reflection package

The README explicitly mentions reflection (org.apache.ibatis.reflection) as a core module for handling dynamic proxy creation and method invocation, but the file structure shows this package exists without listing its files. This is a critical gap since reflection is foundational to MyBatis's mapper proxy mechanism. Adding detailed Chinese comments to ReflectorFactory.java, Reflector.java, and related classes would align with the repo's stated purpose of providing Chinese-annotated source code and help contributors understand how MyBatis introspects mapper interfaces.

• [ ] Examine src/main/java/org/apache/ibatis/reflection/ directory structure
• [ ] Add Chinese comments explaining how Reflector caches class metadata and method signatures
• [ ] Document the relationship between reflection utilities and MapperProxy.java (src/main/java/org/apache/ibatis/binding/MapperProxy.java)
• [ ] Add examples showing how reflection enables dynamic proxy invocation in Chinese comments

Add unit tests for MapperRegistry and MapperProxy binding flow

The binding package (org.apache.ibatis.binding) contains critical classes like MapperRegistry.java, MapperProxy.java, and MapperProxyFactory.java that handle the core mapper registration and method invocation mechanism. No test files are visible in the structure. This is a high-value addition since testing these components validates that the annotation-driven mapper binding (used by MapperAnnotationBuilder) works correctly end-to-end.

• [ ] Create src/test/java/org/apache/ibatis/binding/MapperRegistryTest.java to test mapper registration, lookup, and exception handling
• [ ] Create src/test/java/org/apache/ibatis/binding/MapperProxyTest.java to test method invocation interception and parameter handling
• [ ] Add test cases covering @Param annotation handling and dynamic SQL parameter binding
• [ ] Include edge cases like duplicate mapper registration and invalid method invocations

Document and add tests for XML parsing edge cases in XMLConfigBuilder and XMLMapperBuilder

The README explicitly highlights XML parsing (org.apache.ibatis.parsing and org.apache.ibatis.builder.xml) as a core module with references to external resources. XMLConfigBuilder.java and XMLMapperBuilder.java are responsible for parsing mybatis-3-config.dtd and mybatis-3-mapper.dtd, but there are no visible test files validating DTD compliance, include handling, or error scenarios. Adding comprehensive tests ensures the Chinese-commented code is actually exercised and prevents regressions in XML parsing behavior.

• [ ] Create src/test/java/org/apache/ibatis/builder/xml/XMLConfigBuilderTest.java with tests for config parsing (environment, datasource, mappers elements)
• [ ] Create src/test/java/org/apache/ibatis/builder/xml/XMLMapperBuilderTest.java with tests for mapper parsing (resultMap, sql, select/insert/update/delete statements)
• [ ] Add test cases for XMLIncludeTransformer.java to verify <include> element resolution and circular reference detection
• [ ] Include negative test cases for DTD validation failures and malformed XML

• Add Chinese documentation comments to the org.apache.ibatis.cache package (decorators like PerpetualCache, LruCache, SoftCache). These are used for query result caching but lack the detailed annotations present in other modules—write explanations of cache eviction strategies and when each decorator applies.
• Create a minimal runnable example in examples/ that demonstrates the complete flow: configure MyBatis with an in-memory H2 database, define a simple User mapper using annotations, execute a query, and trace the call stack through MapperProxy → MapperMethod → Executor. Include both XML and annotation-based mapper examples.
• Add unit test coverage for error cases in src/main/java/org/apache/ibatis/builder/annotation/ (e.g., invalid @Results annotations, missing @Param on overloaded mapper methods). Current tests likely focus on happy paths; edge case tests would improve robustness for downstream users.

• High · SQL Injection Risk in Dynamic SQL Construction — src/main/java/org/apache/ibatis/builder/SqlSourceBuilder.java, src/main/java/org/apache/ibatis/parsing/. MyBatis framework dynamically constructs SQL queries based on user input. The SqlSourceBuilder and related components parse dynamic SQL with variable substitution (${} format). Without proper parameterization, this could lead to SQL injection vulnerabilities if developers use string concatenation instead of prepared statements. Fix: Ensure all dynamic SQL uses parameterized queries with #{} placeholders instead of ${}. Educate developers to avoid string concatenation in SQL construction. Implement validation and sanitization of all user inputs before SQL binding.
• High · XML External Entity (XXE) Injection Vulnerability — src/main/java/org/apache/ibatis/builder/xml/XMLConfigBuilder.java, src/main/java/org/apache/ibatis/builder/xml/XMLMapperBuilder.java, src/main/java/org/apache/ibatis/builder/xml/mybatis-3-config.dtd, src/main/java/org/apache/ibatis/builder/xml/mybatis-3-mapper.dtd. The codebase includes XML parsing functionality (XMLConfigBuilder, XMLMapperBuilder, XMLStatementBuilder) that processes DTD files (mybatis-3-config.dtd, mybatis-3-mapper.dtd). If XML parsing is not configured to disable external entity resolution, XXE attacks are possible. Fix: Disable XXE processing in XML parsers by configuring SAXParserFactory with XXE-prevention settings (disable external DTDs, disable external general entities). Use XMLConstants.ACCESS_EXTERNAL_DTD and XMLConstants.ACCESS_EXTERNAL_SCHEMA to restrict entity access.
• High · Reflection-Based Object Instantiation Without Validation — src/main/java/org/apache/ibatis/reflection/. The reflection package (org.apache.ibatis.reflection) is used for dynamic object instantiation and property access. Unrestricted reflection on untrusted classes or method invocation could lead to arbitrary code execution if class paths are controlled by user input. Fix: Implement a whitelist of allowed classes for reflection-based instantiation. Validate and sanitize all class names and method invocations. Restrict reflection capabilities to trusted packages only.
• Medium · Incomplete Element Exception Handling — src/main/java/org/apache/ibatis/builder/IncompleteElementException.java. The IncompleteElementException indicates incomplete configuration processing. If exception handling isn't properly implemented, it may lead to incomplete security configurations or allow bypass of security constraints. Fix: Implement strict validation for all required configuration elements. Fail-fast on incomplete security-related configurations. Log all incomplete element exceptions for audit purposes.
• Medium · Unsecured Caching Mechanism — src/main/java/org/apache/ibatis/cache/, src/main/java/org/apache/ibatis/cache/decorators/. The cache implementation (org.apache.ibatis.cache) includes decorators like SoftCache, WeakCache, and BlockingCache. Cached data might include sensitive information. Without proper access controls or encryption, cached data could be accessed by unauthorized processes. Fix: Implement encryption for cached sensitive data. Restrict cache access to authorized threads only. Consider using SerializedCache with secure serialization. Implement cache expiration policies for sensitive data.
• Medium · Dynamic SQL Provider Security — src/main/java/org/apache/ibatis/annotations/InsertProvider.java, src/main/java/org/apache/ibatis/annotations/UpdateProvider.java, src/main/java/org/apache/ibatis/annotations/DeleteProvider.java, src/main/java/org/apache/ibatis/annotations/SelectProvider.java, src/main/java/org/apache/ibatis/builder/annotation/ProviderSqlSource.java. Provider annotations (*Provider classes) allow dynamic SQL generation through method invocation. If provider methods are not properly validated, malicious SQL could be generated at runtime. Fix: Validate all SQL returned by provider methods. Implement static analysis of provider logic. Use parameterized queries within provider methods. Document security requirements for custom provider implementations.
• Low · Incomplete POM Security Metadata — undefined. The pom.xml references a SNAPSHOT Fix: undefined

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.