MyBatis 快速入门

MyBatis 的前身就是 iBatis ，是一个作用在数据持久层的对象关系映射（Object Relational Mapping，简称 ORM）框架。

Mybatis 简介

什么是 MyBatis

MyBatis 是一款持久层框架，它支持定制化 SQL、存储过程以及高级映射。MyBatis 避免了几乎所有的 JDBC 代码和手动设置参数以及获取结果集。MyBatis 可以使用简单的 XML 或注解来配置和映射原生类型、接口和 Java 的 POJO（Plain Old Java Objects，普通老式 Java 对象）为数据库中的记录。

MyBatis vs. Hibernate

MyBatis 和 Hibernate 都是 Java 世界中比较流行的 ORM 框架。我们应该了解其各自的优势，根据项目的需要去抉择在开发中使用哪个框架。

Mybatis 优势

• MyBatis 可以进行更为细致的 SQL 优化，可以减少查询字段。
• MyBatis 容易掌握，而 Hibernate 门槛较高。

Hibernate 优势

• Hibernate 的 DAO 层开发比 MyBatis 简单，Mybatis 需要维护 SQL 和结果映射。
• Hibernate 对对象的维护和缓存要比 MyBatis 好，对增删改查的对象的维护要方便。
• Hibernate 数据库移植性很好，MyBatis 的数据库移植性不好，不同的数据库需要写不同 SQL。
• Hibernate 有更好的二级缓存机制，可以使用第三方缓存。MyBatis 本身提供的缓存机制不佳。

快速入门

这里，我将以一个入门级的示例来演示 Mybatis 是如何工作的。

注：本文后面章节中的原理、源码部分也将基于这个示例来进行讲解。

数据库准备

在本示例中，需要针对一张用户表进行 CRUD 操作。其数据模型如下：

1
2
3
4
5
6
7
8
9
10
11
12
13

CREATE TABLE IF NOT EXISTS user (
    id      BIGINT(10) UNSIGNED NOT NULL AUTO_INCREMENT COMMENT 'Id',
    name    VARCHAR(10)         NOT NULL DEFAULT '' COMMENT '用户名',
    age     INT(3)              NOT NULL DEFAULT 0 COMMENT '年龄',
    address VARCHAR(32)         NOT NULL DEFAULT '' COMMENT '地址',
    email   VARCHAR(32)         NOT NULL DEFAULT '' COMMENT '邮件',
    PRIMARY KEY (id)
) COMMENT = '用户表';

INSERT INTO user (name, age, address, email)
VALUES ('张三', 18, '北京', 'xxx@163.com');
INSERT INTO user (name, age, address, email)
VALUES ('李四', 19, '上海', 'xxx@163.com');

添加 Mybatis

如果使用 Maven 来构建项目，则需将下面的依赖代码置于 pom.xml 文件中：

1
2
3
4
5

<dependency>
  <groupId>org.mybatis</groupId>
  <artifactId>mybatis</artifactId>
  <version>x.x.x</version>
</dependency>

Mybatis 配置

XML 配置文件中包含了对 MyBatis 系统的核心设置，包括获取数据库连接实例的数据源（DataSource）以及决定事务作用域和控制方式的事务管理器（TransactionManager）。

本示例中只是给出最简化的配置。

【示例】mybatis-config.xml 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
  "http://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
  <environments default="development">
    <environment id="development">
      <transactionManager type="JDBC" />
      <dataSource type="POOLED">
        <property name="driver" value="com.mysql.cj.jdbc.Driver" />
        <property name="url"
                  value="jdbc:mysql://127.0.0.1:3306/spring_tutorial?serverTimezone=UTC" />
        <property name="username" value="root" />
        <property name="password" value="root" />
      </dataSource>
    </environment>
  </environments>
  <mappers>
    <mapper resource="mybatis/mapper/UserMapper.xml" />
  </mappers>
</configuration>

说明：上面的配置文件中仅仅指定了数据源连接方式和 User 表的映射配置文件。

Mapper

Mapper.xml

个人理解，Mapper.xml 文件可以看做是 Mybatis 的 JDBC SQL 模板。

【示例】UserMapper.xml 文件

下面是一个通过 Mybatis Generator 自动生成的完整的 Mapper 文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="io.github.dunwu.spring.orm.mapper.UserMapper">
  <resultMap id="BaseResultMap" type="io.github.dunwu.spring.orm.entity.User">
    <id column="id" jdbcType="BIGINT" property="id" />
    <result column="name" jdbcType="VARCHAR" property="name" />
    <result column="age" jdbcType="INTEGER" property="age" />
    <result column="address" jdbcType="VARCHAR" property="address" />
    <result column="email" jdbcType="VARCHAR" property="email" />
  </resultMap>
  <delete id="deleteByPrimaryKey" parameterType="java.lang.Long">
    delete from user
    where id = #{id,jdbcType=BIGINT}
  </delete>
  <insert id="insert" parameterType="io.github.dunwu.spring.orm.entity.User">
    insert into user (id, name, age,
      address, email)
    values (#{id,jdbcType=BIGINT}, #{name,jdbcType=VARCHAR}, #{age,jdbcType=INTEGER},
      #{address,jdbcType=VARCHAR}, #{email,jdbcType=VARCHAR})
  </insert>
  <update id="updateByPrimaryKey" parameterType="io.github.dunwu.spring.orm.entity.User">
    update user
    set name = #{name,jdbcType=VARCHAR},
      age = #{age,jdbcType=INTEGER},
      address = #{address,jdbcType=VARCHAR},
      email = #{email,jdbcType=VARCHAR}
    where id = #{id,jdbcType=BIGINT}
  </update>
  <select id="selectByPrimaryKey" parameterType="java.lang.Long" resultMap="BaseResultMap">
    select id, name, age, address, email
    from user
    where id = #{id,jdbcType=BIGINT}
  </select>
  <select id="selectAll" resultMap="BaseResultMap">
    select id, name, age, address, email
    from user
  </select>
</mapper>

Mapper.java

Mapper.java 文件是 Mapper.xml 对应的 Java 对象。

【示例】UserMapper.java 文件

1
2
3
4
5
6
7
8
9
10
11
12
13

public interface UserMapper {

    int deleteByPrimaryKey(Long id);

    int insert(User record);

    User selectByPrimaryKey(Long id);

    List<User> selectAll();

    int updateByPrimaryKey(User record);

}

对比 UserMapper.java 和 UserMapper.xml 文件，不难发现：

UserMapper.java 中的方法和 UserMapper.xml 的 CRUD 语句元素（ <insert>、<delete>、<update>、<select>）存在一一对应关系。

在 Mybatis 中，正是通过方法的全限定名，将二者绑定在一起。

数据实体.java

【示例】User.java 文件

1
2
3
4
5
6
7
8
9
10
11
12

public class User {
    private Long id;

    private String name;

    private Integer age;

    private String address;

    private String email;

}

<insert>、<delete>、<update>、<select> 的 parameterType 属性以及 <resultMap> 的 type 属性都可能会绑定到数据实体。这样就可以把 JDBC 操作的输入输出和 JavaBean 结合起来，更加方便、易于理解。

测试程序

【示例】MybatisDemo.java 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

public class MybatisDemo {

    public static void main(String[] args) throws Exception {
        // 1. 加载 mybatis 配置文件，创建 SqlSessionFactory
        // 注：在实际的应用中，SqlSessionFactory 应该是单例
        InputStream inputStream = Resources.getResourceAsStream("mybatis/mybatis-config.xml");
        SqlSessionFactoryBuilder builder = new SqlSessionFactoryBuilder();
        SqlSessionFactory factory = builder.build(inputStream);

        // 2. 创建一个 SqlSession 实例，进行数据库操作
        SqlSession sqlSession = factory.openSession();

        // 3. Mapper 映射并执行
        Long params = 1L;
        List<User> list = sqlSession.selectList("io.github.dunwu.spring.orm.mapper.UserMapper.selectByPrimaryKey", params);
        for (User user : list) {
            System.out.println("user name: " + user.getName());
        }
        // 输出：user name: 张三
    }

}

说明：

SqlSession 接口是 Mybatis API 核心中的核心，它代表了 Mybatis 和数据库的一次完整会话。

• Mybatis 会解析配置，并根据配置创建 SqlSession 。
• 然后，Mybatis 将 Mapper 映射为 SqlSession，然后传递参数，执行 SQL 语句并获取结果。

Mybatis xml 配置

配置的详细内容请参考：“ Mybatis 官方文档之配置 ” 。

MyBatis 的配置文件包含了会深深影响 MyBatis 行为的设置和属性信息。主要配置项有以下：

• properties（属性）
• settings（设置）
• typeAliases（类型别名）
• typeHandlers（类型处理器）
• objectFactory（对象工厂）
• plugins（插件）
• environments（环境配置）
  • environment（环境变量）
    • transactionManager（事务管理器）
    • dataSource（数据源）
• databaseIdProvider（数据库厂商标识）
• mappers（映射器）

Mybatis xml 映射器

SQL XML 映射文件详细内容请参考：“ Mybatis 官方文档之 XML 映射文件 ”。

XML 映射文件只有几个顶级元素：

• cache – 对给定命名空间的缓存配置。
• cache-ref – 对其他命名空间缓存配置的引用。
• resultMap – 是最复杂也是最强大的元素，用来描述如何从数据库结果集中来加载对象。
• parameterMap – 已被废弃！老式风格的参数映射。更好的办法是使用内联参数，此元素可能在将来被移除。文档中不会介绍此元素。
• sql – 可被其他语句引用的可重用语句块。
• insert – 映射插入语句
• update – 映射更新语句
• delete – 映射删除语句
• select – 映射查询语句

Mybatis 扩展

Mybatis 类型处理器

MyBatis 在设置预处理语句（PreparedStatement）中的参数或从结果集中取出一个值时， 都会用类型处理器将获取到的值以合适的方式转换成 Java 类型。下表描述了一些默认的类型处理器。

从 3.4.5 开始，MyBatis 默认支持 JSR-310（日期和时间 API） 。

你可以重写已有的类型处理器或创建你自己的类型处理器来处理不支持的或非标准的类型。 具体做法为：实现 org.apache.ibatis.type.TypeHandler 接口， 或继承一个很便利的类 org.apache.ibatis.type.BaseTypeHandler， 并且可以（可选地）将它映射到一个 JDBC 类型。比如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// ExampleTypeHandler.java
@MappedJdbcTypes(JdbcType.VARCHAR)
public class ExampleTypeHandler extends BaseTypeHandler<String> {

  @Override
  public void setNonNullParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType) throws SQLException {
    ps.setString(i, parameter);
  }

  @Override
  public String getNullableResult(ResultSet rs, String columnName) throws SQLException {
    return rs.getString(columnName);
  }

  @Override
  public String getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
    return rs.getString(columnIndex);
  }

  @Override
  public String getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
    return cs.getString(columnIndex);
  }
}

1
2
3
4

<!-- mybatis-config.xml -->
<typeHandlers>
  <typeHandler handler="org.mybatis.example.ExampleTypeHandler"/>
</typeHandlers>

使用上述的类型处理器将会覆盖已有的处理 Java String 类型的属性以及 VARCHAR 类型的参数和结果的类型处理器。 要注意 MyBatis 不会通过检测数据库元信息来决定使用哪种类型，所以你必须在参数和结果映射中指明字段是 VARCHAR 类型， 以使其能够绑定到正确的类型处理器上。这是因为 MyBatis 直到语句被执行时才清楚数据类型。

Mybatis 插件

MyBatis 允许你在映射语句执行过程中的某一点进行拦截调用。默认情况下，MyBatis 允许使用插件来拦截的方法调用包括：

• Executor (update, query, flushStatements, commit, rollback, getTransaction, close, isClosed)
• ParameterHandler (getParameterObject, setParameters)
• ResultSetHandler (handleResultSets, handleOutputParameters)
• StatementHandler (prepare, parameterize, batch, update, query)

