企业官网建设流程全解析

简介：本资源为MyBatis-Plus官方中文文档离线版，面向Java后端开发者、Spring Boot项目工程师及ORM框架学习者，旨在解决MyBatis原生开发中SQL重复编写、基础CRUD冗余、条件构造繁琐等效率痛点。文档完整覆盖自动CRUD、主键策略（雪花算法/Identity）、Lambda表达式查询、QueryWrapper/UpdateWrapper条件构造器、分页插件、公共字段自动填充、乐观锁、数据权限控制及SQL性能分析等核心功能，是快速上手与深度实践MP的权威参考。压缩包共140个文件，以60个HTML页面（含index.html、crud-interface.html、wrapper.html等核心模块）和68个JS脚本为主，辅以PNG/GIF/SVG等可视化资源与CSS样式文件，结构清晰、可本地直接浏览，总大小仅3.77MB，轻量便携。已有3484人下载学习，内容与官网同步更新，适合日常查阅、离线备查及团队知识沉淀。

1. 别再翻源码找配置项了：MyBatis-Plus 官方中文文档不是“说明书”，而是你写 CRUD 时的实时决策手册

很多 Java 开发者第一次接触 MyBatis-Plus，是在同事甩来一句“用 MP 简化 DAO 层”之后。结果打开官网文档，发现首页写着“快速开始”，点进去却是一堆@TableName、LambdaQueryWrapper、IService的零散片段——没有上下文，不讲适用边界，更没说“为什么这里必须用QueryWrapper而不是LambdaQueryWrapper”。这不是文档缺失，而是官方中文文档的定位被严重误读：它不是教你怎么敲下第一行mp.insert()的入门教程，而是当你在真实项目中面对分页性能抖动、字段自动填充失效、多租户 SQL 拦截异常时，能立刻定位到「哪个配置开关控制行为」「哪段注解决定执行路径」「哪个参数影响 SQL 渲染逻辑」的精准索引系统。它服务的对象不是刚学完 JDBC 的新人，而是正在调试updateById返回 0 却查不到日志的中级开发者，是需要在 Spring Boot 3.x + JDK 17 环境下复用旧版MetaObjectHandler的迁移者，是必须把@TableField(fill = FieldFill.INSERT_UPDATE)和@Version同时生效的业务建模者。本文不重讲“什么是 ORM”，只带你把官方中文文档真正用起来：从结构设计逻辑出发，还原每个模块的决策链路，给出可粘贴验证的最小可运行配置，并标注所有你在application.yml或@Configuration中实际会修改的参数及其副作用。

2. 官方中文文档的三层结构解析：为什么“快速开始”之后要直奔“配置项”和“核心功能”

官方中文文档表面是线性阅读流，实则按“能力分层”组织。跳过结构直接查 API，就像拿着菜谱找灶台开关——找不到关键控制点。真正高效的用法，是先理解其三层骨架：基础支撑层（配置与启动）→ 核心能力层（CRUD/条件构造/分页）→ 扩展治理层（插件/自动填充/多租户）。这三层对应文档中三个最常被跳过的章节：“配置项说明”、“核心功能”、“插件扩展”。新手常卡在“为什么selectList(wrapper)查不到数据”，本质是没意识到wrapper的构建方式受configuration.mapUnderscoreToCamelCase和global-config.db-config.id-type双重影响；老手调优时纠结“分页 count 查询太慢”，却忘了mybatis-plus.configuration.default-fetch-size和pagination.interceptor.count-sql是两个独立开关。下面拆解这三层如何联动，并给出每个层级你必须掌握的 3 个关键入口。

2.1 基础支撑层：mybatis-plus配置块不是可选的，而是行为定义的源头

MyBatis-Plus 的行为不像纯 MyBatis 那样由 XML 和SqlSessionFactoryBean主导，而是由MybatisPlusAutoConfiguration自动装配，其核心是MybatisPlusProperties类。这个类将所有配置映射为mybatis-plus.*前缀的属性，而这些属性直接决定 SQL 解析器、主键生成策略、甚至日志输出格式。例如：

# application.yml mybatis-plus: configuration: # 关键：开启驼峰转换，否则 user_name 字段无法映射到 userName map-underscore-to-camel-case: true # 关键：设置默认 fetch size，避免大数据量分页时内存溢出 default-fetch-size: 100 global-config: db-config: # 关键：主键类型决定 insert 时是否自动生成 ID，ID_WORKER 不等于 UUID id-type: assign_id # 关键：表名前缀，配合 @TableName(value = "user") 实现动态前缀 table-prefix: t_

