一、注解归类

mybatis最初配置信息是基于 XML ,映射语句(SQL)也是定义在 XML 中的。而到了 MyBatis 3提供了新的基于注解的配置。mybatis提供的注解有很多，笔者进行了分类：

• 增删改查：
  @Insert、@Update、@Delete、@Select、@MapKey、@Options、@SelelctKey、@Param、@InsertProvider、@UpdateProvider、@DeleteProvider、@SelectProvider
• 结果集映射：
  @Results、@Result、@ResultMap、@ResultType、@ConstructorArgs、@Arg、@One、@Many、@TypeDiscriminator、@Case
• 缓存：
  @CacheNamespace、@Property、@CacheNamespaceRef、@Flush

绝大部分注解，在xml映射文件中都有元素与之对应，但是不是所有。此外在mybatis-spring中提供了@Mapper注解和@MapperScan注解，用于和spring进行整合。

二、增删改查

映射器接口示例，假设有以下UserMapper接口：

public interface UserMapper {
   @Insert("INSERT INTO user(id,name) VALUES (#{id},#{name})”)
   @Options(useGeneratedKeys = true, keyColumn = "id", keyProperty = "id") 
   public int insert(User user);

   @Update(" UPDATE user SET name=#{name} WHERE id=#{id}")
   public int update(User user);

   @Delete(“ DELETE FROM user WHERE id=#{id}")
   public int delete(int id);

   @Select("SELECT id,name FROM user WHERE id= #{id}")
   public User selectById(int id);

   @Select("SELECT id,name FROM user")
   public List<User> selectAll();

   @Select("SELECT id,name FROM user")
   @MapKey("id")
   public Map<Integer,User> selectMap();

   @Select({ "<script>",
      "SELECT id,name " + "FROM user " + "WHERE id IN "
            + "<foreach item='id' index='index' collection=‘array' open='(' separator=',' close=')'> " 
                 + "#{id}"
            + "</foreach> ",
      "</script>" })
   public List<User> selectByIds(int... ids);

   @Select("SELECT id,name FROM user LIMIT #{offset},#{limit}")
   public List<User> selectPage(@Param("offset") int offset, @Param("limit") int limit);
}

1、@Insert、@Update、@Delete、@Options、@SelectKey注解

mybatis会根据接口方法上的@Insert、@Update、@Delete注解，分别去调用SqlSession的insert、update、delete方法。这个几个方法返回的都是一个int，表示影响的记录行数。

特别的，在UserMapper接口的insert方法上，除了添加了@Insert注解，还添加了@Options注解。在上面的案例中，@Options注解用于获取自动生成主键，并设置到User实体中。此外，@SelectKey注解也可以用于获取自动生成的主键，使用方式如下：

@Insert("INSERT INTO user(id,name) VALUES (#{id},#{name})")
@SelectKey(statement = "SELECT LAST_INSERT_ID()", keyProperty = "id", before = false, resultType = Integer.class)
public int insert(User user);

2、@Select注解

 在上面的案例中，UserMapper的selectById、selectAll、selectMap、selectByIds、selectPage方法都添加了@Select注解。mybatis会根据方法的返回值类型User、List<User>、Map<Integer,User>判断是调用SqlSession的selectOne、selectList还是selectMap方法。 

3、@MapKey注解

特别的，对于返回值是Map的情况，方法上额外添加了一个@MapKey("id")注解，表示将User实例的id属性当做Map的key。

4 、动态sql与<script>标签

在UserMapper的selectByIds方法中，可以看到@Select注解里填写的SQL前后分别添加了<script>、</script>，这是因为SQL中使用了动态sql标签<foreach>。不管是@Insert、@Update、@Delete、@Select注解，只要SQL里使用了mybatis的动态sql标签(包括：if、choose …when ...otherwise、trim 、where、 set、foreach、bind)等，都建议在sql前后分别加上<script>、</script>，否则可能会出现一些参数找不到的情况。

5、@Param注解

@Param注解用于给方法参数起一个名字。以下是笔者总结的使用原则：

• 在方法只接受一个参数的情况下，可以不使用@Param。
• 在方法接受多个参数的情况下，建议一定要使用@Param注解给参数命名。

例如上述案例的selectPage方法接受2个参数，所以其两个参数都使用了@Param注解。@Param注解看起来配置最简单，实际上理解确实最复杂，下面进行详细的介绍。

前面已经提到，当映射器接口定义的方法被调用时，mybatis内部根据方法上注解：@Insert、@Update、@Delete、@Select来选择调用SqlSession的insert、update、delete、selectXXX方法。以下是SqlSession接口的相关方法定义(部分省略)：

public interface SqlSession extends Closeable {
  ...
  <T> T selectOne(String statement);
  <T> T selectOne(String statement, Object parameter);
  <E> List<E> selectList(String statement);
  <E> List<E> selectList(String statement, Object parameter);
  <K, V> Map<K, V> selectMap(String statement, String mapKey);
  <K, V> Map<K, V> selectMap(String statement, Object parameter, String mapKey);
  ...
  int insert(String statement);
  int insert(String statement, Object parameter);
  int update(String statement);
  int update(String statement, Object parameter);
  int delete(String statement);
  int delete(String statement, Object parameter);
  ...
}

可以看到部分方法接受一个Object类型的parameter参数，另外一些方法则没有此参数。mybatis在执行前，除了会根据方法上注解：@Insert、@Update、@Delete、@Select来选择调用SqlSession的insert、update、delete、selectXXX方法；还会提前对传入映射器接口方法中的参数进行一些处理，然后再调用SqlSession的相应方法。逻辑如下：

1)、如果映射器接口方法不接受参数，mybatis在执行时会调用相应无parameter参数的方法重载形式。例如，如UserMapper接口的selectAll方法，其不接受参数，返回值类型为List，因此调用SqlSession不接受paramter参数的selectList方法：

<E> List<E> selectList(String statement);

2)、如果映射器方法只有一个参数，并且这个参数没有使用@Param注解，则直接用这个参数来调用SqlSession相应接受Object类型parameter方法参数的重载形式。例如，如UserMapper接口的selectByIds方法，其接受1个int[]数组类型参数作为查询条件，返回值类型为List<User>，因此调用SqlSession接受paramter参数的selectList方法：