这些类中方法的细节可以通过查看每个方法的签名来发现，或者直接查看 MyBatis 发行包中的源代码。 如果你想做的不仅仅是监控方法的调用，那么你最好相当了解要重写的方法的行为。 因为在试图修改或重写已有方法的行为时，很可能会破坏 MyBatis 的核心模块。 这些都是更底层的类和方法，所以使用插件的时候要特别当心。

通过 MyBatis 提供的强大机制，使用插件是非常简单的，只需实现 Interceptor 接口，并指定想要拦截的方法签名即可。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// ExamplePlugin.java
@Intercepts({@Signature(
  type= Executor.class,
  method = "update",
  args = {MappedStatement.class,Object.class})})
public class ExamplePlugin implements Interceptor {
  private Properties properties = new Properties();
  public Object intercept(Invocation invocation) throws Throwable {
    // implement pre processing if need
    Object returnObject = invocation.proceed();
    // implement post processing if need
    return returnObject;
  }
  public void setProperties(Properties properties) {
    this.properties = properties;
  }
}

1
2
3
4
5
6

<!-- mybatis-config.xml -->
<plugins>
  <plugin interceptor="org.mybatis.example.ExamplePlugin">
    <property name="someProperty" value="100"/>
  </plugin>
</plugins>

上面的插件将会拦截在 Executor 实例中所有的 “update” 方法调用， 这里的 Executor 是负责执行底层映射语句的内部对象。

参考资料

• 官方
  • Mybatis Github
  • Mybatis 官网
  • MyBatis 官方代码生成（mybatis-generator）
  • MyBatis 官方集成 Spring（mybatis-spring）
  • Mybatis 官方集成 Spring Boot（mybatis-spring-boot）
• 扩展插件
  • MyBatis-Plus - CRUD 扩展插件、代码生成器、分页器等多功能
  • Mapper - CRUD 扩展插件
  • Mybatis-PageHelper - Mybatis 通用分页插件
• 文章
  • 深入理解 mybatis 原理
  • mybatis 源码中文注释
  • MyBatis Generator 详解
  • Mybatis 常见面试题
  • Mybatis 中强大的 resultMap

MyBatis 原理

MyBatis 的前身就是 iBatis ，是一款优秀的持久层框架，它支持自定义 SQL、存储过程以及高级映射。本文以一个 MyBatis 完整示例为切入点，结合 MyBatis 底层源码分析，图文并茂的讲解 MyBatis 的核心工作机制。

MyBatis 完整示例

这里，我将以一个入门级的示例来演示 MyBatis 是如何工作的。

注：本文后面章节中的原理、源码部分也将基于这个示例来进行讲解。

完整示例源码地址

数据库准备

在本示例中，需要针对一张用户表进行 CRUD 操作。其数据模型如下：

1
2
3
4
5
6
7
8
9
10
11
12
13

CREATE TABLE IF NOT EXISTS user (
    id      BIGINT(10) UNSIGNED NOT NULL AUTO_INCREMENT COMMENT 'Id',
    name    VARCHAR(10)         NOT NULL DEFAULT '' COMMENT '用户名',
    age     INT(3)              NOT NULL DEFAULT 0 COMMENT '年龄',
    address VARCHAR(32)         NOT NULL DEFAULT '' COMMENT '地址',
    email   VARCHAR(32)         NOT NULL DEFAULT '' COMMENT '邮件',
    PRIMARY KEY (id)
) COMMENT = '用户表';

INSERT INTO user (name, age, address, email)
VALUES ('张三', 18, '北京', 'xxx@163.com');
INSERT INTO user (name, age, address, email)
VALUES ('李四', 19, '上海', 'xxx@163.com');

添加 MyBatis

如果使用 Maven 来构建项目，则需将下面的依赖代码置于 pom.xml 文件中：

1
2
3
4
5

<dependency>
  <groupId>org.mybatis</groupId>
  <artifactId>mybatis</artifactId>
  <version>x.x.x</version>
</dependency>

MyBatis 配置

XML 配置文件中包含了对 MyBatis 系统的核心设置，包括获取数据库连接实例的数据源（DataSource）以及决定事务作用域和控制方式的事务管理器（TransactionManager）。

本示例中只是给出最简化的配置。

【示例】MyBatis-config.xml 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
  "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<configuration>
  <environments default="development">
    <environment id="development">
      <transactionManager type="JDBC" />
      <dataSource type="POOLED">
        <property name="driver" value="com.mysql.cj.jdbc.Driver" />
        <property name="url"
                  value="jdbc:mysql://127.0.0.1:3306/spring_tutorial?serverTimezone=UTC" />
        <property name="username" value="root" />
        <property name="password" value="root" />
      </dataSource>
    </environment>
  </environments>
  <mappers>
    <mapper resource="mybatis/mapper/UserMapper.xml" />
  </mappers>
</configuration>

说明：上面的配置文件中仅仅指定了数据源连接方式和 User 表的映射配置文件。

Mapper

Mapper.xml

个人理解，Mapper.xml 文件可以看做是 MyBatis 的 JDBC SQL 模板。

【示例】UserMapper.xml 文件