提示：id-type: assign_id表示使用雪花算法生成 Long 型 ID，而非数据库自增。若实体类id字段是String类型，必须改为id-type: assign_uuid，否则启动报错Can not find method getId in class xxx。这是文档“配置项说明”中“全局配置”小节里最易忽略的类型约束。

2.2 核心功能层：QueryWrapper和LambdaQueryWrapper的选择不是语法糖，而是编译期安全与运行时灵活性的权衡

文档“核心功能”章节列出 6 种 Wrapper，但日常开发只需掌握两种：QueryWrapper（字符串字段名）和LambdaQueryWrapper（方法引用）。它们的区别远不止“是否类型安全”：

• QueryWrapper支持动态字段拼接，如wrapper.eq("status_" + tenantId, 1)，适合多租户字段后缀场景；
• LambdaQueryWrapper在编译期校验字段存在性，但无法处理ORDER BY FIELD(id, 3,1,2)这类数据库函数排序。

验证二者差异的最小代码：

// 使用 QueryWrapper：字段名硬编码，IDE 不提示错误，运行时报 Unknown column 'user_name' QueryWrapper<User> qw1 = new QueryWrapper<>(); qw1.eq("user_name", "zhangsan"); // ✅ 正确，但字段名易写错 // 使用 LambdaQueryWrapper：字段名由方法引用保证，IDE 实时提示 LambdaQueryWrapper<User> lwq = new LambdaQueryWrapper<>(); lwq.eq(User::getUserName, "zhangsan"); // ✅ 编译通过即字段存在 // 但以下需求只能用 QueryWrapper QueryWrapper<User> qw2 = new QueryWrapper<>(); qw2.orderBy(true, true, "FIELD(id, " + String.join(",", ids) + ")"); // ✅ 动态 IN 排序

注意：LambdaQueryWrapper的eq方法底层仍会将User::getUserName解析为"user_name"字段名，所以map-underscore-to-camel-case: true必须开启，否则解析结果为"userName"导致 SQL 报错。这是配置层与功能层的强耦合，文档未明说，但调试时必踩。

2.3 扩展治理层：插件不是“加功能”，而是 SQL 生命周期的切面控制点

“插件扩展”章节列出了分页、性能分析、多租户等插件，但新手常误以为“引入依赖+加@Bean就完事”。实际上，每个插件都注册在Interceptor链中，其执行顺序直接影响结果。以分页插件为例，官方文档强调PaginationInnerInterceptor，但没说明它必须在MybatisPlusAutoConfiguration初始化后才生效：

@Configuration public class MybatisPlusConfig { @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); // 关键：分页插件必须第一个注册，否则 count 查询可能被其他插件拦截 interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); // 关键：多租户插件必须在分页之后，否则分页 SQL 的 WHERE 条件会被租户条件覆盖 interceptor.addInnerInterceptor(new TenantLineInnerInterceptor(new TenantLineHandler() { @Override public Expression getTenantId() { return new LongValue(1L); // 实际从 ThreadLocal 获取 } @Override public String getTenantIdColumn() { return "tenant_id"; } })); return interceptor; } }

提示：PaginationInnerInterceptor的DbType.MYSQL参数决定分页方言，若项目同时连接 MySQL 和 PostgreSQL，需配置DynamicTableNameParser或自定义IPage实现。文档中“分页插件”小节只提了单库场景，这是多数据源项目的真实坑点。

3. 从文档“常见问题”反推配置陷阱：5 个高频报错的根因与修复命令

官方文档“常见问题”章节只有 8 个条目，但覆盖了 70% 的线上故障。这些条目不是罗列现象，而是暴露了配置、注解、SQL 解析三者的隐式依赖关系。下面选取 5 个最具代表性的案例，给出可立即执行的诊断命令和修复配置。

3.1 报错org.apache.ibatis.binding.BindingException: Invalid bound statement (not found)：不是 Mapper XML 缺失，而是扫描路径未生效

现象：UserMapper.selectList(null)报错，但UserMapper.xml存在且 namespace 正确。
根因：MyBatis-Plus 的@MapperScan注解未覆盖到 Mapper 接口包，或mapper-locations配置路径错误。

验证命令（Spring Boot Actuator 端点）：

curl http://localhost:8080/actuator/mappings | grep "UserMapper" # 若无返回，说明 Mapper 未被扫描

修复配置（二选一）：

# 方案1：用 @MapperScan 注解（推荐） @SpringBootApplication @MapperScan("com.example.mapper") # 显式指定包路径 public class Application { ... } # 方案2：用 yml 配置（需确保路径正确） mybatis-plus: mapper-locations: classpath*:mapper/**/*Mapper.xml # 注意 *Mapper.xml 后缀 type-aliases-package: com.example.entity

