由 Mybatis 源码畅谈软件设计（七）：从根上理解 Mybatis 一级缓存

京东云开发者2025-10-29 17:39

本篇我们来讲 一级缓存，重点关注它的实现原理：何时生效、生效范围和何时失效，在未来设计缓存使用时，提供一些借鉴和参考。

1. 准备工作

定义实体

arduino 复制代码 
public class Department {

    public Department(String id) {
        this.id = id;
    }

    private String id;

    /**
     * 部门名称
     */
    private String name;

    /**
     * 部门电话
     */
    private String tel;

    /**
     * 部门成员
     */
    private Set<User> users;
}
vbnet 复制代码 
public class User {

    private String id;

    private String name;

    private Integer age;

    private LocalDateTime birthday;

    private Department department;
}

定义 Mapper.xml

DepartmentMapper.xml，两条 SQL：一条根据 ID 查询；一条清除缓存，标记了 fulshCache 标签，将其设置为 true 后，只要语句被调用，都会将本地缓存和二级缓存清空（默认值为 false）

csharp 复制代码 
<select id="findById" resultType="Department">
    select * from department
    where id = #{id}
</select>

<select id="cleanCathe" resultType="int" flushCache="true">
    select count(department.id) from department;
</select>

UserMapper.xml，联表查询用户信息：

csharp 复制代码 
<select id="findAll" resultMap="userMap">
    select u.*, td.id, td.name as department_name
    from user u
    left join department td
    on u.department_id = td.id
</select>

2. 一级缓存

一级缓存的生效范围 SqlSession 级别的，不同 SqlSession 间不共享缓存，它默认情况下是启用的。主要作用是减少在同一个查询 SQL 会话中对数据库的重复查询，从而提高性能。以如下用例为例：

ini 复制代码 
    public static void main(String[] args) throws IOException {
        InputStream xml = Resources.getResourceAsStream("mybatis-config.xml");
        SqlSessionFactoryBuilder sqlSessionFactoryBuilder = new SqlSessionFactoryBuilder();
        // 开启二级缓存需要在同一个SqlSessionFactory下，二级缓存存在于 SqlSessionFactory 生命周期，如此才能命中二级缓存
        SqlSessionFactory sqlSessionFactory = sqlSessionFactoryBuilder.build(xml);

        SqlSession sqlSession = sqlSessionFactory.openSession();
        DepartmentMapper departmentMapper = sqlSession.getMapper(DepartmentMapper.class);
        System.out.println("----------department第一次查询 ↓------------");
        departmentMapper.findById("18ec781fbefd727923b0d35740b177ab");
        System.out.println("----------department一级缓存生效，控制台看不见SQL ↓------------");
        departmentMapper.findById("18ec781fbefd727923b0d35740b177ab");

    }

可以发现在第二次查询时，一级缓存生效，控制台没有出现SQL：

而我们清空下一级缓存再试试：

ini 复制代码 
    public static void main(String[] args) throws IOException {
        InputStream xml = Resources.getResourceAsStream("mybatis-config.xml");
        SqlSessionFactoryBuilder sqlSessionFactoryBuilder = new SqlSessionFactoryBuilder();
        // 开启二级缓存需要在同一个SqlSessionFactory下，二级缓存存在于 SqlSessionFactory 生命周期，如此才能命中二级缓存
        SqlSessionFactory sqlSessionFactory = sqlSessionFactoryBuilder.build(xml);

        SqlSession sqlSession = sqlSessionFactory.openSession();
        DepartmentMapper departmentMapper = sqlSession.getMapper(DepartmentMapper.class);
        System.out.println("----------department第一次查询 ↓------------");
        departmentMapper.findById("18ec781fbefd727923b0d35740b177ab");
        System.out.println("----------department一级缓存生效，控制台看不见SQL ↓------------");
        departmentMapper.findById("18ec781fbefd727923b0d35740b177ab");
        System.out.println("----------清除一级缓存 ↓------------");
        departmentMapper.cleanCathe();
        System.out.println("----------清除后department再一次查询，SQL再次出现 ↓------------");
        departmentMapper.findById("18ec781fbefd727923b0d35740b177ab");
    }