下面是一个通过 MyBatis Generator 自动生成的完整的 Mapper 文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="io.github.dunwu.spring.orm.mapper.UserMapper">
  <resultMap id="BaseResultMap" type="io.github.dunwu.spring.orm.entity.User">
    <id column="id" jdbcType="BIGINT" property="id" />
    <result column="name" jdbcType="VARCHAR" property="name" />
    <result column="age" jdbcType="INTEGER" property="age" />
    <result column="address" jdbcType="VARCHAR" property="address" />
    <result column="email" jdbcType="VARCHAR" property="email" />
  </resultMap>
  <delete id="deleteByPrimaryKey" parameterType="java.lang.Long">
    delete from user
    where id = #{id,jdbcType=BIGINT}
  </delete>
  <insert id="insert" parameterType="io.github.dunwu.spring.orm.entity.User">
    insert into user (id, name, age,
      address, email)
    values (#{id,jdbcType=BIGINT}, #{name,jdbcType=VARCHAR}, #{age,jdbcType=INTEGER},
      #{address,jdbcType=VARCHAR}, #{email,jdbcType=VARCHAR})
  </insert>
  <update id="updateByPrimaryKey" parameterType="io.github.dunwu.spring.orm.entity.User">
    update user
    set name = #{name,jdbcType=VARCHAR},
      age = #{age,jdbcType=INTEGER},
      address = #{address,jdbcType=VARCHAR},
      email = #{email,jdbcType=VARCHAR}
    where id = #{id,jdbcType=BIGINT}
  </update>
  <select id="selectByPrimaryKey" parameterType="java.lang.Long" resultMap="BaseResultMap">
    select id, name, age, address, email
    from user
    where id = #{id,jdbcType=BIGINT}
  </select>
  <select id="selectAll" resultMap="BaseResultMap">
    select id, name, age, address, email
    from user
  </select>
</mapper>

Mapper.java

Mapper.java 文件是 Mapper.xml 对应的 Java 对象。

【示例】UserMapper.java 文件

1
2
3
4
5
6
7
8
9
10
11
12
13

public interface UserMapper {

    int deleteByPrimaryKey(Long id);

    int insert(User record);

    User selectByPrimaryKey(Long id);

    List<User> selectAll();

    int updateByPrimaryKey(User record);

}

对比 UserMapper.java 和 UserMapper.xml 文件，不难发现：

UserMapper.java 中的方法和 UserMapper.xml 的 CRUD 语句元素（ <insert>、<delete>、<update>、<select>）存在一一对应关系。

在 MyBatis 中，正是通过方法的全限定名，将二者绑定在一起。

数据实体.java

【示例】User.java 文件

1
2
3
4
5
6
7
8
9
10
11
12

public class User {
    private Long id;

    private String name;

    private Integer age;

    private String address;

    private String email;

}

<insert>、<delete>、<update>、<select> 的 parameterType 属性以及 <resultMap> 的 type 属性都可能会绑定到数据实体。这样就可以把 JDBC 操作的输入输出和 JavaBean 结合起来，更加方便、易于理解。

测试程序

【示例】MybatisDemo.java 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

public class MybatisDemo {

    public static void main(String[] args) throws Exception {
        // 1. 加载 MyBatis 配置文件，创建 SqlSessionFactory
        // 注：在实际的应用中，SqlSessionFactory 应该是单例
        InputStream inputStream = Resources.getResourceAsStream("MyBatis/MyBatis-config.xml");
        SqlSessionFactoryBuilder builder = new SqlSessionFactoryBuilder();
        SqlSessionFactory factory = builder.build(inputStream);

        // 2. 创建一个 SqlSession 实例，进行数据库操作
        SqlSession sqlSession = factory.openSession();

        // 3. Mapper 映射并执行
        Long params = 1L;
        List<User> list = sqlSession.selectList("io.github.dunwu.spring.orm.mapper.UserMapper.selectByPrimaryKey", params);
        for (User user : list) {
            System.out.println("user name: " + user.getName());
        }
        // 输出：user name: 张三
    }

}

说明：

SqlSession 接口是 MyBatis API 核心中的核心，它代表了 MyBatis 和数据库的一次完整会话。

• MyBatis 会解析配置，并根据配置创建 SqlSession 。
• 然后，MyBatis 将 Mapper 映射为 SqlSession，然后传递参数，执行 SQL 语句并获取结果。

MyBatis 生命周期

SqlSessionFactoryBuilder

SqlSessionFactoryBuilder 的职责

SqlSessionFactoryBuilder 负责创建 SqlSessionFactory 实例。SqlSessionFactoryBuilder 可以从 XML 配置文件或一个预先定制的 Configuration 的实例构建出 SqlSessionFactory 的实例。

Configuration 类包含了对一个 SqlSessionFactory 实例你可能关心的所有内容。

SqlSessionFactoryBuilder 应用了建造者设计模式，它有五个 build 方法，允许你通过不同的资源创建 SqlSessionFactory 实例。

1
2
3
4
5

SqlSessionFactory build(InputStream inputStream)
SqlSessionFactory build(InputStream inputStream, String environment)
SqlSessionFactory build(InputStream inputStream, Properties properties)
SqlSessionFactory build(InputStream inputStream, String env, Properties props)
SqlSessionFactory build(Configuration config)

SqlSessionFactoryBuilder 的生命周期

SqlSessionFactoryBuilder 可以被实例化、使用和丢弃，一旦创建了 SqlSessionFactory，就不再需要它了。 因此 SqlSessionFactoryBuilder 实例的最佳作用域是方法作用域（也就是局部方法变量）。你可以重用 SqlSessionFactoryBuilder 来创建多个 SqlSessionFactory 实例，但最好还是不要一直保留着它，以保证所有的 XML 解析资源可以被释放给更重要的事情。

SqlSessionFactory

SqlSessionFactory 职责

SqlSessionFactory 负责创建 SqlSession 实例。

SqlSessionFactory 应用了工厂设计模式，它提供了一组方法，用于创建 SqlSession 实例。

1
2
3
4
5
6
7
8
9

SqlSession openSession()
SqlSession openSession(boolean autoCommit)
SqlSession openSession(Connection connection)
SqlSession openSession(TransactionIsolationLevel level)
SqlSession openSession(ExecutorType execType, TransactionIsolationLevel level)
SqlSession openSession(ExecutorType execType)
SqlSession openSession(ExecutorType execType, boolean autoCommit)
SqlSession openSession(ExecutorType execType, Connection connection)
Configuration getConfiguration();

方法说明：

• 默认的 openSession() 方法没有参数，它会创建具备如下特性的 SqlSession：
  • 事务作用域将会开启（也就是不自动提交）。
  • 将由当前环境配置的 DataSource 实例中获取 Connection 对象。
  • 事务隔离级别将会使用驱动或数据源的默认设置。
  • 预处理语句不会被复用，也不会批量处理更新。
• TransactionIsolationLevel 表示事务隔离级别，它对应着 JDBC 的五个事务隔离级别。
• ExecutorType 枚举类型定义了三个值:
  • ExecutorType.SIMPLE：该类型的执行器没有特别的行为。它为每个语句的执行创建一个新的预处理语句。
  • ExecutorType.REUSE：该类型的执行器会复用预处理语句。
  • ExecutorType.BATCH：该类型的执行器会批量执行所有更新语句，如果 SELECT 在多个更新中间执行，将在必要时将多条更新语句分隔开来，以方便理解。

SqlSessionFactory 生命周期

SqlSessionFactory 应该以单例形式在应用的运行期间一直存在。

SqlSession

SqlSession 职责

MyBatis 的主要 Java 接口就是 SqlSession。它包含了所有执行语句，获取映射器和管理事务等方法。

详细内容可以参考：“ MyBatis 官方文档之 SqlSessions ” 。

SqlSession 类的方法可以按照下图进行大致分类：

SqlSession 生命周期

SqlSessions 是由 SqlSessionFactory 实例创建的；而 SqlSessionFactory 是由 SqlSessionFactoryBuilder 创建的。

🔔 注意：当 MyBatis 与一些依赖注入框架（如 Spring 或者 Guice）同时使用时，SqlSessions 将被依赖注入框架所创建，所以你不需要使用 SqlSessionFactoryBuilder 或者 SqlSessionFactory。

每个线程都应该有它自己的 SqlSession 实例。

SqlSession 的实例不是线程安全的，因此是不能被共享的，所以它的最佳的作用域是请求或方法作用域。 绝对不能将 SqlSession 实例的引用放在一个类的静态域，甚至一个类的实例变量也不行。 也绝不能将 SqlSession 实例的引用放在任何类型的托管作用域中，比如 Servlet 框架中的 HttpSession。 正确在 Web 中使用 SqlSession 的场景是：每次收到的 HTTP 请求，就可以打开一个 SqlSession，返回一个响应，就关闭它。

编程模式：

1
2
3

try (SqlSession session = sqlSessionFactory.openSession()) {
  // 你的应用逻辑代码
}

映射器

映射器职责

映射器是一些由用户创建的、绑定 SQL 语句的接口。

SqlSession 中的 insert、update、delete 和 select 方法都很强大，但也有些繁琐。更通用的方式是使用映射器类来执行映射语句。一个映射器类就是一个仅需声明与 SqlSession 方法相匹配的方法的接口类。

MyBatis 将配置文件中的每一个 <mapper> 节点抽象为一个 Mapper 接口，而这个接口中声明的方法和跟 <mapper> 节点中的 <select|update|delete|insert> 节点相对应，即 <select|update|delete|insert> 节点的 id 值为 Mapper 接口中的方法名称，parameterType 值表示 Mapper 对应方法的入参类型，而 resultMap 值则对应了 Mapper 接口表示的返回值类型或者返回结果集的元素类型。

MyBatis 会根据相应的接口声明的方法信息，通过动态代理机制生成一个 Mapper 实例；MyBatis 会根据这个方法的方法名和参数类型，确定 Statement Id，然后和 SqlSession 进行映射，底层还是通过 SqlSession 完成和数据库的交互。

下面的示例展示了一些方法签名以及它们是如何映射到 SqlSession 上的。

注意

• 映射器接口不需要去实现任何接口或继承自任何类。只要方法可以被唯一标识对应的映射语句就可以了。
• 映射器接口可以继承自其他接口。当使用 XML 来构建映射器接口时要保证语句被包含在合适的命名空间中。而且，唯一的限制就是你不能在两个继承关系的接口中拥有相同的方法签名（潜在的危险做法不可取）。

映射器生命周期

映射器接口的实例是从 SqlSession 中获得的。因此从技术层面讲，任何映射器实例的最大作用域是和请求它们的 SqlSession 相同的。尽管如此，映射器实例的最佳作用域是方法作用域。 也就是说，映射器实例应该在调用它们的方法中被请求，用过之后即可丢弃。

编程模式：

1
2
3
4

try (SqlSession session = sqlSessionFactory.openSession()) {
  BlogMapper mapper = session.getMapper(BlogMapper.class);
  // 你的应用逻辑代码
}

• 映射器注解

MyBatis 是一个 XML 驱动的框架。配置信息是基于 XML 的，而且映射语句也是定义在 XML 中的。MyBatis 3 以后，支持注解配置。注解配置基于配置 API；而配置 API 基于 XML 配置。

MyBatis 支持诸如 @Insert、@Update、@Delete、@Select、@Result 等注解。

详细内容请参考：MyBatis 官方文档之 sqlSessions，其中列举了 MyBatis 支持的注解清单，以及基本用法。

MyBatis 的架构

从 MyBatis 代码实现的角度来看，MyBatis 的主要组件有以下几个：

• SqlSession - 作为 MyBatis 工作的主要顶层 API，表示和数据库交互的会话，完成必要数据库增删改查功能。
• Executor - MyBatis 执行器，是 MyBatis 调度的核心，负责 SQL 语句的生成和查询缓存的维护。
• StatementHandler - 封装了 JDBC Statement 操作，负责对 JDBC statement 的操作，如设置参数、将 Statement 结果集转换成 List 集合。
• ParameterHandler - 负责对用户传递的参数转换成 JDBC Statement 所需要的参数。
• ResultSetHandler - 负责将 JDBC 返回的 ResultSet 结果集对象转换成 List 类型的集合。
• TypeHandler - 负责 java 数据类型和 jdbc 数据类型之间的映射和转换。
• MappedStatement - MappedStatement 维护了一条 <select|update|delete|insert> 节点的封装。
• SqlSource - 负责根据用户传递的 parameterObject，动态地生成 SQL 语句，将信息封装到 BoundSql 对象中，并返回。
• BoundSql - 表示动态生成的 SQL 语句以及相应的参数信息。
• Configuration - MyBatis 所有的配置信息都维持在 Configuration 对象之中。

这些组件的架构层次如下：

配置层

配置层决定了 MyBatis 的工作方式。

MyBatis 提供了两种配置方式：

• 基于 XML 配置文件的方式
• 基于 Java API 的方式

SqlSessionFactoryBuilder 会根据配置创建 SqlSessionFactory ；

SqlSessionFactory 负责创建 SqlSessions 。

接口层

接口层负责和数据库交互的方式。

MyBatis 和数据库的交互有两种方式：

• 使用 SqlSession：SqlSession 封装了所有执行语句，获取映射器和管理事务的方法。
  • 用户只需要传入 Statement Id 和查询参数给 SqlSession 对象，就可以很方便的和数据库进行交互。
  • 这种方式的缺点是不符合面向对象编程的范式。
• 使用 Mapper 接口：MyBatis 会根据相应的接口声明的方法信息，通过动态代理机制生成一个 Mapper 实例；MyBatis 会根据这个方法的方法名和参数类型，确定 Statement Id，然后和 SqlSession 进行映射，底层还是通过 SqlSession 完成和数据库的交互。

数据处理层

数据处理层可以说是 MyBatis 的核心，从大的方面上讲，它要完成两个功能：

• 根据传参 Statement 和参数构建动态 SQL 语句
  • 动态语句生成可以说是 MyBatis 框架非常优雅的一个设计，MyBatis 通过传入的参数值，使用 Ognl 来动态地构造 SQL 语句，使得 MyBatis 有很强的灵活性和扩展性。
  • 参数映射指的是对于 java 数据类型和 jdbc 数据类型之间的转换：这里有包括两个过程：查询阶段，我们要将 java 类型的数据，转换成 jdbc 类型的数据，通过 preparedStatement.setXXX() 来设值；另一个就是对 resultset 查询结果集的 jdbcType 数据转换成 java 数据类型。
• 执行 SQL 语句以及处理响应结果集 ResultSet
  • 动态 SQL 语句生成之后，MyBatis 将执行 SQL 语句，并将可能返回的结果集转换成 List<E> 列表。
  • MyBatis 在对结果集的处理中，支持结果集关系一对多和多对一的转换，并且有两种支持方式，一种为嵌套查询语句的查询，还有一种是嵌套结果集的查询。

框架支撑层

• 事务管理机制 - MyBatis 将事务抽象成了 Transaction 接口。MyBatis 的事务管理分为两种形式：

  • 使用 JDBC 的事务管理机制：即利用 java.sql.Connection 对象完成对事务的提交（commit）、回滚（rollback）、关闭（close）等。
  • 使用 MANAGED 的事务管理机制：MyBatis 自身不会去实现事务管理，而是让程序的容器如（JBOSS，Weblogic）来实现对事务的管理。

• 连接池管理

• SQL 语句的配置 - 支持两种方式：

  • xml 配置
  • 注解配置

• 缓存机制 - MyBatis 采用两级缓存结构

  • 一级缓存是 Session 会话级别的缓存 - 一级缓存又被称之为本地缓存。一般而言，一个 SqlSession 对象会使用一个 Executor 对象来完成会话操作，Executor 对象会维护一个 Cache 缓存，以提高查询性能。
    • 一级缓存的生命周期是 Session 会话级别的。
  • 二级缓存是 Application 应用级别的缓存 - 用户配置了 "cacheEnabled=true"，才会开启二级缓存。
    • 如果开启了二级缓存，SqlSession 会先使用 CachingExecutor 对象来处理查询请求。CachingExecutor 会在二级缓存中查看是否有匹配的数据，如果匹配，则直接返回缓存结果；如果缓存中没有，再交给真正的 Executor 对象来完成查询，之后 CachingExecutor 会将真正 Executor 返回的查询结果放置到缓存中，然后在返回给用户。
    • 二级缓存的生命周期是应用级别的。

SqlSession 内部工作机制

从前文，我们已经了解了，MyBatis 封装了对数据库的访问，把对数据库的会话和事务控制放到了 SqlSession 对象中。那么具体是如何工作的呢？接下来，我们通过源码解读来进行分析。

SqlSession 对于 insert、update、delete、select 的内部处理机制基本上大同小异。所以，接下来，我会以一次完整的 select 查询流程为例讲解 SqlSession 内部的工作机制。相信读者如果理解了 select 的处理流程，对于其他 CRUD 操作也能做到一通百通。

SqlSession 子组件

前面的内容已经介绍了：SqlSession 是 MyBatis 的顶层接口，它提供了所有执行语句，获取映射器和管理事务等方法。

实际上，SqlSession 是通过聚合多个子组件，让每个子组件负责各自功能的方式，实现了任务的下发。

在了解各个子组件工作机制前，先让我们简单认识一下 SqlSession 的核心子组件。

Executor

Executor 即执行器，它负责生成动态 SQL 以及管理缓存。

• Executor 即执行器接口。
• BaseExecutor 是 Executor 的抽象类，它采用了模板方法设计模式，内置了一些共性方法，而将定制化方法留给子类去实现。
• SimpleExecutor 是最简单的执行器。它只会直接执行 SQL，不会做额外的事。
• BatchExecutor 是批处理执行器。它的作用是通过批处理来优化性能。值得注意的是，批量更新操作，由于内部有缓存机制，使用完后需要调用 flushStatements 来清除缓存。
• ReuseExecutor 是可重用的执行器。重用的对象是 Statement，也就是说，该执行器会缓存同一个 SQL 的 Statement，避免重复创建 Statement。其内部的实现是通过一个 HashMap 来维护 Statement 对象的。由于当前 Map 只在该 session 中有效，所以使用完后需要调用 flushStatements 来清除 Map。
• CachingExecutor 是缓存执行器。它只在启用二级缓存时才会用到。

StatementHandler

StatementHandler 对象负责设置 Statement 对象中的查询参数、处理 JDBC 返回的 resultSet，将 resultSet 加工为 List 集合返回。

StatementHandler 的家族成员：

• StatementHandler 是接口；
• BaseStatementHandler 是实现 StatementHandler 的抽象类，内置一些共性方法；
• SimpleStatementHandler 负责处理 Statement；
• PreparedStatementHandler 负责处理 PreparedStatement；
• CallableStatementHandler 负责处理 CallableStatement。
• RoutingStatementHandler 负责代理 StatementHandler 具体子类，根据 Statement 类型，选择实例化 SimpleStatementHandler、PreparedStatementHandler、CallableStatementHandler。

ParameterHandler

ParameterHandler 负责将传入的 Java 对象转换 JDBC 类型对象，并为 PreparedStatement 的动态 SQL 填充数值。

ParameterHandler 只有一个具体实现类，即 DefaultParameterHandler。

ResultSetHandler

ResultSetHandler 负责两件事：

• 处理 Statement 执行后产生的结果集，生成结果列表
• 处理存储过程执行后的输出参数

ResultSetHandler 只有一个具体实现类，即 DefaultResultSetHandler。

TypeHandler

TypeHandler 负责将 Java 对象类型和 JDBC 类型进行相互转换。

SqlSession 和 Mapper

先来回忆一下 MyBatis 完整示例章节的 测试程序部分的代码。

MybatisDemo.java 文件中的代码片段：

1
2
3
4
5
6
7
8
9

// 2. 创建一个 SqlSession 实例，进行数据库操作
SqlSession sqlSession = factory.openSession();

// 3. Mapper 映射并执行
Long params = 1L;
List<User> list = sqlSession.selectList("io.github.dunwu.spring.orm.mapper.UserMapper.selectByPrimaryKey", params);
for (User user : list) {
    System.out.println("user name: " + user.getName());
}

示例代码中，给 sqlSession 对象的传递一个配置的 Sql 语句的 Statement Id 和参数，然后返回结果

io.github.dunwu.spring.orm.mapper.UserMapper.selectByPrimaryKey 是配置在 UserMapper.xml 的 Statement ID，params 是 SQL 参数。

UserMapper.xml 文件中的代码片段：

1
2
3
4
5

<select id="selectByPrimaryKey" parameterType="java.lang.Long" resultMap="BaseResultMap">
  select id, name, age, address, email
  from user
  where id = #{id,jdbcType=BIGINT}
</select>

MyBatis 通过方法的全限定名，将 SqlSession 和 Mapper 相互映射起来。

SqlSession 和 Executor

org.apache.ibatis.session.defaults.DefaultSqlSession 中 selectList 方法的源码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

@Override
public <E> List<E> selectList(String statement) {
  return this.selectList(statement, null);
}

@Override
public <E> List<E> selectList(String statement, Object parameter) {
  return this.selectList(statement, parameter, RowBounds.DEFAULT);
}

@Override
public <E> List<E> selectList(String statement, Object parameter, RowBounds rowBounds) {
  try {
    // 1. 根据 Statement Id，在配置对象 Configuration 中查找和配置文件相对应的 MappedStatement
    MappedStatement ms = configuration.getMappedStatement(statement);
    // 2. 将 SQL 语句交由执行器 Executor 处理
    return executor.query(ms, wrapCollection(parameter), rowBounds, Executor.NO_RESULT_HANDLER);
  } catch (Exception e) {
    throw ExceptionFactory.wrapException("Error querying database.  Cause: " + e, e);
  } finally {
    ErrorContext.instance().reset();
  }
}

说明：

MyBatis 所有的配置信息都维持在 Configuration 对象之中。中维护了一个 Map<String, MappedStatement> 对象。其中，key 为 Mapper 方法的全限定名（对于本例而言，key 就是 io.github.dunwu.spring.orm.mapper.UserMapper.selectByPrimaryKey ），value 为 MappedStatement 对象。所以，传入 Statement Id 就可以从 Map 中找到对应的 MappedStatement。

MappedStatement 维护了一个 Mapper 方法的元数据信息，其数据组织可以参考下面的 debug 截图：

小结：

通过 “SqlSession 和 Mapper” 以及 “SqlSession 和 Executor” 这两节，我们已经知道：

SqlSession 的职能是：根据 Statement ID, 在 Configuration 中获取到对应的 MappedStatement 对象，然后调用 Executor 来执行具体的操作。

Executor 工作流程

继续上一节的流程，SqlSession 将 SQL 语句交由执行器 Executor 处理。Executor 又做了哪些事儿呢？

（1）执行器查询入口

1
2
3
4
5
6
7

public <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler) throws SQLException {
	// 1. 根据传参，动态生成需要执行的 SQL 语句，用 BoundSql 对象表示
    BoundSql boundSql = ms.getBoundSql(parameter);
    // 2. 根据传参，创建一个缓存Key
    CacheKey key = createCacheKey(ms, parameter, rowBounds, boundSql);
    return query(ms, parameter, rowBounds, resultHandler, key, boundSql);
 }