注意：mapper-locations的classpath*:表示扫描所有 jar 包中的 mapper 文件，而classpath:只扫描当前模块。微服务架构下必须用classpath*:，否则依赖的公共 mapper 包无法加载。

3.2updateById返回 0 但数据库有数据：不是 SQL 错误，而是乐观锁版本号未更新

现象：user.setVersion(1); userMapper.updateById(user)返回 0，查数据库发现 version 字段仍是 1。
根因：@Version注解字段未参与 SQL 更新，或optimisticLockerInnerInterceptor未注册。

验证步骤：

// 检查实体类是否正确定义 @Version @Data public class User { @TableId private Long id; private String name; @Version // ✅ 必须有此注解 private Integer version; // ✅ 类型必须是 Integer/Long，不能是 int/long }

修复配置：

@Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor()); return interceptor; }

提示：@Version字段在updateById时会自动添加WHERE version = #{version}条件。若数据库 version 是 2，而传入对象 version 是 1，则 SQL 影响行数为 0，这是预期行为，不是 bug。

3.3 分页查询count结果为 0：不是数据问题，而是IPage泛型未指定

现象：IPage<User> page = userMapper.selectPage(new Page<>(1,10), wrapper)返回page.getRecords()有数据，但page.getTotal()为 0。
根因：IPage未指定泛型，导致PaginationInnerInterceptor无法识别返回类型，跳过 count 查询。

错误写法：

IPage page = userMapper.selectPage(new Page(1,10), wrapper); // ❌ 无泛型

正确写法：

IPage<User> page = userMapper.selectPage(new Page<>(1,10), wrapper); // ✅ 有泛型

注意：Page构造函数参数是(current, size)，不是(offset, limit)。new Page<>(1,10)表示第 1 页，每页 10 条；若写成new Page<>(0,10)，则 current=0，分页插件会认为无需分页，直接返回全部数据。

3.4@TableField(fill = FieldFill.INSERT)字段未填充：不是注解失效，而是MetaObjectHandler未被调用

现象：插入新记录时create_time字段为 null。
根因：MetaObjectHandler实现类未被 Spring 扫描，或strict模式下字段名不匹配。

验证命令：

# 查看 Spring 容器中是否注册了 MetaObjectHandler Bean curl http://localhost:8080/actuator/beans | grep "metaObjectHandler" # 应返回类似 "metaObjectHandler": { "bean":"metaObjectHandler", "scope":"singleton" }

修复代码：

@Component // ✅ 必须加 @Component 让 Spring 管理 public class MyMetaObjectHandler implements MetaObjectHandler { @Override public void insertFill(MetaObject metaObject) { // 关键：字段名必须与数据库列名一致（非驼峰），因为 fill 发生在 SQL 解析前 this.strictInsertFill(metaObject, "create_time", LocalDateTime.class, LocalDateTime.now()); // 起始字段名 } @Override public void updateFill(MetaObject metaObject) { this.strictUpdateFill(metaObject, "update_time", LocalDateTime.class, LocalDateTime.now()); } }

提示：strictInsertFill的第一个参数是数据库列名（如create_time），不是 Java 字段名（如createTime）。若实体类用@TableField("create_time")显式指定，则此处必须用"create_time"。

3.5 多租户插件未生效：不是插件未启用，而是TenantLineHandler的ignoreTable未排除系统表

现象：user表的 SQL 自动添加AND tenant_id = 1，但sys_log表也加了该条件，导致查询失败。
根因：TenantLineHandler默认对所有表生效，需显式声明忽略表。

修复代码：