<E> List<E> selectList(String statement, Object parameter);

3)、如果映射器方法只接受一个参数，但是使用了@Param注解，也会先封装到Map中；或者映射器方法总是接受多个参数，不管有没有使用@Param注解指定参数，总是会先封装到一个Map中。之后，调用SqlSession的相应方法把这个Map当做parameter参数传入。
例如：UserMapper接口的selectPage方法， 通过@Param("offset”)和@Param("limit”)为2个int参数指定了名字。

@Select("SELECT id,name FROM user LIMIT #{offset},#{limit}")
public List<User> selectPage(@Param("offset") int offset, @Param("limit") int limit);

假设我们传入0和10，那么参数封装后的Map结构如下：

 key        value
--------------------------
  offset      0        //1
  limit       10       //2
  param1      0        //3
  param2      10       //4

关于Map中1、2两个key-value，比较好理解，是我们通过@Param注解指定的映射关系。而3、4两个key-value，实际上是参数位置(param1、param2…，下标从1开始)和参数值的映射关系，不管我们有没有使用@Param注解，存在多个参数的情况下，我们总是可以按照位置进行引用。

因此，将UserMapper的selectPage方法定义改成以下形式也是正确的：

//使用了@Param注解的情况下，依然根据参数位置进行引用(param1，param2…，下标从1开始)
@Select("SELECT id,name FROM user LIMIT #{param1},#{param2}")
public List<User> selectPage(@Param("offset") int offset, @Param("limit") int limit);
//不使用@Param注解，直接根据参数位置进行引用
@Select("SELECT id,name FROM user LIMIT #{param1},#{param2}")
public List<User> selectPage(int offset, int limit);

显然，根据参数位置进行引用不太直观，因此建议在存在多个参数的情况，总是通过@Param注解显式的指定参数名。