执行器查询入口主要做两件事：

• 生成动态 SQL：根据传参，动态生成需要执行的 SQL 语句，用 BoundSql 对象表示。
• 管理缓存：根据传参，创建一个缓存 Key。

（2）执行器查询第二入口

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

@SuppressWarnings("unchecked")
@Override
public <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql) throws SQLException {
  // 略
  List<E> list;
  try {
    queryStack++;
    list = resultHandler == null ? (List<E>) localCache.getObject(key) : null;
    // 3. 缓存中有值，则直接从缓存中取数据；否则，查询数据库
    if (list != null) {
      handleLocallyCachedOutputParameters(ms, key, parameter, boundSql);
    } else {
      list = queryFromDatabase(ms, parameter, rowBounds, resultHandler, key, boundSql);
    }
  } finally {
    queryStack--;
  }
  // 略
  return list;
}

实际查询方法主要的职能是判断缓存 key 是否能命中缓存：

• 命中，则将缓存中数据返回；
• 不命中，则查询数据库：

（3）查询数据库

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

private <E> List<E> queryFromDatabase(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey key, BoundSql boundSql) throws SQLException {
  List<E> list;
  localCache.putObject(key, EXECUTION_PLACEHOLDER);
  try {
    // 4. 执行查询，获取 List 结果，并将查询的结果更新本地缓存中
    list = doQuery(ms, parameter, rowBounds, resultHandler, boundSql);
  } finally {
    localCache.removeObject(key);
  }
  localCache.putObject(key, list);
  if (ms.getStatementType() == StatementType.CALLABLE) {
    localOutputParameterCache.putObject(key, parameter);
  }
  return list;
}

queryFromDatabase 方法的职责是调用 doQuery，向数据库发起查询，并将返回的结果更新到本地缓存。

（4）实际查询方法

SimpleExecutor 类的 doQuery()方法实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

@Override
public <E> List<E> doQuery(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) throws SQLException {
  Statement stmt = null;
  try {
    Configuration configuration = ms.getConfiguration();
    // 5. 根据既有的参数，创建StatementHandler对象来执行查询操作
    StatementHandler handler = configuration.newStatementHandler(wrapper, ms, parameter, rowBounds, resultHandler, boundSql);
    // 6. 创建java.Sql.Statement对象，传递给StatementHandler对象
    stmt = prepareStatement(handler, ms.getStatementLog());
    // 7. 调用StatementHandler.query()方法，返回List结果
    return handler.query(stmt, resultHandler);
  } finally {
    closeStatement(stmt);
  }
}

上述的 Executor.query()方法几经转折，最后会创建一个 StatementHandler 对象，然后将必要的参数传递给 StatementHandler，使用 StatementHandler 来完成对数据库的查询，最终返回 List 结果集。
从上面的代码中我们可以看出，Executor 的功能和作用是：

1. 根据传递的参数，完成 SQL 语句的动态解析，生成 BoundSql 对象，供 StatementHandler 使用；

2. 为查询创建缓存，以提高性能

3. 创建 JDBC 的 Statement 连接对象，传递给 StatementHandler 对象，返回 List 查询结果。

prepareStatement() 方法的实现：

1
2
3
4
5
6
7
8

private Statement prepareStatement(StatementHandler handler, Log statementLog) throws SQLException {
  Statement stmt;
  Connection connection = getConnection(statementLog);
  stmt = handler.prepare(connection, transaction.getTimeout());
  //对创建的Statement对象设置参数，即设置SQL 语句中 ? 设置为指定的参数
  handler.parameterize(stmt);
  return stmt;
}

对于 JDBC 的 PreparedStatement 类型的对象，创建的过程中，我们使用的是 SQL 语句字符串会包含 若干个? 占位符，我们其后再对占位符进行设值。

StatementHandler 工作流程

StatementHandler 有一个子类 RoutingStatementHandler，它负责代理其他 StatementHandler 子类的工作。

它会根据配置的 Statement 类型，选择实例化相应的 StatementHandler，然后由其代理对象完成工作。

【源码】RoutingStatementHandler

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

public RoutingStatementHandler(Executor executor, MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql) {

  switch (ms.getStatementType()) {
    case STATEMENT:
      delegate = new SimpleStatementHandler(executor, ms, parameter, rowBounds, resultHandler, boundSql);
      break;
    case PREPARED:
      delegate = new PreparedStatementHandler(executor, ms, parameter, rowBounds, resultHandler, boundSql);
      break;
    case CALLABLE:
      delegate = new CallableStatementHandler(executor, ms, parameter, rowBounds, resultHandler, boundSql);
      break;
    default:
      throw new ExecutorException("Unknown statement type: " + ms.getStatementType());
  }

}

【源码】RoutingStatementHandler 的 parameterize 方法源码

【源码】PreparedStatementHandler 的 parameterize 方法源码

StatementHandler 使用 ParameterHandler 对象来完成对 Statement 的赋值。

1
2
3
4
5

@Override
public void parameterize(Statement statement) throws SQLException {
  // 使用 ParameterHandler 对象来完成对 Statement 的设值
  parameterHandler.setParameters((PreparedStatement) statement);
}

【源码】StatementHandler 的 query 方法源码

StatementHandler 使用 ResultSetHandler 对象来完成对 ResultSet 的处理。

1
2
3
4
5
6
7

@Override
public <E> List<E> query(Statement statement, ResultHandler resultHandler) throws SQLException {
  PreparedStatement ps = (PreparedStatement) statement;
  ps.execute();
  // 使用ResultHandler来处理ResultSet
  return resultSetHandler.handleResultSets(ps);
}

ParameterHandler 工作流程

【源码】DefaultParameterHandler 的 setParameters 方法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

 @Override
 public void setParameters(PreparedStatement ps) {
// parameterMappings 是对占位符 #{} 对应参数的封装
   List<ParameterMapping> parameterMappings = boundSql.getParameterMappings();
   if (parameterMappings != null) {
     for (int i = 0; i < parameterMappings.size(); i++) {
       ParameterMapping parameterMapping = parameterMappings.get(i);
       // 不处理存储过程中的参数
       if (parameterMapping.getMode() != ParameterMode.OUT) {
         Object value;
         String propertyName = parameterMapping.getProperty();
         if (boundSql.hasAdditionalParameter(propertyName)) { // issue #448 ask first for additional params
           // 获取对应的实际数值
           value = boundSql.getAdditionalParameter(propertyName);
         } else if (parameterObject == null) {
           value = null;
         } else if (typeHandlerRegistry.hasTypeHandler(parameterObject.getClass())) {
           value = parameterObject;
         } else {
           // 获取对象中相应的属性或查找 Map 对象中的值
           MetaObject metaObject = configuration.newMetaObject(parameterObject);
           value = metaObject.getValue(propertyName);
         }

         TypeHandler typeHandler = parameterMapping.getTypeHandler();
         JdbcType jdbcType = parameterMapping.getJdbcType();
         if (value == null && jdbcType == null) {
           jdbcType = configuration.getJdbcTypeForNull();
         }
         try {
           // 通过 TypeHandler 将 Java 对象参数转为 JDBC 类型的参数
           // 然后，将数值动态绑定到 PreparedStaement 中
           typeHandler.setParameter(ps, i + 1, value, jdbcType);
         } catch (TypeException | SQLException e) {
           throw new TypeException("Could not set parameters for mapping: " + parameterMapping + ". Cause: " + e, e);
         }
       }
     }
   }
 }

