DOCSEARCHbyAlgolia
Submit Docs

MyBatis Mapper Documentation

repository·master·Indexed 27 days ago

https://github.com/abel533/mapper

A library providing generic CRUD operations for MyBatis to reduce boilerplate code for single-table database interactions. It includes modules such as mapper-core, mapper-extra, mapper-generator, mapper-spring, and mapper-weekend. Features include JPA annotation-based entity mapping, batch inserts via InsertListMapper, and a code generator extending MyBatis Generator (MBG) with FreeMarker template support via TemplateFilePlugin and MapperPlugin.

Tokens
9.2K
Snippets
23
Records
40
Agent score
92%

What's inside MyBatis Mapper

  1. Overview of MyBatis Mapper capabilities

    master

    MyBatis Mapper provides highly convenient CRUD (Create, Read, Update, Delete) operations for single tables. It allows developers to select from a variety of built-in generic methods or design their own custom generic methods.

    Note: It supports single-table operations but does not support generic multi-table join queries.

  2. Select the correct MyBatis Mapper version for your environment

    master

    Choose the appropriate branch of MyBatis Mapper based on your Spring Boot and JDK versions to ensure compatibility:

    BranchSpring Boot VersionJDK VersionMapper Version
    masterSpring Boot 4.xJDK 17+6.0.0+
    5.xSpring Boot 3.xJDK 17+5.0.0
    4.3.xSpring Boot 2.xJDK 8+4.3.x

  3. Migrate from MyBatis Generic Mapper 3.x to 4.x+

    master

    To facilitate the transition from Generic Mapper 3.x to 4.x and later versions, this project provides two sub-modules. You can upgrade by simply changing the Maven version number to tk.mybatis:mapper.

    Available modules:

    1. dependencies: Uses Maven dependency transitively.
    2. mapper: A single large JAR package created using the maven-shade-plugin.

  4. Integrate MyBatis 通用 Mapper using mapper-all-dependencies

    master

    To use the full suite of MyBatis 通用 Mapper features, add the mapper-all-dependencies dependency to your Maven pom.xml. This artifact automatically includes the following sub-projects:

    • mapper-core
    • mapper-extra
    • mapper-generator
    • mapper-spring
    • mapper-weekend
    <dependency>
    <groupId>tk.mybatis</groupId>
    <artifactId>mapper-all-dependencies</artifactId>
    <version>版本号</version>
</dependency>

  5. Configure Entity Classes with JPA Annotations

    master

    MyBatis通用Mapper uses JPA annotations to map entity classes to database tables. Ensure your entity class uses @Id for the primary key and @Column for table columns.

    Important: Any property in your entity class that is not a field in the database table must be annotated with @Transient to prevent mapping errors.

  6. Avoid mixing official MyBatis starter with mapper-spring-boot-starter

    master
    When using mapper-spring-boot-starter, do not include the official mybatis-spring-boot-starter in your dependencies. The mapper-spring-boot-starter implements its own auto-configuration to ensure proper initialization and to prevent conflicts with MyBatis's own @Bean generation.

  8. Add mapper-spring dependency

    master

    To integrate MyBatis Common Mapper with Spring, you must add mapper-spring. Note that this dependency does not transitively include other required libraries, so you must also provide MyBatis, mybatis-spring, and Spring dependencies in your project.

    <!-- Required dependency -->
<dependency>
    <groupId>tk.mybatis</groupId>
    <artifactId>mapper-spring</artifactId>
    <version>VERSION</version>
</dependency>

<!-- Other required dependencies -->
<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>VERSION</version>
</dependency>
<dependency>
    <groupId>tk.mybatis</groupId>
    <artifactId>mapper</artifactId>
    <version>VERSION</version>
</dependency>
<dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis-spring</artifactId>
    <version>VERSION</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>VERSION</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-tx</artifactId>
    <version>VERSION</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-jdbc</artifactId>
    <version>VERSION</version>
</dependency>

  9. Add FreeMarker dependency for TemplateFilePlugin

    master

    If you are using the TemplateFilePlugin with the default FreemarkerTemplateFormatter, you must include the FreeMarker dependency in your project.

    <dependency>
    <groupId>org.freemarker</groupId>
    <artifactId>freemarker</artifactId>
    <version>2.3.23</version>
</dependency>

  10. Configure via @MapperScan annotation

    master

    When using pure annotations, you cannot configure Common Mapper parameters directly in @MapperScan. Instead, use one of the following three methods (ordered by priority):

    1. mapperHelperRef: Specify the name of a MapperHelper bean.
    2. properties: Provide configuration strings in key=value format.
    3. Spring Boot Configuration: Use application.yml or application.properties (only if using annotation-based configuration).

  12. Integrate MyBatis Mapper Jar

    master

    To use MyBatis Mapper, add the tk.mybatis:mapper dependency to your project. This single dependency integrates the following modules by default:

    • mapper-core
    • mapper-extra
    • mapper-generator
    • mapper-spring
    • mapper-weekend

    Note that adding this dependency does not introduce transitive dependencies.

    <dependency>
    <groupId>tk.mybatis</groupId>
    <artifactId>mapper</artifactId>
    <version>版本号</version>
</dependency>