6 动态sql相关注解

@InsertProvider、@UpdateProvider、@DeleteProvider、@SelectProvider

public interface UserBuilderMapper {
   @SelectProvider(type = UserSqlBuilder.class, method = "buildSelectByIdSql")
   public User selectById(@Param("id") int id);
   @InsertProvider(type = UserSqlBuilder.class, method = "buildInsertSql")
   @Options(useGeneratedKeys = true, keyColumn = "id", keyProperty = "id")
   public int insert(User user);
   @UpdateProvider(type = UserSqlBuilder.class, method = "buildUpdateSql")
   public int update(User user);
   @DeleteProvider(type = UserSqlBuilder.class, method = "buildDeleteSql")
   public int delete(@Param("id") int id);
    //建议将sql builder以映射器接口内部类的形式进行定义
    public static class UserSqlBuilder {
      public static String buildSelectByIdSql(@Param("id") int id) {
         return new SQL() {
            {
               SELECT("id, name");
               FROM("user");
               WHERE("id=#{id}");
            }
         }.toString();
      }
      public static String buildInsertSql(User user) {
         return new SQL() {
            {
               INSERT_INTO("user");
               VALUES("name", "#{name}");
            }
         }.toString();
      }
      public static String buildUpdateSql(User user) {
         return new SQL() {
            {
               UPDATE("user");
               SET("name=#{name}");
               WHERE("id=#{id}");
            }
         }.toString();
      }
      public static String buildDeleteSql(@Param("id") int id) {
         return new SQL() {
            {
               DELETE_FROM("user");
                    WHERE("id=#{id}");
            }
         }.toString();
      }
   }
 }
}

三、结果集映射

1、@ConstructorArgs与@Arg注解

如果实体类没有无参的构造方法，那么我们就必须通过@ConstructorArgs与@Arg注解来提供实体类的构造方法参数信息。例如上述UserMapper的selectById方法，其返回一个User对象。假设User对象只有以下构造方法：

public User(Integer id, String name) {
   this.id = id;
   this.name = name;
}

那么需要在selectById方法上，添加@ConstructorArgs注解，提供构造方法信息，如下：

@Select("SELECT id,name FROM user where id= #{id}")
@ConstructorArgs({
      @Arg(column = "id",javaType = Integer.class,id = true),
      @Arg(column = "name",javaType = String.class)})
public User selectById(int id);

注意，通常情况下，我们都建议为实体类提供无参的构造方法的，这是最佳实践的总结，因此@ConstructorArgs注解和@Arg注解基本使用不到。

2、通过@Results、@Result注解定义结果集映射

如果实体字段的名称与数据库表字段名称不一致时，我们就需要显式的指定映射关系。这是通过@Results、@Result注解来指定的，例如为UserMapper的selectById指定映射关系：

@Select("SELECT id,name FROM user where id= #{id}")
@Results(id = "userMap", value = {
      @Result(property = "id", column = "id", javaType = Integer.class,jdbcType = JdbcType.INTEGER,id = true),
      @Result(property = "name", column = "name",javaType = String.class,jdbcType = JdbcType.VARCHAR)})
public User selectById(int id);

其中：

• @Results注解

id属性用于给这个映射关系起一个名字(这里指定的为userMap)，其内部还包含了一个@Result[]来表示实体属性和数据库表字段的映射关系

• @Result注解

property属性是java实体属性的名称，column表示对应的数据库字段的名称。javaType和JdbcType属性可以不指定。

@Select("SELECT id,name FROM user")
@ResultMap("userMap")
public List<User> selectAll();

4、@TypeDiscriminator、@Case注解

鉴别器相关，基本没用，有空再补充

5、关联关系映射@Many、@One

假设有作者(author)和文章(article)两张数据库表，一个author可以有多个article，一个article只能属于一个author。相关表结构以及初始数据如下所示：

--author表
CREATE TABLE `author` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `name` varchar(255) NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
INSERT INTO `author` (`id`, `name`) 
VALUES 
    (1, 'tianshouzhi');
    