ResultSetHandler 工作流程

ResultSetHandler 的实现可以概括为：将 Statement 执行后的结果集，按照 Mapper 文件中配置的 ResultType 或 ResultMap 来转换成对应的 JavaBean 对象，最后将结果返回。

【源码】DefaultResultSetHandler 的 handleResultSets 方法

handleResultSets 方法是 DefaultResultSetHandler 的最关键方法。其实现如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

@Override
public List<Object> handleResultSets(Statement stmt) throws SQLException {
  ErrorContext.instance().activity("handling results").object(mappedStatement.getId());

  final List<Object> multipleResults = new ArrayList<>();

  int resultSetCount = 0;
  // 第一个结果集
  ResultSetWrapper rsw = getFirstResultSet(stmt);
  List<ResultMap> resultMaps = mappedStatement.getResultMaps();
  // 判断结果集的数量
  int resultMapCount = resultMaps.size();
  validateResultMapsCount(rsw, resultMapCount);
  // 遍历处理结果集
  while (rsw != null && resultMapCount > resultSetCount) {
    ResultMap resultMap = resultMaps.get(resultSetCount);
    handleResultSet(rsw, resultMap, multipleResults, null);
    rsw = getNextResultSet(stmt);
    cleanUpAfterHandlingResultSet();
    resultSetCount++;
  }

  String[] resultSets = mappedStatement.getResultSets();
  if (resultSets != null) {
    while (rsw != null && resultSetCount < resultSets.length) {
      ResultMapping parentMapping = nextResultMaps.get(resultSets[resultSetCount]);
      if (parentMapping != null) {
        String nestedResultMapId = parentMapping.getNestedResultMapId();
        ResultMap resultMap = configuration.getResultMap(nestedResultMapId);
        handleResultSet(rsw, resultMap, null, parentMapping);
      }
      rsw = getNextResultSet(stmt);
      cleanUpAfterHandlingResultSet();
      resultSetCount++;
    }
  }

  return collapseSingleResultList(multipleResults);
}

参考资料

• 官方
  • MyBatis Github
  • MyBatis 官网
• 文章
  • 深入理解 MyBatis 原理
  • MyBatis 源码中文注释
  • MyBatis 中强大的 resultMap

Shiro 快速入门

Shiro 是一个安全框架，具有认证、授权、加密、会话管理功能。

一、Shiro 简介

Shiro 特性

核心功能：

• Authentication - 认证。验证用户是不是拥有相应的身份。
• Authorization - 授权。验证某个已认证的用户是否拥有某个权限；即判断用户是否能做事情，常见的如：验证某个用户是否拥有某个角色。或者细粒度的验证某个用户对某个资源是否具有某个权限。
• Session Manager - 会话管理。即用户登录后就是一次会话，在没有退出之前，它的所有信息都在会话中。会话可以是普通 JavaSE 环境的，也可以是如 Web 环境的。
• Cryptography - 加密。保护数据的安全性，如密码加密存储到数据库，而不是明文存储。

辅助功能：

• Web Support - Web 支持。可以非常容易的集成到 Web 环境；
• Caching - 缓存。比如用户登录后，其用户信息、拥有的角色 / 权限不必每次去查，这样可以提高效率；
• Concurrency - 并发。Shiro 支持多线程应用的并发验证，即如在一个线程中开启另一个线程，能把权限自动传播过去；
• Testing - 测试。提供测试支持；
• Run As - 运行方式。允许一个用户假装为另一个用户（如果他们允许）的身份进行访问；
• Remember Me - 记住我。即一次登录后，下次再访问免登录。

:bell: 注意：Shiro 不会去维护用户、维护权限；这些需要我们自己去提供；然后通过相应的接口注入给 Shiro 即可。

Shiro 架构概述

• Subject - 主题。它代表当前用户，Subject 可以是一个人，但也可以是第三方服务、守护进程帐户、时钟守护任务或者其它——当前和软件交互的任何事件。Subject 是 Shiro 的入口。

  • Principals 是 Subject 的“识别属性”。Principals 可以是任何可以识别 Subject 的东西，例如名字（姓氏），姓氏（姓氏或姓氏），用户名，社会保险号等。当然，Principals 在应用程序中最好是惟一的。
  • Credentials 通常是仅由 Subject 知道的秘密值，用作他们实际上“拥有”所主张身份的佐证 凭据的一些常见示例是密码，生物特征数据（例如指纹和视网膜扫描）以及 X.509 证书。

• SecurityManager - 安全管理。它是 Shiro 的核心，所有与安全有关的操作（认证、授权、及会话、缓存的管理）都与 SecurityManager 交互，且它管理着所有 Subject。

• Realm - 域。用于访问安全相关数据，可以视为应用自身的数据源，需要开发者自己实现。Shiro 会通过 Realm 获取安全数据（如用户、角色、权限），就是说 SecurityManager 要验证用户身份，那么它需要从 Realm 获取相应的用户进行比较以确定用户身份是否合法；也需要从 Realm 得到用户相应的角色/权限进行验证用户是否能进行操作；可以把 Realm 看成 DataSource，即安全数据源。

SecurityManager

SecurityManager 是 Shiro 框架核心中的核心，它相当于 Shiro 的总指挥，负责调度所有行为，包括：认证、授权、获取安全数据（调用 Realm）、会话管理等。

SecurityManager 聚合了以下组件：

• Authenticator - 认证器，负责认证。如果用户需要定制认证策略，可以实现此接口。
• Authorizer - 授权器，负责权限控制。用来决定主体是否有权限进行相应的操作；即控制着用户能访问应用中的哪些功能；
• SessionManager - 会话管理器。Shiro 抽象了一个自己的 Session 来管理主体与应用之间交互的数据。
• SessionDAO - 会话 DAO 用于存储会话，需要用户自己实现。
• CacheManager - 缓存控制器。用于管理如用户、角色、权限等信息的缓存。
• Cryptography - 密码器。用于对数据加密、解密。

二、Shiro 认证

认证 Subject

验证 Subject 的过程可以有效地分为三个不同的步骤：

（1）收集 Subject 提交的 Principals 和 Credentials

1
2
3
4
5

//Example using most common scenario of username/password pair:
UsernamePasswordToken token = new UsernamePasswordToken(username, password);

//"Remember Me" built-in:
token.setRememberMe(true);

（2）提交 Principals 和 Credentials 以进行身份验证。

1
2
3

Subject currentUser = SecurityUtils.getSubject();

currentUser.login(token);

（3）如果提交成功，则允许访问，否则重试身份验证或阻止访问。

1
2
3
4
5
6
7
8
9
10

try {
    currentUser.login(token);
} catch ( UnknownAccountException uae ) { ...
} catch ( IncorrectCredentialsException ice ) { ...
} catch ( LockedAccountException lae ) { ...
} catch ( ExcessiveAttemptsException eae ) { ...
} ... catch your own ...
} catch ( AuthenticationException ae ) {
    //unexpected error?
}

Remembered 和 Authenticated

• Remembered - 记住我。被记住的 Subject 不是匿名的，并且具有已知的身份（即 subject.getPrincipals() 是非空的）。 但是，在先前的会话期间，通过先前的身份验证会记住此身份。 如果 subject.isRemembered() 返回 true，则认为该主题已被记住。
• Authenticated - 已认证。已认证的 Subject 是在当前会话期间已成功认证的 Subject。 如果 subject.isAuthenticated() 返回 true，则认为该 Subject 已通过身份验证。

登出

当 Subject 与应用程序完成交互后，可以调用 subject.logout() 登出，即放弃所有标识信息。

1

currentUser.logout();

认证流程

1. 应用程序代码调用 Subject.login 方法，传入构造的 AuthenticationToken 实例，该实例代表最终用户的 Principals 和 Credentials。

2. Subject 实例（通常是 DelegatingSubject（或子类））通过调用 securityManager.login（token）委托应用程序的 SecurityManager，在此处开始实际的身份验证工作。

3. SecurityManager 接收令牌，并通过调用 authenticator.authenticate（token）来简单地委派给其内部 Authenticator 实例。这几乎总是一个 ModularRealmAuthenticator 实例，它支持在身份验证期间协调一个或多个 Realm 实例。

4. 如果为该应用程序配置了多个 Realm，则 ModularRealmAuthenticator 实例将利用其配置的 AuthenticationStrategy 发起多域验证尝试。在调用领域进行身份验证之前，期间和之后，将调用 AuthenticationStrategy 以使其对每个领域的结果做出反应。

5. 请咨询每个已配置的 Realm，以查看其是否支持提交的 AuthenticationToken。 如果是这样，将使用提交的令牌调用支持 Realm 的 getAuthenticationInfo 方法。 getAuthenticationInfo 方法有效地表示对该特定 Realm 的单个身份验证尝试。

认证策略

当为一个应用程序配置两个或多个领域时，ModularRealmAuthenticator 依赖于内部 AuthenticationStrategy 组件来确定认证尝试成功或失败的条件。

例如，如果只有一个 Realm 成功地对 AuthenticationToken 进行身份验证，而所有其他 Realm 都失败了，那么该身份验证尝试是否被视为成功？还是必须所有领域都成功进行身份验证才能将整体尝试视为成功？或者，如果某个领域成功通过身份验证，是否有必要进一步咨询其他领域？ AuthenticationStrategy 根据应用程序的需求做出适当的决定。

AuthenticationStrategy 是无状态组件，在尝试进行身份验证时会被查询 4 次（这 4 种交互所需的任何必要状态都将作为方法参数给出）：

• 在任何领域被调用之前
• 在调用单个 Realm 的 getAuthenticationInfo 方法之前
• 在调用单个 Realm 的 getAuthenticationInfo 方法之后
• 在所有领域都被调用之后

AuthenticationStrategy 还负责汇总每个成功 Realm 的结果，并将它们“捆绑”成单个 AuthenticationInfo 表示形式。最终的聚合 AuthenticationInfo 实例是 Authenticator 实例返回的结果，也是 Shiro 用来表示主体的最终身份（也称为委托人）的东西。

:link: 更多认证细节可以参考：Apache Shiro Authentication

三、Shiro 授权

授权，也称为访问控制，是管理对资源的访问的过程。 换句话说，控制谁有权访问应用程序中的内容。

授权元素

授权有三个核心要素：权限、角色和用户。

权限

权限示例：

• 打开一个文件
• 查看 /user/list web 页面
• 查询记录
• 删除一条记录
• …

大多数资源都支持一般的 CRUD 操作。除此以外，对于一些特定的资源，任何有意义的行为都是可以的。基本的设计思路是：权限控制，至少是基于资源和行为。

角色

角色是一个命名实体，通常代表一组行为或职责。这些行为会转化为：谁可以在应用程序中执行哪些行为？谁不可以在程序中执行哪些行为？

角色通常是分配给用户帐户的，因此通过关联，用户可以获得自身角色所赋予的权限。

用户

用户本质上是应用程序的“用户”。

用户（即 Shiro 的 Subject）通过与角色或直接权限的关联在应用程序中执行某些行为。

基于角色的授权

如果授权是基于角色赋予权限的数据模型，编程模式如下：

【示例一】

1
2
3
4
5
6
7

Subject currentUser = SecurityUtils.getSubject();

if (currentUser.hasRole("administrator")) {
    //show the admin button
} else {
    //don't show the button?  Grey it out?
}

【示例二】

1
2
3
4
5
6

Subject currentUser = SecurityUtils.getSubject();

// 检查当前 Subject 是否有某种权限
// 如果有，直接跳过；如果没有，Shiro 会抛出 AuthorizationException
currentUser.checkRole("bankTeller");
openBankAccount();