控制台日志很清晰，清除缓存后又重新查了一遍：

接下来我们看一下不同 SqlSession 间一级缓存是否共享，创建一个新的 SqlSession sqlSession1 执行相同的SQL：

ini 复制代码 
    public static void main(String[] args) throws IOException {
        SqlSession sqlSession = sqlSessionFactory.openSession();
        SqlSession sqlSession1 = sqlSessionFactory.openSession();
        DepartmentMapper departmentMapper = sqlSession.getMapper(DepartmentMapper.class);
        DepartmentMapper departmentMapper1 = sqlSession1.getMapper(DepartmentMapper.class);
        System.out.println("----------department第一次查询 ↓------------");
        departmentMapper.findById("18ec781fbefd727923b0d35740b177ab");
        System.out.println("----------sqlSession1下department执行相同的SQL，控制台出现SQL ↓------------");
        departmentMapper1.findById("18ec781fbefd727923b0d35740b177ab");
    }

如控制台日志所示，可以发现在不同的 SqlSession 下不共享一级缓存：

3. 一级缓存原理

一级缓存在查询方法 org.apache.ibatis.executor.BaseExecutor#query 中生效，如下所示：

scss 复制代码 
public abstract class BaseExecutor implements Executor {
    // ...
    
    // 一级缓存
    protected PerpetualCache localCache;

    public <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler,
                             CacheKey key, BoundSql boundSql) throws SQLException {
        ErrorContext.instance().resource(ms.getResource()).activity("executing a query").object(ms.getId());
        if (closed) {
            throw new ExecutorException("Executor was closed.");
        }
        // 判断是否刷新本地缓存
        if (queryStack == 0 && ms.isFlushCacheRequired()) {
            clearLocalCache();
        }
        List<E> list;
        try {
            queryStack++;
            // 判断一级缓存是否存在，存在则直接作为结果返回，否则查询数据库
            list = resultHandler == null ? (List<E>) localCache.getObject(key) : null;
            if (list != null) {
                // 存储过程相关逻辑
                handleLocallyCachedOutputParameters(ms, key, parameter, boundSql);
            } else {
                // 未命中一级缓存，查询数据库
                list = queryFromDatabase(ms, parameter, rowBounds, resultHandler, key, boundSql);
            }
        } finally {
            queryStack--;
        }
        if (queryStack == 0) {
            for (DeferredLoad deferredLoad : deferredLoads) {
                deferredLoad.load();
            }
            // issue #601
            deferredLoads.clear();
            if (configuration.getLocalCacheScope() == LocalCacheScope.STATEMENT) {
                // issue #482
                clearLocalCache();
            }
        }
        return list;
    }

    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 {
            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;
    }
}

其中 PerpetualCache localCache 便是一级缓存，它的实现借助了 HashMap：

typescript 复制代码 
public class PerpetualCache implements Cache {

    private final String id;

    private final Map<Object, Object> cache = new HashMap<>();
 
    // ...
}

一级缓存生效的逻辑也非常简单，如下所示：

queryFromDatabase 方法中有一段蛮有意思的逻辑 localCache.putObject(key, EXECUTION_PLACEHOLDER);：在添加一级缓存前会先添加缓存 占位符 EXECUTION_PLACEHOLDER ，但是这个占位符并没有被用作一个明确的同步机制来阻止其他线程的查询执行，所以它只是标记一个查询正在进行，提供了 防止在同一事务上下文中重复执行相同的查询的 基础，这种设计可能是 MyBatis 开发者认为在多数情况下，数据库查询的开销相对较小或同一事务中几乎不执行多次相同的查询，而不是为了在多线程环境下保证不击穿数据库，降低数据库的压力。

这种设计模式在分布式缓存系统中很常见，一般用于 解决 "缓存击穿" 问题，帮助系统在高并发环境下保持稳定性。