interceptor.addInnerInterceptor(new TenantLineInnerInterceptor(new TenantLineHandler() { @Override public Expression getTenantId() { return new LongValue(TenantContext.getTenantId()); } @Override public String getTenantIdColumn() { return "tenant_id"; } @Override public boolean ignoreTable(String tableName) { // ✅ 显式忽略 sys_ 开头的系统表 return tableName.startsWith("sys_"); } }));

注意：ignoreTable方法在每次 SQL 解析时调用，若逻辑复杂（如查数据库判断），会导致性能下降。应只做简单字符串匹配。

4. 文档未写的实战技巧：用@InterceptorIgnore绕过插件的 3 种精确控制方式

官方文档“插件扩展”章节只讲了全局启用，但真实项目中常需“局部禁用”——比如分页插件不应作用于导出接口，多租户插件不应过滤定时任务的job_log表。@InterceptorIgnore注解就是为此设计的精准开关，但它有 3 种粒度，文档未说明使用场景。

4.1 方法级忽略：针对特定 Mapper 方法禁用分页

当某个导出接口需查全量数据，但又不想写原生 SQL 时：

@Mapper public interface UserMapper extends BaseMapper<User> { // ✅ 禁用分页插件，但保留乐观锁、多租户 @InterceptorIgnore(page = "true") List<User> selectAllForExport(); // ✅ 同时禁用分页和多租户 @InterceptorIgnore(page = "true", tenantLine = "true") List<User> selectAllForAdmin(); }

4.2 SQL 片段级忽略：在 Wrapper 中动态控制插件行为

当需要对同一方法的不同调用启用不同插件时：

// 查询租户内用户（启用多租户） LambdaQueryWrapper<User> tenantQw = new LambdaQueryWrapper<>(); tenantQw.eq(User::getStatus, 1); List<User> tenantUsers = userMapper.selectList(tenantQw); // 查询所有用户（禁用多租户） LambdaQueryWrapper<User> allQw = new LambdaQueryWrapper<>(); allQw.eq(User::getStatus, 1); // ✅ 在 Wrapper 中设置 ignore 属性 allQw.setEntity(new User().setTenantId(null)); // 触发 tenantLine 插件忽略逻辑 // 或更直接的方式： allQw.last(" /*%mybatis-plus-ignored:tenantLine%*/ "); // 注释方式忽略 List<User> allUsers = userMapper.selectList(allQw);

4.3 全局配置级忽略：用InterceptorIgnoreProperty统一管理忽略规则

当项目有大量需忽略的表，且规则固定时，避免在每个方法加注解：

@Configuration public class MybatisPlusConfig { @Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); // ✅ 全局配置：对 sys_、qrtz_ 开头的表，自动忽略分页和多租户 InterceptorIgnoreProperty ignoreProperty = new InterceptorIgnoreProperty(); ignoreProperty.setPage(Arrays.asList("sys_%", "qrtz_%")); ignoreProperty.setTenantLine(Arrays.asList("sys_%", "qrtz_%")); interceptor.setInterceptorIgnoreProperty(ignoreProperty); return interceptor; } }

提示：InterceptorIgnoreProperty的page和tenantLine是List<String>，支持LIKE通配符（%）和精确匹配。sys_%匹配sys_user、sys_role，但不匹配system_log。

5. 验证文档配置是否生效的 4 个终端命令：不用重启，实时观测 SQL 行为

改完application.yml或@Configuration，别急着重启应用。用以下命令直接观测配置是否被加载、插件是否注册、SQL 是否被改写——这是高效使用官方中文文档的最后一步。

5.1 查看所有 MyBatis-Plus 配置属性是否加载成功

# Spring Boot 2.x curl "http://localhost:8080/actuator/configprops?include=mybatis-plus" # Spring Boot 3.x（需启用 endpoint） curl "http://localhost:8080/actuator/configprops?include=mybatis-plus"

返回 JSON 中应包含：

"mybatis-plus-com.baomidou.mybatisplus.autoconfigure.MybatisPlusProperties": { "prefix": "mybatis-plus", "properties": { "configuration": { "map-underscore-to-camel-case": true }, "global-config": { "db-config": { "id-type": "assign_id" } } } }

5.2 查看已注册的 Interceptor 链顺序

curl "http://localhost:8080/actuator/beans" | grep -A 10 "mybatisPlusInterceptor"

输出应类似：

"mybatisPlusInterceptor": { "aliases": [], "scope": "singleton", "type": "com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor", "resource": "class path resource [com/example/config/MybatisPlusConfig.class]", "dependencies": [] }

5.3 开启 SQL 日志，验证分页插件是否生成 count 查询

# application.yml 临时开启 logging: level: com.baomidou.mybatisplus.extension.plugins.pagination: debug com.example.mapper.UserMapper: debug

调用userMapper.selectPage(new Page<>(1,10), wrapper)后，日志中应出现：

==> Preparing: SELECT COUNT(*) FROM user WHERE status = ? ==> Parameters: 1(Integer) <== Total: 1 ==> Preparing: SELECT id,name,create_time FROM user WHERE status = ? LIMIT ? ==> Parameters: 1(Integer), 10(Long)

5.4 验证@TableField(fill)是否触发填充逻辑

在MyMetaObjectHandler中加日志：

@Override public void insertFill(MetaObject metaObject) { log.info("insertFill triggered for: {}", metaObject.getOriginalObject().getClass().getSimpleName()); this.strictInsertFill(metaObject, "create_time", LocalDateTime.class, LocalDateTime.now()); }

执行userMapper.insert(new User().setName("test"))，日志应输出insertFill triggered for User。若无输出，说明MetaObjectHandler未被调用，需检查@Component和包扫描路径。

注意：@TableField(fill = FieldFill.INSERT)的填充发生在insert方法内部，不会作用于insertBatchSomeColumn等批量方法。这是文档未明确说明的边界，但生产环境必须知晓。

本文还有配套的精品资源，点击获取