提示：方式二相比方式一，代码更简洁

基于权限的授权

更好的授权策略通常是基于权限的授权。基于权限的授权，由于它和应用程序的原始功能（针对具体资源上的行为）紧密相关，所以基于权限的授权源代码会在功能更改时同步更改（而不是在安全策略发生更改时）。 这意味着与类似的基于角色的授权代码相比，修改代码的影响面要小得多。

【示例】基于对象的权限检查

1
2
3
4
5
6
7
8
9

Permission printPermission = new PrinterPermission("laserjet4400n", "print");

Subject currentUser = SecurityUtils.getSubject();

if (currentUser.isPermitted(printPermission)) {
    //show the Print button
} else {
    //don't show the button?  Grey it out?
}

在对象中存储权限控制信息，但这种方式较为繁重

【示例】字符串定义权限控制信息

1
2
3
4
5
6
7

Subject currentUser = SecurityUtils.getSubject();

if (currentUser.isPermitted("printer:print:laserjet4400n")) {
    //show the Print button
} else {
    //don't show the button?  Grey it out?
}

使用 : 分隔，表示资源类型、行为、资源 ID，Shiro 提供了默认实现： org.apache.shiro.authz.permission.WildcardPermission。

这种权限控制方式的好处在于：轻量、灵活。

基于注解的授权

Shiro 提供了一些用于授权的注解，来进一步简化授权代码。

@RequiresAuthentication

@RequiresAuthentication 注解要求当前 Subject 必须是已认证用户才可以访问被修饰的方法。

【示例】

1
2
3
4
5
6

@RequiresAuthentication
public void updateAccount(Account userAccount) {
    //this method will only be invoked by a
    //Subject that is guaranteed authenticated
    ...
}

@RequiresGuest

@RequiresGuest 注解要求当前 Subject 的角色是 guest 才可以访问被修饰的方法。

授权流程

1. 应用程序或框架代码调用任何 Subject 的 hasRole*，checkRole*，isPermitted* 或 checkPermission* 方法，并传入所需的权限或角色。

2. Subject 实例，通常是 DelegatingSubject（或子类），通过调用 securityManager 几乎相同的各自 hasRole*，checkRole*，isPermitted* 或 checkPermission* 方法来委托 SecurityManager （实现了 org.apache.shiro.authz.Authorizer 接口）处理授权。

3. SecurityManager 通过调用授权者各自的 hasRole*，checkRole*，isPermitted* 或 checkPermission* 方法来中继/委托其内部的 org.apache.shiro.authz.Authorizer 实例。默认情况下，authorizer 实例是 ModularRealmAuthorizer 实例，该实例支持在任何授权操作期间协调一个或多个 Realm 实例。

4. 检查每个已配置的 Realm，以查看其是否实现相同的 Authorizer 接口。如果是这样，则将调用 Realm 各自的 hasRole*，checkRole*，isPermitted* 或 checkPermission* 方法。

:link: 更多授权细节可以参考：Apache Shiro Authorization

四、Shiro 会话管理

Shiro 提供了一套独特的会话管理方案：其 Session 可以使用 Java SE 程序，也可以使用于 Java Web 程序。

在 Shiro 中，SessionManager 负责管理应用所有 Subject 的会话，如：创建、删除、失效、验证等。

【示例】会话使用示例

1
2
3
4

Subject currentUser = SecurityUtils.getSubject();

Session session = currentUser.getSession();
session.setAttribute( "someKey", someValue);

会话超时

默认情况下，Shiro 中的会话有效期为 30 分钟，超时后，该会话将被 Shiro 视为无效。

可以通过 globalSessionTimeout 方法设置 Shiro 会话超时时间。

会话监听

Shiro 提供了 SessionListener 接口（或 SessionListenerAdapter 接口），用于监听重要的会话事件，并允许使用者在事件触发时做定制化处理。

【示例】

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

public class ShiroSessionListener implements SessionListener {

    private final Logger log = LoggerFactory.getLogger(this.getClass());

    private final AtomicInteger sessionCount = new AtomicInteger(0);

    @Override
    public void onStart(Session session) {
        sessionCount.incrementAndGet();
    }

    @Override
    public void onStop(Session session) {
        sessionCount.decrementAndGet();
    }

    @Override
    public void onExpiration(Session session) {
        sessionCount.decrementAndGet();
    }
}

会话存储

大多数情况下，应用需要保存会话信息，以便在稍后可以使用它。

Shiro 提供了 SessionManager 接口，负责将针对会话的 CRUD 操作委派给内部组件 SessionDAO，该组件反映了数据访问对象（DAO）设计模式。

:bell: 注意：由于会话通常具有时效性，所以一般会话天然适合存储于缓存中。存储于 Redis 中是一个不错的选择。

五、Realm

Realm 是 Shiro 访问程序安全相关数据（如：用户、角色、权限）的接口。

Realm 是有开发者自己实现的，开发者可以通过实现 Realm 接口，接入应用的数据源，如：JDBC、文件、Nosql 等等。

认证令牌

Shiro 支持身份验证令牌。在咨询 Realm 进行认证尝试之前，将调用其支持方法。 如果返回值为 true，则仅会调用其 getAuthenticationInfo(token) 方法。通常，Realm 会检查所提交令牌的类型（接口或类），以查看其是否可以处理它。

令牌认证处理流程如下：

1. 检查用于标识 principal 的令牌（帐户标识信息）。
2. 根据 principal，在数据源中查找相应的帐户数据。
3. 确保令牌提供的凭证与数据存储中存储的凭证匹配。
4. 如果 credentials 匹配，则返回 AuthenticationInfo 实例。
5. 如果 credentials 不匹配，则抛出 AuthenticationException 异常。

加密

通过前文，可以了解：Shiro 需要通过一对 principal 和 credentials 来确认身份是否匹配（即认证）。

一般来说，成熟软件是不允许存储账户、密码这些敏感数据时，使用明文存储。所以，通常要将密码加密后存储。

Shiro 提供了一些加密器，其思想就是用 MD5、SHA 这种数字签名算法，加 Salt，然后转为 Base64 字符串。为了避免被暴力破解，Shiro 使用多次加密的方式获得最终的 credentials 字符串。

【示例】Shiro 加密密码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

import org.apache.shiro.crypto.hash.Sha256Hash;
import org.apache.shiro.crypto.RandomNumberGenerator;
import org.apache.shiro.crypto.SecureRandomNumberGenerator;
...

//We'll use a Random Number Generator to generate salts.  This
//is much more secure than using a username as a salt or not
//having a salt at all.  Shiro makes this easy.
//
//Note that a normal app would reference an attribute rather
//than create a new RNG every time:
RandomNumberGenerator rng = new SecureRandomNumberGenerator();
Object salt = rng.nextBytes();

//Now hash the plain-text password with the random salt and multiple
//iterations and then Base64-encode the value (requires less space than Hex):
String hashedPasswordBase64 = new Sha256Hash(plainTextPassword, salt, 1024).toBase64();

User user = new User(username, hashedPasswordBase64);
//save the salt with the new account.  The HashedCredentialsMatcher
//will need it later when handling login attempts:
user.setPasswordSalt(salt);
userDAO.create(user);

六、配置

过滤链

运行 Web 应用程序时，Shiro 将创建一些有用的默认 Filter 实例。

RememberMe

1
2
3

UsernamePasswordToken token = new UsernamePasswordToken(username, password);
token.setRememberMe(true);
SecurityUtils.getSubject().login(token);

参考资料

• Shiro 官方文档
• 跟我学 Shiro
• The New RBAC: Resource-Based Access Control

Spring Security 快速入门

快速开始

参考：Securing a Web Application

核心 API

设计原理

Spring Security 对于 Servlet 的支持基于过滤链（FilterChain）实现。

Spring 提供了一个名为 DelegatingFilterProxy 的 Filter 实现，该实现允许在 Servlet 容器的生命周期和 Spring 的 ApplicationContext 之间进行桥接。 Servlet 容器允许使用其自己的标准注册 Filters，但它不了解 Spring 定义的 Bean。 DelegatingFilterProxy 可以通过标准的 Servlet 容器机制进行注册，但是可以将所有工作委托给实现 Filter 的 Spring Bean。

1
2
3
4
5
6
7

public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
    // Lazily get Filter that was registered as a Spring Bean
    // For the example in DelegatingFilterProxy delegate is an instance of Bean Filter0
    Filter delegate = getFilterBean(someBeanName);
    // delegate work to the Spring Bean
    delegate.doFilter(request, response);
}

FilterChainProxy 使用 SecurityFilterChain 确定应对此请求调用哪些 Spring Security 过滤器。

SecurityFilterChain 中的安全过滤器通常是 Bean，但它们是使用 FilterChainProxy 而不是 DelegatingFilterProxy 注册的。

实际上，FilterChainProxy 可用于确定应使用哪个 SecurityFilterChain。如果您的应用程序可以为不同的模块提供完全独立的配置。

ExceptionTranslationFilter 可以将 AccessDeniedException 和 AuthenticationException 转换为 HTTP 响应。

核心源码：

1
2
3
4
5
6
7
8
9

try {
    filterChain.doFilter(request, response);
} catch (AccessDeniedException | AuthenticationException e) {
    if (!authenticated || e instanceof AuthenticationException) {
        startAuthentication();
    } else {
        accessDenied();
    }
}

认证

数据模型

Spring Security 框架中的认证数据模型如下：

• Authentication - 认证信息实体。
  • principal - 用户标识。如：用户名、账户名等。通常是 UserDetails 的实例（后面详细讲解）。
  • credentials - 认证凭证。如：密码等。
  • authorities - 授权信息。如：用户的角色、权限等信息。
• SecurityContext - 安全上下文。包含一个 Authentication 对象。
• SecurityContextHolder - 安全上下文持有者。用于存储认证信息。

【示例】注册认证信息

1
2
3
4
5

SecurityContext context = SecurityContextHolder.createEmptyContext();
Authentication authentication =
    new TestingAuthenticationToken("username", "password", "ROLE_USER");
context.setAuthentication(authentication);
SecurityContextHolder.setContext(context);

【示例】访问认证信息

认证基本流程

AbstractAuthenticationProcessingFilter 用作验证用户凭据的基本过滤器。 在对凭证进行身份验证之前，Spring Security 通常使用 AuthenticationEntryPoint 请求凭证。

• （1）当用户提交其凭据时，AbstractAuthenticationProcessingFilter 从要验证的 HttpServletRequest 创建一个 Authentication。创建的身份验证类型取决于 AbstractAuthenticationProcessingFilter 的子类。例如，UsernamePasswordAuthenticationFilter 根据在 HttpServletRequest 中提交的用户名和密码来创建 UsernamePasswordAuthenticationToken。
• （2）接下来，将身份验证传递到 AuthenticationManager 进行身份验证。
• （3）如果身份验证失败，则认证失败
  • 清除 SecurityContextHolder。
  • 调用 RememberMeServices.loginFail。如果没有配置 remember me，则为空。
  • 调用 AuthenticationFailureHandler。
• （4）如果身份验证成功，则认证成功。
  • 如果是新的登录，则通知 SessionAuthenticationStrategy。
  • 身份验证是在 SecurityContextHolder 上设置的。之后，SecurityContextPersistenceFilter 将 SecurityContext 保存到 HttpSession 中。
  • 调用 RememberMeServices.loginSuccess。如果没有配置 remember me，则为空。
  • ApplicationEventPublisher 发布一个 InteractiveAuthenticationSuccessEvent。

用户名/密码认证

读取用户名和密码的方式：

• 表单
• 基本认证
• 数字认证

存储机制

• 内存
• JDBC
• UserDetailsService
• LDAP

表单认证

spring security 支持通过从 html 表单获取登录时提交的用户名、密码。

一旦，登录信息被提交，UsernamePasswordAuthenticationFilter 就会验证用户名和密码。

基本认证

1
2
3
4
5

