MyBatis Mapper

项目地址：https://mapper.mybatis.io

介绍

这是一个不需要任何配置就可以直接使用的通用 Mapper，通过简单的学习就可以直接在项目中使用。

1.1 主要目标

1. 开箱即用，无需任何配置，继承基类 Mapper 即可获得大量通用方法；
2. 随心所欲，通过复制粘贴的方式可以组建自己的基类 Mapper；
3. 全面贴心，提供 Service 层的封装方便业务使用和理解 Mapper；
4. 简单直观，提供 ActiveRecord 模式，结合 Spring Boot 自动配置直接上手用；
5. 自定义方法，简单几行代码即可实现自定义通用方法；
6. 轻松扩展，通过 Java SPI 轻松扩展。

1.2 系统要求

MyBatis Mapper 要求 MyBatis 最低版本为3.5.1，推荐使用最新版本。

和 MyBatis 框架一样，最低需要 Java 8。

1.3 安装

如果你使用 Maven，在你的 `pom.xml` 添加下面的依赖：

<dependencies>
  <dependency>
    <groupId>io.mybatis</groupId>
    <artifactId>mybatis-mapper</artifactId>
    <version>1.0.0</version>
  </dependency>
  <!-- TODO 按需选择依赖 -->
  <!-- 使用 Service 层封装时 -->
  <dependency>
    <groupId>io.mybatis</groupId>
    <artifactId>mybatis-service</artifactId>
    <version>1.0.0</version>
  </dependency>
  <!-- TODO 按需选择依赖 -->
  <!-- 使用 ActiveRecord 模式时 -->
  <dependency>
    <groupId>io.mybatis</groupId>
    <artifactId>mybatis-activerecord</artifactId>
    <version>1.0.0</version>
  </dependency>
</dependencies>

如果使用 Gradle，在 `build.gradle` 中添加：

dependencies {
    compile("io.mybatis:mybatis-mapper:1.0.0")
    // 使用 Service 层封装时
    compile("io.mybatis:mybatis-service:1.0.0")
    // 使用 ActiveRecord 模式时
    compile("io.mybatis:mybatis-activerecord:1.0.0")
}

1.4 快速设置

MyBatis Mapper 的基本原理是将实体类映射为数据库中的表和字段信息，因此实体类需要通过注解配置基本的元数据，配置好实体后，只需要创建一个继承基础接口的 Mapper 接口就可以开始使用了。

1.4.1 实体类配置

假设有一个表：

create table user
(
    id   INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 1) PRIMARY KEY,
    name VARCHAR(32) DEFAULT 'DEFAULT',
    sex  VARCHAR(2)
);

对应的实体类：

import io.mybatis.provider.Entity;

@Entity.Table("user")
public class User {
  @Entity.Column(id = true)
  private Long   id;
  @Entity.Column("name")
  private String username;
  @Entity.Column
  private String sex;

  //省略set和get方法
}

实体类上必须添加@Entity.Table注解指定实体类对应的表名，建议明确指定表名，不提供表名的时候，使用类名作为表名。所有属于表中列的字段，必须添加@Entity.Column注解，不指定列名时，使用字段名（不做任何转换），通过 id=true可以标记字段为主键。

@Entity中包含的这两个注解提供了大量的配置属性，想要使用更多的配置，参考 实体类注解 中的内容，下面是一个简单示例：

@Entity.Table(value = "sys_user", remark = "系统用户", autoResultMap = true)
public class User {
  @Entity.Column(id = true, remark = "主键", updatable = false, insertable = false)
  private Long   id;
  @Entity.Column(value = "name", remark = "帐号")
  private String userName;
  //省略其他
}

1.4.2 Mapper接口定义

有了 User实体后，直接创建一个继承了 Mapper 的接口即可：

//io.mybatis.mapper.Mapper
public interface UserMapper extends Mapper<User, Long> {
  
}

这个接口只要被 MyBatis 扫描到即可直接使用。

下面是几种常见的扫描配置：

1. MyBatis 自带的配置文件方式 `mybatis-config.xml`：

 <mappers>
   <!-- 扫描指定的包 -->
   <package name="com.example.mapper"/>
 </mappers>

2. Spring 中的 `spring.xml` 配置：

<bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
  <property name="basePackage" value="com.example.mapper"/>
  <property name="markerInterface" value="io.mybatis.service.mapper.RoleMarker"/>
  <property name="sqlSessionFactoryBeanName" value="sqlSessionFactoryRole"/>
</bean>

3. Spring Boot 配置，启动类注解方式：

@MapperScan(basePackages = "com.example.mapper")
@SpringBootApplication
public class SpringBootDemoApplication {

  public static void main(String[] args) {
    SpringApplication.run(SpringBootDemoApplication.class, args);
  }

}

Spring Boot 中，还可以直接给接口添加 @org.apache.ibatis.annotations.Mapper 注解，增加注解后可以省略 @MapperScan 配置。

可以注意到上面都是 MyBatis 自己的配置方式，新版 mybatis-mapper 本身不需要任何配置即可使用。

1.4.3 使用

定义好接口后，就可以获取 `UserMapper` 使用，下面是简单示例：

User user = new User();
user.setUserName("测试");
userMapper.insert(user);
//保存后自增id回写，不为空
Assert.assertNotNull(user.getId());
//根据id查询
user = userMapper.selectByPrimaryKey(user.getId());
//删除
Assert.assertEquals(1, userMapper.deleteByPrimaryKey(user.getId()));

看到这里，可以发现除了 MyBatis 自身的配置外，MyBatis Mapper 只需要配置实体类注解，
创建对应的 Mapper 接口就可以直接使用，没有任何繁琐的配置。

上面的示例只是简单的使用了 MyBatis Mapper，还有很多开箱即用的功能没有涉及，
建议在上述示例运行成功后，继续查看本项目其他模块的详细文档，熟悉各部分文档后，
在使用 MyBatis Mapper 时会更得心应手，随心所欲。

更多用法可以通过 https://mapper.mybatis.io 进行了解。