MyBatis Common Mapper: single-table CRUD without hand-written SQL

The boilerplate MyBatis Common Mapper removes

Plain MyBatis makes you write the SQL. A single-table insert, a delete by primary key, a select by id and a paged list each get their own statement, either in an XML mapper file or in an annotation on the interface. For a schema with a dozen tables that is a dozen near-identical files, and the only thing that changes between them is the table and column names.

MyBatis Common Mapper removes that repetition. You declare an interface, give it a table and a set of columns through annotations, and the library supplies the CRUD methods. The README frames the goal as letting developers pick the general methods they need "按照自己的需要" and write their own general methods when the built-in set does not fit. That second half matters: the project's own guidance says a large, all-purpose method set is not automatically better, and that methods chosen or designed for your needs serve you better.

The audience is a Java team already committed to MyBatis and Spring Boot, working on a schema where most access is single-table. It is not a query builder for reporting workloads and it is not an ORM that maps object graphs. The README states the boundary plainly: single-table operations are supported, general multi-table join queries are not.

How the generated statements are produced

The mechanism is annotation-driven statement generation at mapper-registration time. You define an interface, mark it as a mapper, and annotate the entity class with the table name and the fields with their column mapping. MyBatis Common Mapper reads that metadata and registers the insert, delete, update and select statements into the MyBatis configuration, so the mapper interface has methods to call without any XML behind it.

The repository layout reflects this split. The top level holds core/, base/, extra/, generator/, spring/, spring-boot-starter/, all/, solon-plugin/ and weekend/ as separate modules, which is why the artifact you depend on matters: the core generation logic, the Spring integration and the Boot starter are not the same jar. The generator/ module is separate again, aimed at producing code rather than generating statements at runtime.

Version 6.0.0 is described as mainly a dependency update. The README says the configuration is fully compatible but that you must move to the newer JPA annotations and copy in mybatis-spring 4.0.0 and mybatis-spring-boot-starter 4.0.0. That is the real cost of the upgrade: the annotation package changed, so entity classes carry an import that has to move with it.

Installing MyBatis Common Mapper 6.0.0 and calling a generated method

Version 6.0.0 is on Maven Central under the group tk.mybatis. The README gives this dependency block, and it is the one to use for the Spring Boot 4 branch:

<dependency>
    <groupId>tk.mybatis</groupId>
    <artifactId>mapper</artifactId>
    <version>6.0.0</version>
</dependency>

Before adding it, check the version table in the README against your runtime. The master branch is Spring Boot 4.x with JDK 17+ and Mapper 6.0.0+; the 5.x branch is Spring Boot 3.x with JDK 17+ and Mapper 5.0.0; the 4.3.x branch is Spring Boot 2.x with JDK 8+ and Mapper 4.3.x. Picking the wrong row is the most likely first failure, because the annotation package and the mybatis-spring version both follow the branch.

The README also states that 6.0.0 requires the newer JPA annotations plus mybatis-spring 4.0.0 and mybatis-spring-boot-starter 4.0.0. Those are the versions to align your existing dependencies with, not versions to invent. Beyond the dependency block, the README does not spell out the full wiring: it points to the GitHub and Gitee wikis and to the JavaDoc for the configuration details, so the entity annotations and mapper registration steps are documented there rather than in the README itself. For a first real use, follow the quick-start links the README gives, then verify the generated method by calling it from a test against a real table. If the statement is not found at startup, the usual cause is a mapper interface that was not registered, not a missing dependency.

Single-table only, and the branch trap

The limitation is stated in the README and it is not a small one: general multi-table join queries are not supported. If your service layer needs a join, a subquery or a hand-tuned projection, MyBatis Common Mapper does not generate it. You write that statement yourself in the usual MyBatis way, which means a real application ends up with two styles side by side: generated single-table methods and hand-written SQL for everything else. That is workable, but it is a mixed codebase and the boundary has to be a deliberate choice rather than something a developer discovers mid-sprint.

The second constraint is version branching. Three branches, three Spring Boot generations, three JDK baselines. The README presents the 6.0.0 release as a dependency update for Spring Boot 4.0.2 compatibility, and it tells you to copy in the matching mybatis-spring artifacts. A team on Spring Boot 3 is not on this branch; a team on Spring Boot 2 is two branches back. Upgrading Spring Boot therefore means upgrading Mapper and the JPA annotations together, which is the kind of change that touches every entity class in the project.

The third point is one the README makes itself. It recommends looking at a newer project, mybatis-mapper, for new work, describing it as existing purely as a MyBatis extension that modifies no MyBatis, mybatis-spring or mybatis-spring-boot-starter code and needs no extra configuration. When a project's own README steers new users elsewhere, that is worth weighing before you build a new service on this one.

Where MyBatis Common Mapper sits next to the alternatives

The nearest alternative is plain MyBatis with XML or annotation mappers. The difference is who writes the SQL. Plain MyBatis gives you the statement and nothing else, so every table needs its own insert, delete, update and select. MyBatis Common Mapper generates those from annotations and leaves you to write only the queries it cannot infer. Plain MyBatis is more verbose and more explicit; Mapper is faster to start and less visible, since the SQL is produced rather than read.

The alternative the README itself recommends is mybatis-mapper, a separate project at github.com/mybatis-mapper/mapper with documentation at mapper.mybatis.io. The README says it works as a pure MyBatis extension without modifying MyBatis, mybatis-spring or mybatis-spring-boot-starter, and without extra configuration. That is a different integration approach from MyBatis Common Mapper, which the README pairs with specific mybatis-spring and starter versions. If you are starting fresh, the README's own recommendation is to look at mybatis-mapper first.

A third option is a full ORM such as Hibernate. That solves a different problem: object graph mapping and multi-table relationships. MyBatis Common Mapper deliberately stays on single tables, so it is not a drop-in substitute for an ORM, and it does not try to be.

Maintenance, licence and the cost of staying current

The repository is not archived, and the last push was on 2026-07-15. The most recent release listed is 6.0.0 on 2026-02-12, alongside 5.0.2 and 4.3.2 published the same day, which shows the three branches are released in step rather than independently. That is a good sign for teams on older branches, because it means a Spring Boot 2 or 3 shop is not stranded.

The licence is MIT, stated in the README and present as a LICENSE file at the repository root. MIT is permissive: it allows commercial use and modification, and it requires the copyright notice and licence text to be preserved. That is a description of the licence text, not legal advice; if your organisation has rules about dependency licences, the LICENSE file is the document to check.

Upgrade cost is where this project asks for real work. The 6.0.0 release is a dependency alignment: newer JPA annotations, mybatis-spring 4.0.0, mybatis-spring-boot-starter 4.0.0, Spring Boot 4. The README says the configuration itself is compatible, so the migration is mostly imports and dependency versions. But because the annotation package changes, the edit lands in every entity class. Budget for that rather than for a version bump in one pom file.

Editorial conclusion

Adopt MyBatis Common Mapper when you are on Spring Boot 4 with JDK 17, your workload is single-table CRUD, and you want the mapper methods generated rather than written. Do not adopt it for multi-table joins, and do not expect it to work on Spring Boot 2 or 3 without the matching branch. Before committing, verify three things against the 6.0.0 artifact: which JPA annotation package your imports resolve to, whether the mybatis-spring and mybatis-spring-boot-starter versions you already have are the 4.0.0 line the README calls for, and whether the generated methods cover every query your service layer actually issues.

Frequently asked questions

Official sources

1. abel533/Mapper on GitHub
2. License: MIT
3. Project website
4. README
5. Releases