08、MyBatis源码 - MyBatis之映射器注解

映射器注解

设计初期的 MyBatis 是一个 XML 驱动的框架。配置信息是基于 XML 的，映射语句也是定义在 XML 中的。而在 MyBatis 3 中，我们提供了其它的配置方式。MyBatis 3 构建在全面且强大的基于 Java 语言的配置 API 之上。它是 XML 和注解配置的基础。注解提供了一种简单且低成本的方式来实现简单的映射语句。

不幸的是，Java 注解的表达能力和灵活性十分有限。尽管我们花了很多时间在调查、设计和试验上，但最强大的 MyBatis 映射并不能用注解来构建——我们真没开玩笑。而 C# 属性就没有这些限制，因此 MyBatis.NET 的配置会比 XML 有更大的选择余地。虽说如此，基于 Java 注解的配置还是有它的好处的。

注解说明

注解如下表所示：

使用案例

这个例子展示了如何使用 @SelectKey 注解来在插入前读取数据库序列的值：

@Insert("insert into table3 (id, name) values(#{nameId},{name})")
@SelectKey(statement="call next value for TestSequence", keyProperty="nameId", before=true, resultType=int.class)
int insertTable3(Name name);

这个例子展示了如何使用 @SelectKey 注解来在插入后读取数据库自增列的值：

@Insert("insert into table2 (name) values(#{name})")
@SelectKey(statement="call identity()", keyProperty="nameId", before=false, resultType=int.class)
int insertTable2(Name name);

这个例子展示了如何使用 @Flush 注解来调用 SqlSession#flushStatements()：

@Flush
List<BatchResult> flush();

这些例子展示了如何通过指定 @Result 的 id 属性来命名结果集：

@Results(id = "userResult", value = {
   
     
  @Result(property = "id", column = "uid", id = true),
  @Result(property = "firstName", column = "first_name"),
  @Result(property = "lastName", column = "last_name")
})
@Select("select * from users where id ={id}")
User getUserById(Integer id);

@Results(id = "companyResults")
@ConstructorArgs({
   
     
  @Arg(column = "cid", javaType = Integer.class, id = true),
  @Arg(column = "name", javaType = String.class)
})
@Select("select * from company where id ={id}")
Company getCompanyById(Integer id);

这个例子展示了如何使用单个参数的 @SqlProvider 注解：

@SelectProvider(type = UserSqlBuilder.class, method = "buildGetUsersByName")
List<User> getUsersByName(String name);

class UserSqlBuilder {
   
     
  public static String buildGetUsersByName(final String name) {
   
     
    return new SQL(){
   
     {
   
     
      SELECT("*");
      FROM("users");
      if (name != null) {
   
     
        WHERE("name like{value} || '%'");
      }
      ORDER_BY("id");
    }}.toString();
  }
}

这个例子展示了如何使用多个参数的 @SqlProvider 注解：

@SelectProvider(type = UserSqlBuilder.class, method = "buildGetUsersByName")
List<User> getUsersByName(
    @Param("name") String name, @Param("orderByColumn") String orderByColumn);

class UserSqlBuilder {
   
     

  // 如果不使用 @Param，就应该定义与 mapper 方法相同的参数
  public static String buildGetUsersByName(
      final String name, final String orderByColumn) {
   
     
    return new SQL(){
   
     {
   
     
      SELECT("*");
      FROM("users");
      WHERE("name like{name} || '%'");
      ORDER_BY(orderByColumn);
    }}.toString();
  }

  // 如果使用 @Param，就可以只定义需要使用的参数
  public static String buildGetUsersByName(@Param("orderByColumn") final String orderByColumn) {
   
     
    return new SQL(){
   
     {
   
     
      SELECT("*");
      FROM("users");
      WHERE("name like{name} || '%'");
      ORDER_BY(orderByColumn);
    }}.toString();
  }
}

此示例显示使用全局配置（自 3.5.6 起可用）将 sql 提供程序类共享给所有映射器方法的用法：

Configuration configuration = new Configuration();
configuration.setDefaultSqlProviderType(TemplateFilePathProvider.class); // 指定一个 sql 提供程序类以在所有映射器方法上共享
// ...

 // 可以省略 sql 提供程序注释上的类型/值属性
 // 如果省略，MyBatis 将应用 defaultSqlProviderType 上指定的类。
public interface UserMapper {
   
     

  @SelectProvider // Same with @SelectProvider(TemplateFilePathProvider.class)
  User findUser(int id);

  @InsertProvider // Same with @InsertProvider(TemplateFilePathProvider.class)
  void createUser(User user);

  @UpdateProvider // Same with @UpdateProvider(TemplateFilePathProvider.class)
  void updateUser(User user);

  @DeleteProvider // Same with @DeleteProvider(TemplateFilePathProvider.class)
  void deleteUser(int id);
}

以下例子展示了 ProviderMethodResolver（3.5.1 后可用）的默认实现使用方法：

@SelectProvider(UserSqlProvider.class)
List<User> getUsersByName(String name);

// 在你的 provider 类中实现 ProviderMethodResolver 接口
class UserSqlProvider implements ProviderMethodResolver {
   
     
  // 默认实现中，会将映射器方法的调用解析到实现的同名方法上
  public static String getUsersByName(final String name) {
   
     
    return new SQL(){
   
     {
   
     
      SELECT("*");
      FROM("users");
      if (name != null) {
   
     
        WHERE("name like{value} || '%'");
      }
      ORDER_BY("id");
    }}.toString();
  }
}

此示例显示了语句注释上的 databaseId 属性的用法（自 3.5.5 起可用）：

@Select(value = "SELECT SYS_GUID() FROM dual", databaseId = "oracle") // Use this statement if DatabaseIdProvider provide "oracle"
@Select(value = "SELECT uuid_generate_v4()", databaseId = "postgres") // Use this statement if DatabaseIdProvider provide "postgres"
@Select("SELECT RANDOM_UUID()") // Use this statement if the DatabaseIdProvider not configured or not matches databaseId
String generateId();