一级缓存失效场景

  • 两次相同查询SQL间有 Insert、Delete、Update 语句执行时：Insert、Delete、Update 的 flushCache标签 默认为 true ，执行它们时，会将一级缓存清空
  • 调用 sqlSession#clearCache 方法
  • SqlSession 被关闭时，一级缓存也会被清空

缓存的是对象的引用

以如下代码为例，第一次查询结果中 name 字段的值为 null，将其赋值再进行第二次查询：

csharp 复制代码 
        System.out.println("----------department第一次查询 ↓------------");
        Department department = departmentMapper.findById("18ec781fbefd727923b0d35740b177ab");
        System.out.println(department);
        department.setName("   把名字改了");

        System.out.println("----------department一级缓存生效，控制台看不见SQL ↓------------");
        System.out.println(departmentMapper.findById("18ec781fbefd727923b0d35740b177ab"));

可以发现第二次查询取缓存的结果是 更改name结果之后的：

这是因为一级缓存中 存放的数据其实是对象的引用 ，导致第二次从一级缓存中查询到的数据，就是我们刚刚改过的数据，而并不是数据库中真实的数据。在同一个 SqlSession 中，如果对缓存中返回的对象进行了修改，而没有同步更新数据库，那么在后续的查询中会返回被修改的对象，而不是数据库中的最新数据，导致脏读。

4. 总结

  • 一级缓存基于 SqlSession，不同 SqlSession 间不共享一级缓存
  • 一级缓存被保存在 BaseExecutor 的 PerpetualCache 中，本质上是 HashMap
  • 执行 Insert、Delete、Update 语句会使一级缓存失效
  • 一级缓存存放的数据是对象的引用，若对它进行修改，则之后取出的缓存为修改后的数据

巨人的肩膀

相关推荐
淘源码d1 天前
【开源可商用】高并发智慧校园SaaS平台核心源码：Spring Boot 微服务 + 多终端协同
java·程序员·智慧校园·源码·二次开发·软件源码·电子班牌系统
程序员鱼皮2 天前
7个神级技巧，彻底去除网站的 AI 味儿！
计算机·ai·程序员·互联网·网站·编程经验
程序员鱼皮5 天前
Agent Skills 傻瓜式教程，26 年最火 AI 技术就这？
计算机·ai·程序员·agent·编程经验
黑客-雨7 天前
DeepSeek-V3.2深度拆解：开源模型逆袭，GPT-5迎来劲敌！
人工智能·程序员·大模型·知识图谱·agent·大模型教程·deepseek-v3.2
紫雾凌寒7 天前
【 HarmonyOS 高频题】2026 最新 ArkUI 开发与组件面试题
ui·华为·面试·程序员·职场发展·harmonyos·ark-ui
IT技术分享社区9 天前
GTID 结构升级 + JSON 视图强化，MySQL 9.6 创新版带来哪些性能提升？
数据库·程序员
小阿鑫9 天前
32岁程序员猝死背后，我的一些真实感受
前端·后端·程序员·代码人生
十年编程老舅10 天前
虾皮C++一面：C++四种类型转换详解
程序员·编程·c/c++
紫雾凌寒10 天前
【 HarmonyOS 面试题】2026 最新 ArkTS 语言基础面试题
华为·面试·程序员·华为云·职场发展·harmonyos·arkts
程序员鱼皮12 天前
20 个神级 AI 编程扩展，爽爆了！
ai·程序员·编程
热门推荐
01GitHub 镜像站点02Clawdbot 中文汉化版 接入微信、飞书032026美赛A题智能手机电池续航时间预测的连续时间数学模型04OpenCode 入门教程：介绍 · 安装 · 配置第三方 API (如 Claude)052025 年大语言模型发展回顾：关键突破、意外转折与 2026 年展望06【Milvus】向量数据库pymilvus使用教程072026数学建模美赛题目特点与选题建议，常用四大模型汇总08Claude Code Skills 实用使用手册09一种新的LCA算法10UV安装并设置国内源