MyBatis Mapper新一代通用 Mapper

項(xiàng)目地址：https://mapper.mybatis.io

介紹

這是一個(gè)不需要任何配置就可以直接使用的通用 Mapper，通過簡單的學(xué)習(xí)就可以直接在項(xiàng)目中使用。

1.1 主要目標(biāo)

1. 開箱即用，無需任何配置，繼承基類 Mapper 即可獲得大量通用方法；
2. 隨心所欲，通過復(fù)制粘貼的方式可以組建自己的基類 Mapper；
3. 全面貼心，提供 Service 層的封裝方便業(yè)務(wù)使用和理解 Mapper；
4. 簡單直觀，提供 ActiveRecord 模式，結(jié)合 Spring Boot 自動(dòng)配置直接上手用；
5. 自定義方法，簡單幾行代碼即可實(shí)現(xiàn)自定義通用方法；
6. 輕松擴(kuò)展，通過 Java SPI 輕松擴(kuò)展。

1.2 系統(tǒng)要求

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 層封裝時(shí) -->
  <dependency>
    <groupId>io.mybatis</groupId>
    <artifactId>mybatis-service</artifactId>
    <version>1.0.0</version>
  </dependency>
  <!-- TODO 按需選擇依賴 -->
  <!-- 使用 ActiveRecord 模式時(shí) -->
  <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 層封裝時(shí)
    compile("io.mybatis:mybatis-service:1.0.0")
    // 使用 ActiveRecord 模式時(shí)
    compile("io.mybatis:mybatis-activerecord:1.0.0")
}

1.4 快速設(shè)置

MyBatis Mapper 的基本原理是將實(shí)體類映射為數(shù)據(jù)庫中的表和字段信息，因此實(shí)體類需要通過注解配置基本的元數(shù)據(jù)，配置好實(shí)體后，只需要?jiǎng)?chuàng)建一個(gè)繼承基礎(chǔ)接口的 Mapper 接口就可以開始使用了。

1.4.1 實(shí)體類配置

假設(shè)有一個(gè)表：

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

對應(yīng)的實(shí)體類：

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方法
}

實(shí)體類上必須添加@Entity.Table注解指定實(shí)體類對應(yīng)的表名，建議明確指定表名，不提供表名的時(shí)候，使用類名作為表名。所有屬于表中列的字段，必須添加@Entity.Column注解，不指定列名時(shí)，使用字段名（不做任何轉(zhuǎn)換），通過 id=true可以標(biāo)記字段為主鍵。

@Entity中包含的這兩個(gè)注解提供了大量的配置屬性，想要使用更多的配置，參考 實(shí)體類注解 中的內(nèi)容，下面是一個(gè)簡單示例：

@Entity.Table(value = "sys_user", remark = "系統(tǒng)用戶", 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實(shí)體后，直接創(chuàng)建一個(gè)繼承了 Mapper 的接口即可：

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

這個(gè)接口只要被 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 配置，啟動(dòng)類注解方式：

@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());
//根據(jù)id查詢
user = userMapper.selectByPrimaryKey(user.getId());
//刪除
Assert.assertEquals(1, userMapper.deleteByPrimaryKey(user.getId()));

看到這里，可以發(fā)現(xiàn)除了 MyBatis 自身的配置外，MyBatis Mapper 只需要配置實(shí)體類注解，
創(chuàng)建對應(yīng)的 Mapper 接口就可以直接使用，沒有任何繁瑣的配置。

上面的示例只是簡單的使用了 MyBatis Mapper，還有很多開箱即用的功能沒有涉及，
建議在上述示例運(yùn)行成功后，繼續(xù)查看本項(xiàng)目其他模塊的詳細(xì)文檔，熟悉各部分文檔后，
在使用 MyBatis Mapper 時(shí)會更得心應(yīng)手，隨心所欲。

更多用法可以通過 https://mapper.mybatis.io 進(jìn)行了解。