protected void configure(HttpSecurity http) {
    http
        // ...
        .httpBasic(withDefaults());
}

内存认证

InMemoryUserDetailsManager 实现了 UserDetailsService ，提供了基本的用户名、密码认证，其认证数据存储在内存中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

@Bean
public UserDetailsService users() {
    // The builder will ensure the passwords are encoded before saving in memory
    UserBuilder users = User.withDefaultPasswordEncoder();
    UserDetails user = users
        .username("user")
        .password("password")
        .roles("USER")
        .build();
    UserDetails user = users
        .username("admin")
        .password("password")
        .roles("USER", "ADMIN")
        .build();
    return new InMemoryUserDetailsManager(user, admin);
}

JDBC 认证

JdbcUserDetailsManager 实现了 UserDetailsService ，提供了基本的用户名、密码认证，其认证数据存储在关系型数据库中，通过 JDBC 方式访问。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

@Bean
UserDetailsManager users(DataSource dataSource) {
    UserDetails user = User.builder()
        .username("user")
        .password("{bcrypt}$2a$10$GRLdNijSQMUvl/au9ofL.eDwmoohzzS7.rmNSJZ.0FxO/BTk76klW")
        .roles("USER")
        .build();
    UserDetails admin = User.builder()
        .username("admin")
        .password("{bcrypt}$2a$10$GRLdNijSQMUvl/au9ofL.eDwmoohzzS7.rmNSJZ.0FxO/BTk76klW")
        .roles("USER", "ADMIN")
        .build();
    JdbcUserDetailsManager users = new JdbcUserDetailsManager(dataSource);
    users.createUser()
}

基本的 scheam：

1
2
3
4
5
6
7
8
9
10
11
12

create table users(
    username varchar_ignorecase(50) not null primary key,
    password varchar_ignorecase(50) not null,
    enabled boolean not null
);

create table authorities (
    username varchar_ignorecase(50) not null,
    authority varchar_ignorecase(50) not null,
    constraint fk_authorities_users foreign key(username) references users(username)
);
create unique index ix_auth_username on authorities (username,authority);

UserDetailsService

UserDetails 由 UserDetailsService 返回。 DaoAuthenticationProvider 验证 UserDetails，然后返回身份验证，该身份验证的主体是已配置的 UserDetailsService 返回的 UserDetails。

DaoAuthenticationProvider 使用 UserDetailsService 检索用户名，密码和其他用于使用用户名和密码进行身份验证的属性。 Spring Security 提供 UserDetailsService 的内存中和 JDBC 实现。

您可以通过将自定义 UserDetailsService 公开为 bean 来定义自定义身份验证。

PasswordEncoder

Spring Security 的 servlet 支持通过与 PasswordEncoder 集成来安全地存储密码。 可以通过公开一个 PasswordEncoder Bean 来定制 Spring Security 使用的 PasswordEncoder 实现。

Remember-Me

Spring Boot 集成

@EnableWebSecurity 和 @Configuration 注解一起使用, 注解 WebSecurityConfigurer 类型的类。

或者利用@EnableWebSecurity注解继承 WebSecurityConfigurerAdapter 的类，这样就构成了 Spring Security 的配置。

• configure(WebSecurity)：通过重载该方法，可配置 Spring Security 的 Filter 链。
• configure(HttpSecurity)：通过重载该方法，可配置如何通过拦截器保护请求。

参考资料

• Spring Security Architecture
• Securing a Web Application

Netty 快速入门

Netty 简介

Netty 是一款基于 NIO（Nonblocking I/O，非阻塞 IO）开发的网络通信框架。

Netty 的特性

• 高并发：Netty 是一款基于 NIO（Nonblocking IO，非阻塞 IO）开发的网络通信框架，对比于 BIO（Blocking I/O，阻塞 IO），他的并发性能得到了很大提高。
• 传输快：Netty 的传输依赖于内存零拷贝特性，尽量减少不必要的内存拷贝，实现了更高效率的传输。
• 封装好：Netty 封装了 NIO 操作的很多细节，提供了易于使用调用接口。

核心组件

• Channel：Netty 网络操作抽象类，它除了包括基本的 I/O 操作，如 bind、connect、read、write 等。
• EventLoop：主要是配合 Channel 处理 I/O 操作，用来处理连接的生命周期中所发生的事情。
• ChannelFuture：Netty 框架中所有的 I/O 操作都为异步的，因此我们需要 ChannelFuture 的 addListener()注册一个 ChannelFutureListener 监听事件，当操作执行成功或者失败时，监听就会自动触发返回结果。
• ChannelHandler：充当了所有处理入站和出站数据的逻辑容器。ChannelHandler 主要用来处理各种事件，这里的事件很广泛，比如可以是连接、数据接收、异常、数据转换等。
• ChannelPipeline：为 ChannelHandler 链提供了容器，当 channel 创建时，就会被自动分配到它专属的 ChannelPipeline，这个关联是永久性的。

Netty 有两种发送消息的方式：

• 直接写入 Channel 中，消息从 ChannelPipeline 当中尾部开始移动；
• 写入和 ChannelHandler 绑定的 ChannelHandlerContext 中，消息从 ChannelPipeline 中的下一个 ChannelHandler 中移动。

高性能

Netty 高性能表现在哪些方面：

• NIO 线程模型：同步非阻塞，用最少的资源做更多的事。
• 内存零拷贝：尽量减少不必要的内存拷贝，实现了更高效率的传输。
• 内存池设计：申请的内存可以重用，主要指直接内存。内部实现是用一颗二叉查找树管理内存分配情况。
• 串形化处理读写：避免使用锁带来的性能开销。
• 高性能序列化协议：支持 protobuf 等高性能序列化协议。

零拷贝

传统意义的拷贝

是在发送数据的时候，传统的实现方式是：

File.read(bytes)

Socket.send(bytes)

这种方式需要四次数据拷贝和四次上下文切换：

1. 数据从磁盘读取到内核的 read buffer

2. 数据从内核缓冲区拷贝到用户缓冲区

3. 数据从用户缓冲区拷贝到内核的 socket buffer

4. 数据从内核的 socket buffer 拷贝到网卡接口（硬件）的缓冲区

零拷贝的概念

明显上面的第二步和第三步是非必要的，通过 java 的 FileChannel.transferTo 方法，可以避免上面两次多余的拷贝（当然这需要底层操作系统支持）

• 调用 transferTo，数据从文件由 DMA 引擎拷贝到内核 read buffer
• 接着 DMA 从内核 read buffer 将数据拷贝到网卡接口 buffer

上面的两次操作都不需要 CPU 参与，所以就达到了零拷贝。

Netty 中的零拷贝

主要体现在三个方面：

bytebuffer

Netty 发送和接收消息主要使用 bytebuffer，bytebuffer 使用对外内存（DirectMemory）直接进行 Socket 读写。

原因：如果使用传统的堆内存进行 Socket 读写，JVM 会将堆内存 buffer 拷贝一份到直接内存中然后再写入 socket，多了一次缓冲区的内存拷贝。DirectMemory 中可以直接通过 DMA 发送到网卡接口

Composite Buffers

传统的 ByteBuffer，如果需要将两个 ByteBuffer 中的数据组合到一起，我们需要首先创建一个 size=size1+size2 大小的新的数组，然后将两个数组中的数据拷贝到新的数组中。但是使用 Netty 提供的组合 ByteBuf，就可以避免这样的操作，因为 CompositeByteBuf 并没有真正将多个 Buffer 组合起来，而是保存了它们的引用，从而避免了数据的拷贝，实现了零拷贝。

对于 FileChannel.transferTo 的使用

Netty 中使用了 FileChannel 的 transferTo 方法，该方法依赖于操作系统实现零拷贝。

Netty 流程

应用

Netty 是一个广泛使用的 Java 网络编程框架。很多著名软件都使用了它，如：Dubbo、Cassandra、Elasticsearch、Vert.x 等。

有了 Netty，你可以实现自己的 HTTP 服务器，FTP 服务器，UDP 服务器，RPC 服务器，WebSocket 服务器，Redis 的 Proxy 服务器，MySQL 的 Proxy 服务器等等。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

public class NettyOioServer {

    public void server(int port) throws Exception {
        final ByteBuf buf = Unpooled.unreleasableBuffer(
                Unpooled.copiedBuffer("Hi!\r\n", Charset.forName("UTF-8")));
        EventLoopGroup group = new OioEventLoopGroup();
        try {
            ServerBootstrap b = new ServerBootstrap();        //1

            b.group(group)                                    //2
             .channel(OioServerSocketChannel.class)
             .localAddress(new InetSocketAddress(port))
             .childHandler(new ChannelInitializer<SocketChannel>() {//3
                 @Override
                 public void initChannel(SocketChannel ch)
                     throws Exception {
                     ch.pipeline().addLast(new ChannelInboundHandlerAdapter() {            //4
                         @Override
                         public void channelActive(ChannelHandlerContext ctx) throws Exception {
                             ctx.writeAndFlush(buf.duplicate()).addListener(ChannelFutureListener.CLOSE);//5
                         }
                     });
                 }
             });
            ChannelFuture f = b.bind().sync();  //6
            f.channel().closeFuture().sync();
        } finally {
            group.shutdownGracefully().sync();        //7
        }
    }
}

参考资料

• 官方
  • Netty 官网
  • Netty Github
• 文章
  • Netty 入门教程——认识 Netty
  • 彻底理解 Netty，这一篇文章就够了
  • Java 200+ 面试题补充 ② Netty 模块

Java 缓存中间件

关键词：Spring Cache、J2Cache、JetCache

一 、JSR 107

JSR107 中制订了 Java 缓存的规范。

因此，在很多缓存框架、缓存库中，其 API 都参考了 JSR 107 规范。

Java Caching 定义了 5 个核心接口

• CachingProvider - 定义了创建、配置、获取、管理和控制多个 CacheManager。一个应用可以在运行期访问多个 CachingProvider。
• CacheManager - 定义了创建、配置、获取、管理和控制多个唯一命名的 Cache，这些 Cache 存在于 CacheManager 的上下文中。一个 CacheManager 仅被一个 CachingProvider 所拥有。
• Cache - 是一个类似 Map 的数据结构并临时存储以 Key 为索引的值。一个 Cache 仅被一个 CacheManager 所拥有。
• Entry - 是一个存储在 Cache 中的 key-value 对。
• Expiry - 每一个存储在 Cache 中的条目有一个定义的有效期，即 Expiry Duration。一旦超过这个时间，条目为过期的状态。一旦过期，条目将不可访问、更新和删除。缓存有效期可以通过 ExpiryPolicy 设置。

二、Spring Cache

详见：Spring Cache 官方文档

Spring 作为 Java 开发最著名的框架，也提供了缓存功能的框架—— Spring Cache。

Spring 支持基于注释（annotation）的缓存（cache）技术，它本质上不是一个具体的缓存实现方案（例如：EHCache 或 OSCache），而是一个对缓存使用的抽象，通过在既有代码中添加少量它定义的各种 annotation，即能够达到缓存方法的返回对象的效果。

Spring Cache 的特点：

• 通过缓存注解即可支持缓存功能
• 支持 Spring EL 表达式
• 支持 AspectJ
• 支持自定义 key 和缓存管理

开启缓存注解

Spring 为缓存功能提供了注解功能，但是你必须启动注解。

有两种方式：

（一）使用标记注解 @EnableCaching

这种方式对于 Spring 或 Spring Boot 项目都适用。

1
2
3
4

@Configuration
@EnableCaching
public class AppConfig {
}

（二）在 xml 中声明

1

<cache:annotation-driven cache-manager="cacheManager"/>

spring 缓存注解 API

Spring 对缓存的支持类似于对事务的支持。

首先使用注解标记方法，相当于定义了切点，然后使用 Aop 技术在这个方法的调用前、调用后获取方法的入参和返回值，进而实现了缓存的逻辑。