--article表
CREATE TABLE `article` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `title` varchar(255) NOT NULL,
  `content` longtext NOT NULL,
  `author_id` int(11) NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
INSERT INTO `article` (`id`, `title`, `content`, `author_id`)
VALUES
    (1, 'title1', 'content1', 1),
    (2, 'title2', 'content2', 1);

相应的Java实体类如下所示：

public class Article {
   private Integer id;
   private String title;
   private String content;
   private Author author;
   //...setters getters and toString...
}
public class Author {
   private Integer id;
   private String name;
   private List<Article> articles;
  
   //...setters getters and toString...
}

映射器接口定义分别如下：

ArticleMapper

public interface ArticleMapper {
    //1、根据文章id查询文章Article对象，同时通过One注解关联查询出作者Author信息
    @Select("SELECT id,title,content,author_id FROM article where id= #{articleId}")
    @Results(id = "articleWithAuthor", value = {
            @Result(property = "id", column = "id"),
            @Result(property = "title", column = "title"),
            @Result(property = "content", column = "content"),
            //property属性：指定将关联查询的结果封装到Article对象的author属性上
            //column属性指定：指定在执行@One注解中定义的select语句时，把article表的author_id字段当做参数传入
            //one属性：通过@One注解定义关联查询的语句是AuthorMapper中的findAuthorByAuthorId方法
            @Result(property = "author",column = "author_id”,
                    one = @One(select = "com.tianshouzhi.mapper.AuthorMapper.findAuthorByAuthorId"))})
    public Article findArticleWithAuthorByArticleId(@Param("articleId") int articleId);
   
    //2、根据作者(Author)的id查询其所有的文章(Article)
   @Select("SELECT id,title,content,author_id FROM article WHERE author_id=#{authorId}")
   @Results(id = "articlesWithoutAuthor", value = {
           @Result(property = "id", column = "id"),
            @Result(property = "title", column = "title"),
            @Result(property = "content", column = "content")})
   List<Article> findArticlesByAuthorId(@Param("authorId") int authorId);
}

AuthorMapper

public interface AuthorMapper {
    //根据作者id查询Author信息
    @Select("SELECT id,name FROM author WHERE id=#{authorId}")
    Author findAuthorByAuthorId(int authorId);
    //根据作者id查询Author信息，通过@Many注解关联查询出所有的文章信息
    @Select("SELECT id,name FROM author WHERE id=#{authorId}")
    @Results(id = "authorWithArticles", value = {
            @Result(property = "id", column = "id"),
            @Result(property = "name", column = "name”),
           //property属性：指定将关联查询的结果封装到Author对象的articles属性上
            //column属性指定：指定在执行@Many注解中定义的select语句时，把author表的id字段当做参数传入
            //many属性：指定通过@Many注解定义关联查询的语句是ArticleMapper中的findArticlesByAuthorId方法
            @Result(property = "articles",column = "id”,
                    many = @Many(select = "com.tianshouzhi.mapper.ArticleMapper.findArticlesByAuthorId"))})
    Author findAuthorWithArticlesByAuthorId(int authorId);
}

测试如下：

@Test
public void testOneAndMany(){
       System.out.println("===========通过@One注解查询出Article关联的Auhtor===========");
       Article article = articleMapper.findArticleWithAuthorByArticleId(1);
       System.out.println(article);
       System.out.println("===========通过@Many注解查询出Auhtor关联的Article==========");
       Author author = authorMapper.findAuthorWithArticlesByAuthorId(1);
       System.out.println(author);
   }

控制台输出结果为：

===========通过@One注解查询出Article关联的Auhtor===========
Article{id=1, title='title1', content='content1', author=Author{id=1, name='tianshouzhi', articles=null}}
===========通过@Many注解查询出Auhtor关联的Article==========
Author{id=1, name='tianshouzhi', articles=[Article{id=1, title='title1', content='content1', author=null}, Article{id=2, title='title2', content='content2', author=null}]}

3 缓存相关注解

四、参考资料

1. mybatis官方文档-Mapper Annotation
2. 2.8 mybayis注解配置详解