@Cacheable

@Cacheable 用于触发缓存。

表明所修饰的方法是可以缓存的：当第一次调用这个方法时，它的结果会被缓存下来，在缓存的有效时间内，以后访问这个方法都直接返回缓存结果，不再执行方法中的代码段。

这个注解可以用condition属性来设置条件，如果不满足条件，就不使用缓存能力，直接执行方法。

可以使用key属性来指定 key 的生成规则。

@CachePut

@CachePut 用于更新缓存。

与@Cacheable不同，@CachePut不仅会缓存方法的结果，还会执行方法的代码段。

它支持的属性和用法都与@Cacheable一致。

@CacheEvict

@CacheEvict 用于清除缓存。

与@Cacheable功能相反，@CacheEvict表明所修饰的方法是用来删除失效或无用的缓存数据。

下面是@Cacheable、@CacheEvict和@CachePut基本使用方法的一个集中展示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

@Service
public class UserService {
    // @Cacheable可以设置多个缓存，形式如：@Cacheable({"books", "isbns"})
    @Cacheable(value={"users"}, key="#user.id")
    public User findUser(User user) {
        return findUserInDB(user.getId());
    }

    @Cacheable(value = "users", condition = "#user.getId() <= 2")
    public User findUserInLimit(User user) {
        return findUserInDB(user.getId());
    }

    @CachePut(value = "users", key = "#user.getId()")
    public void updateUser(User user) {
        updateUserInDB(user);
    }

    @CacheEvict(value = "users")
    public void removeUser(User user) {
        removeUserInDB(user.getId());
    }

    @CacheEvict(value = "users", allEntries = true)
    public void clear() {
        removeAllInDB();
    }
}

@Caching

@Caching 用于组合定义多种缓存功能。

如果需要使用同一个缓存注解（@Cacheable、@CacheEvict或@CachePut）多次修饰一个方法，就需要用到@Caching。

1
2

@Caching(evict = { @CacheEvict("primary"), @CacheEvict(cacheNames="secondary", key="#p0") })
public Book importBooks(String deposit, Date date)

@CacheConfig

@CacheConfig 用于定义公共缓存配置。

与前面的缓存注解不同，这是一个类级别的注解。

如果类的所有操作都是缓存操作，你可以使用@CacheConfig来指定类，省去一些配置。

1
2
3
4
5

@CacheConfig("books")
public class BookRepositoryImpl implements BookRepository {
 @Cacheable
 public Book findBook(ISBN isbn) {...}
}

三、Spring Boot Cache

详见：Spring Boot Cache 特性官方文档

Spring Boot Cache 是在 Spring Cache 的基础上做了封装，使得使用更为便捷。

Spring Boot Cache 快速入门

（1）引入依赖

1
2
3
4
5
6
7
8
9
10

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-cache</artifactId>
</dependency>

<!-- 按序引入需要的缓存库 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

（2）缓存配置

例如，选用缓存为 redis，则需要配置 redis 相关的配置项（如：数据源、连接池等配置信息）

1
2
3
4
5
6
7
8
9
10

# 缓存类型，支持类型：GENERIC、JCACHE、EHCACHE、HAZELCAST、INFINISPAN、COUCHBASE、REDIS、CAFFEINE、SIMPLE
spring.cache.type = redis
# 全局缓存时间
spring.cache.redis.time-to-live = 60s

# Redis 配置
spring.redis.database = 0
spring.redis.host = localhost
spring.redis.port = 6379
spring.redis.password =

（3）使用 @EnableCaching 开启缓存

1
2
3
4
5

@EnableCaching
@SpringBootApplication
public class Application {
    // ...
}

（4）缓存注解（@Cacheable、@CachePut、@CacheEvit 等）使用方式与 Spring Cache 完全一样

四、JetCache

JetCache 是一个基于 Java 的缓存系统封装，提供统一的 API 和注解来简化缓存的使用。 JetCache 提供了比 SpringCache 更加强大的注解，可以原生的支持 TTL、两级缓存、分布式自动刷新，还提供了Cache接口用于手工缓存操作。 当前有四个实现，RedisCache、TairCache（此部分未在 github 开源）、CaffeineCache(in memory)和一个简易的LinkedHashMapCache(in memory)，要添加新的实现也是非常简单的。

详见：jetcache Github

jetcache 快速入门

如果使用 Spring Boot，可以按如下的方式配置（这里使用了 jedis 客户端连接 redis，如果需要集群、读写分离、异步等特性支持请使用lettuce客户端）。

（1）引入 POM

1
2
3
4
5

<dependency>
    <groupId>com.alicp.jetcache</groupId>
    <artifactId>jetcache-starter-redis</artifactId>
    <version>2.5.14</version>
</dependency>

（2）配置

配置一个 spring boot 风格的 application.yml 文件，把他放到资源目录中

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

jetcache:
  statIntervalMinutes: 15
  areaInCacheName: false
  local:
    default:
      type: linkedhashmap
      keyConvertor: fastjson
  remote:
    default:
      type: redis
      keyConvertor: fastjson
      valueEncoder: java
      valueDecoder: java
      poolConfig:
        minIdle: 5
        maxIdle: 20
        maxTotal: 50
      host: 127.0.0.1
      port: 6379

（3）开启缓存

然后创建一个 App 类放在业务包的根下，EnableMethodCache，EnableCreateCacheAnnotation 这两个注解分别激活 Cached 和 CreateCache 注解，其他和标准的 Spring Boot 程序是一样的。这个类可以直接 main 方法运行。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

package com.company.mypackage;

import com.alicp.jetcache.anno.config.EnableCreateCacheAnnotation;
import com.alicp.jetcache.anno.config.EnableMethodCache;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@EnableMethodCache(basePackages = "com.company.mypackage")
@EnableCreateCacheAnnotation
public class MySpringBootApp {
    public static void main(String[] args) {
        SpringApplication.run(MySpringBootApp.class);
    }
}

（4）API 基本使用

创建缓存实例

通过 @CreateCache 注解创建一个缓存实例，默认超时时间是 100 秒

1
2

@CreateCache(expire = 100)
private Cache<Long, UserDO> userCache;

用起来就像 map 一样

1
2
3

UserDO user = userCache.get(123L);
userCache.put(123L, user);
userCache.remove(123L);

创建一个两级（内存+远程）的缓存，内存中的元素个数限制在 50 个。

1
2

@CreateCache(name = "UserService.userCache", expire = 100, cacheType = CacheType.BOTH, localLimit = 50)
private Cache<Long, UserDO> userCache;

name 属性不是必须的，但是起个名字是个好习惯，展示统计数据的使用，会使用这个名字。如果同一个 area 两个 @CreateCache 的 name 配置一样，它们生成的 Cache 将指向同一个实例。

创建方法缓存

使用 @Cached 方法可以为一个方法添加上缓存。JetCache 通过 Spring AOP 生成代理，来支持缓存功能。注解可以加在接口方法上也可以加在类方法上，但需要保证是个 Spring bean。

1
2
3
4

public interface UserService {
    @Cached(name="UserService.getUserById", expire = 3600)
    User getUserById(long userId);
}

五、j2cache

六、总结

使用缓存框架，使得开发缓存功能非常便捷。

如果你的系统只需要使用一种缓存，那么推荐使用 Spring Boot Cache。Spring Boot Cache 在 Spring Cache 基础上做了封装，使用更简单、方便。

如果你的系统需要使用多级缓存，那么推荐使用 jetcache。

参考资料

• JSR107
• Spring Cache 官方文档
• Spring Boot Cache 特性官方文档
• J2Cache Gitee
• jetcache Github
• jetcache wiki

Ehcache 快速入门

EhCache 是一个纯 Java 的进程内缓存框架，具有快速、精干等特点，是 Hibernate 中默认的 CacheProvider。

一、简介

Ehcache 虽然也支持分布式模式，但是分布式方案不是很好好，建议只将其作为单机的进程内缓存使用。

Ehcache 特性

优点

• 快速、简单
• 支持多种缓存策略：LRU、LFU、FIFO 淘汰算法
• 缓存数据有两级：内存和磁盘，因此无需担心容量问题
• 缓存数据会在虚拟机重启的过程中写入磁盘
• 可以通过 RMI、可插入 API 等方式进行分布式缓存
• 具有缓存和缓存管理器的侦听接口
• 支持多缓存管理器实例，以及一个实例的多个缓存区域
• 提供 Hibernate 的缓存实现

缺点

• 使用磁盘 Cache 的时候非常占用磁盘空间
• 不保证数据的安全
• 虽然支持分布式缓存，但效率不高（通过组播方式，在不同节点之间同步数据）。

Ehcache 集群

Ehcache 目前支持五种集群方式：

• RMI
• JMS
• JGroup
• Terracotta
• Ehcache Server

RMI

使用组播方式通知所有节点同步数据。

如果网络有问题，或某台服务宕机，则存在数据无法同步的可能，导致数据不一致。

JMS

JMS 类似 MQ，所有节点订阅消息，当某节点缓存发生变化，就向 JMS 发消息，其他节点感知变化后，同步数据。

Cache Server

二、快速入门

引入 Ehcache

如果你的项目使用 maven 管理，添加以下依赖到你的 pom.xml 中。

1
2
3
4
5
6

<dependency>
  <groupId>net.sf.ehcache</groupId>
  <artifactId>ehcache</artifactId>
  <version>2.10.2</version>
  <type>pom</type>
</dependency>

如果你的项目不使用 maven 管理，请在 Ehcache 官网下载地址 下载 jar 包。

Spring 提供了对于 Ehcache 接口的封装，可以更简便的使用其功能。接入方式如下：

如果你的项目使用 maven 管理，添加以下依赖到你的pom.xml中。

spring-context-support这个 jar 包中含有 Spring 对于缓存功能的抽象封装接口。

1
2
3
4
5

<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-context-support</artifactId>
  <version>4.1.4.RELEASE</version>
</dependency>

添加配置文件

（1）在 classpath 下添加 ehcache.xml
添加一个名为 helloworld 的缓存。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

<?xml version="1.0" encoding="UTF-8"?>
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd">

  <!-- 磁盘缓存位置 -->
  <diskStore path="java.io.tmpdir/ehcache"/>

  <!-- 默认缓存 -->
  <defaultCache
          maxEntriesLocalHeap="10000"
          eternal="false"
          timeToIdleSeconds="120"
          timeToLiveSeconds="120"
          maxEntriesLocalDisk="10000000"
          diskExpiryThreadIntervalSeconds="120"
          memoryStoreEvictionPolicy="LRU"/>

  <!-- helloworld缓存 -->
  <cache name="helloworld"
         maxElementsInMemory="1000"
         eternal="false"
         timeToIdleSeconds="5"
         timeToLiveSeconds="5"
         overflowToDisk="false"
         memoryStoreEvictionPolicy="LRU"/>
</ehcache>

Ehcache 工作示例

Ehcache 会自动加载 classpath 根目录下名为 ehcache.xml 文件。

EhcacheDemo 的工作步骤如下：

1. 在 EhcacheDemo 中，我们引用 ehcache.xml 声明的名为 helloworld 的缓存来创建Cache对象；
2. 然后我们用一个键值对来实例化Element对象；
3. 将Element对象添加到Cache；
4. 然后用Cache的 get 方法获取Element对象。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

public class EhcacheDemo {
    public static void main(String[] args) throws Exception {
        // Create a cache manager
        final CacheManager cacheManager = new CacheManager();

        // create the cache called "helloworld"
        final Cache cache = cacheManager.getCache("helloworld");

        // create a key to map the data to
        final String key = "greeting";

        // Create a data element
        final Element putGreeting = new Element(key, "Hello, World!");

        // Put the element into the data store
        cache.put(putGreeting);

        // Retrieve the data element
        final Element getGreeting = cache.get(key);

        // Print the value
        System.out.println(getGreeting.getObjectValue());
    }
}

输出