在实际 Java Web 项目中持久层框架 MyBatis 因其灵活性和对 SQL 的直接掌控能力而被广泛使用。然而当业务逻辑变得复杂需要根据不同条件拼接 SQL 时传统的字符串拼接方式不仅代码冗长、难以维护还极易引入 SQL 注入的安全风险。MyBatis 提供的动态 SQL 功能正是为了解决这一问题而生它允许你在 XML 映射文件中使用一组强大的标签来构建条件化的 SQL 语句。掌握动态 SQL意味着你能用更少的代码实现更复杂的查询逻辑显著提升开发效率和代码可读性。本文将带你从零开始深入理解 MyBatis 动态 SQL 的核心标签及其应用场景并通过一个完整的 Spring Boot 集成案例展示如何在实际项目中运用这些标签来简化代码最终形成一套可复用的查询构建模式。1. 理解 MyBatis 动态 SQL 的核心价值与工作机制1.1 为什么需要动态 SQL在数据库操作中我们经常遇到根据前端传入的不同参数组合进行查询的场景。例如一个用户查询接口可能支持按姓名、年龄、状态等多个字段进行筛选且这些条件都是可选的。如果使用静态 SQL你需要为每一种可能的条件组合都编写一个独立的查询方法这会导致 Mapper 接口和 XML 文件急剧膨胀产生大量重复代码。更糟糕的是使用 Java 代码进行字符串拼接来动态生成 SQL不仅可读性差而且一旦忘记处理参数中的特殊字符如单引号就会为 SQL 注入攻击打开大门。MyBatis 动态 SQL 的本质是在 XML 映射文件中通过一组预定义的标签如if,choose,where,set,foreach等在 SQL 语句被发送到数据库执行之前根据传入参数的值智能地组装出最终的 SQL 字符串。这个过程由 MyBatis 框架在运行时完成开发者无需关心字符串拼接的细节只需声明逻辑规则。1.2 动态 SQL 的执行流程与底层原理当 MyBatis 执行一条映射语句时它会经历一个完整的生命周期从解析 Mapper XML 文件开始到创建 SqlSession最终执行 JDBC 操作。动态 SQL 的处理发生在 SQL 语句的构建阶段。解析阶段MyBatis 启动时会加载所有*Mapper.xml文件并将其中的 SQL 语句解析成一颗包含动态标签的抽象语法树AST。参数绑定当调用 Mapper 方法时传入的参数对象会被封装到一个ParameterHandler中。动态处理SqlSource接口的实现类通常是DynamicSqlSource会根据传入的参数遍历之前解析好的 AST。它会评估每个动态标签中的 OGNL 表达式如test“name ! null”根据表达式的结果true/false来决定是否包含该标签内的 SQL 片段并处理标签本身的逻辑如where标签会自动去除首个AND或OR。SQL 生成经过动态处理后一颗静态的 SQL 树被生成并转换为一个BoundSql对象其中包含了最终要发送到数据库的、带有?占位符的 SQL 字符串以及对应的参数映射关系。执行PreparedStatement使用这个BoundSql对象来设置参数并执行。理解这个流程有助于你在遇到动态 SQL 拼接错误时能够从原理层面进行排查而不是盲目尝试。2. 环境准备与项目基础搭建在开始编写动态 SQL 之前我们需要一个可以运行的基础项目。这里以 Spring Boot 集成 MyBatis 为例。2.1 技术栈与依赖配置确保你的开发环境已安装 JDK 8、Maven 或 Gradle 以及一个 IDE如 IntelliJ IDEA 或 Eclipse。我们将使用以下技术栈Spring Boot: 2.7.x (或 3.x注意依赖包名变化)MyBatis Spring Boot Starter: 用于快速集成MySQL: 作为示例数据库Lombok: 简化实体类编写可选在项目的pom.xml文件中添加关键依赖dependencies !-- Spring Boot Web Starter (如果构建Web应用) -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- MyBatis Spring Boot Starter -- dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.0/version !-- 请使用与Spring Boot版本匹配的版本 -- /dependency !-- MySQL Connector -- dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependency !-- Lombok -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency !-- 测试 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies2.2 数据库与实体类准备假设我们有一个user表用于演示复杂的条件查询和批量操作。CREATE TABLE user ( id bigint(20) NOT NULL AUTO_INCREMENT COMMENT 主键ID, name varchar(30) DEFAULT NULL COMMENT 姓名, age int(11) DEFAULT NULL COMMENT 年龄, email varchar(50) DEFAULT NULL COMMENT 邮箱, status tinyint(4) DEFAULT 1 COMMENT 状态0-禁用1-启用, create_time datetime DEFAULT CURRENT_TIMESTAMP COMMENT 创建时间, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT用户表;对应的 Java 实体类User.javapackage com.example.demo.entity; import lombok.Data; import java.time.LocalDateTime; Data public class User { private Long id; private String name; private Integer age; private String email; private Integer status; // 0:禁用 1:启用 private LocalDateTime createTime; }2.3 MyBatis 基础配置在application.yml或application.properties中配置数据源和 MyBatis# application.yml spring: datasource: url: jdbc:mysql://localhost:3306/your_database?useUnicodetruecharacterEncodingutf-8useSSLfalseserverTimezoneAsia/Shanghai username: your_username password: your_password driver-class-name: com.mysql.cj.jdbc.Driver mybatis: # 指定 mapper.xml 文件的位置如果放在 resources 下对应目录 mapper-locations: classpath:mapper/*.xml # 配置实体类所在的包方便在 XML 中使用短类名 type-aliases-package: com.example.demo.entity configuration: # 开启驼峰命名自动映射数据库 user_name - 实体类 userName map-underscore-to-camel-case: true # 在控制台打印执行的 SQL便于调试 log-impl: org.apache.ibatis.logging.stdout.StdOutImpl3. 核心动态 SQL 标签详解与实战应用接下来我们逐一剖析最常用的动态 SQL 标签并通过具体的 Mapper 接口和 XML 配置来演示其用法。我们将创建一个UserMapper.java接口及其对应的UserMapper.xml。3.1if标签基础条件判断if标签用于简单的条件判断。其test属性中填写 OGNL 表达式表达式结果为true时标签内的 SQL 片段会被包含。场景实现一个多条件分页查询用户的功能所有查询条件均为可选。首先创建一个查询参数封装类UserQuery.javapackage com.example.demo.dto; import lombok.Data; Data public class UserQuery { private String name; private Integer minAge; private Integer maxAge; private Integer status; // 分页参数 private Integer pageNum; private Integer pageSize; }在UserMapper.java接口中定义方法package com.example.demo.mapper; import com.example.demo.entity.User; import com.example.demo.dto.UserQuery; import org.apache.ibatis.annotations.Mapper; import java.util.List; Mapper public interface UserMapper { ListUser selectByCondition(UserQuery query); }在resources/mapper/UserMapper.xml中编写动态 SQL?xml version1.0 encodingUTF-8? !DOCTYPE mapper PUBLIC -//mybatis.org//DTD Mapper 3.0//EN http://mybatis.org/dtd/mybatis-3-mapper.dtd mapper namespacecom.example.demo.mapper.UserMapper select idselectByCondition resultTypeUser parameterTypeUserQuery SELECT id, name, age, email, status, create_time FROM user WHERE 11 if testname ! null and name ! AND name LIKE CONCAT(%, #{name}, %) /if if testminAge ! null AND age #{minAge} /if if testmaxAge ! null AND age #{maxAge} /if if teststatus ! null AND status #{status} /if ORDER BY create_time DESC /select /mapper关键解释test表达式name ! null and name ! 是典型的非空且非空字符串判断。对于字符串两者通常需要同时检查。WHERE 11这是一个小技巧用于避免所有if条件都不满足时SQL 变成SELECT ... FROM user WHERE导致语法错误。但这不是最佳实践后面会用where标签优化。#{name}MyBatis 的参数占位符能有效防止 SQL 注入。3.2where,set,trim标签智能处理关键字直接使用WHERE 11虽然简单但不够优雅且在某些数据库优化器中可能影响性能。where和set标签可以智能地处理WHERE和SET子句。where标签会自动去除其内容开头多余的AND或OR并且如果标签内没有任何内容则不会生成WHERE关键字。优化上面的查询 SQLselect idselectByCondition resultTypeUser parameterTypeUserQuery SELECT id, name, age, email, status, create_time FROM user where if testname ! null and name ! AND name LIKE CONCAT(%, #{name}, %) /if if testminAge ! null AND age #{minAge} /if if testmaxAge ! null AND age #{maxAge} /if if teststatus ! null AND status #{status} /if /where ORDER BY create_time DESC /select现在即使所有if条件都不满足where标签也不会输出WHERESQL 语句完全正确。set标签常用于 UPDATE 语句会自动去除末尾多余的逗号。// Mapper 接口 int updateUserSelective(User user);update idupdateUserSelective parameterTypeUser UPDATE user set if testname ! nullname #{name},/if if testage ! nullage #{age},/if if testemail ! nullemail #{email},/if if teststatus ! nullstatus #{status},/if /set WHERE id #{id} /update如果只有name和age不为空生成的 SQL 会是UPDATE user SET name?, age? WHERE id?set标签自动去掉了age后面的逗号。trim标签是where和set的底层实现功能更强大可以自定义前缀、后缀以及要覆盖的多余字符串。prefix添加前缀。prefixOverrides去掉第一个指定的前缀如AND|OR。suffix添加后缀。suffixOverrides去掉最后一个指定的后缀如,。用trim实现where功能trim prefixWHERE prefixOverridesAND |OR !-- 条件... -- /trim用trim实现set功能trim prefixSET suffixOverrides, !-- 赋值... -- /trim3.3choose,when,otherwise标签多路选择类似于 Java 中的switch-case语句用于实现多选一的逻辑。场景查询用户优先按姓名精确匹配若姓名为空则按邮箱模糊匹配若邮箱也为空则查询所有启用状态的用户。select idselectByPriority resultTypeUser parameterTypemap SELECT * FROM user where choose when testname ! null and name ! name #{name} /when when testemail ! null and email ! email LIKE CONCAT(%, #{email}, %) /when otherwise status 1 /otherwise /choose /where /select3.4foreach标签遍历集合这是动态 SQL 中最强大的标签之一用于处理IN查询和批量操作。场景1IN 查询。根据一组 ID 列表查询用户。// Mapper 接口 ListUser selectByIdList(Param(idList) ListLong idList);select idselectByIdList resultTypeUser SELECT * FROM user WHERE id IN foreach collectionidList itemid indexindex open( separator, close) #{id} /foreach /selectcollection: 指定要遍历的集合参数名。如果参数是单集合且未用Param指定则可用list或array。item: 遍历过程中每个元素的别名。index: 遍历的索引可选。open/close: 遍历开始和结束时添加的字符串。separator: 每次遍历之间添加的分隔符。最终生成的 SQL 类似SELECT * FROM user WHERE id IN (1, 2, 3, 4)场景2批量插入。这是foreach标签的经典应用能极大提升数据初始化效率。// Mapper 接口 int batchInsert(Param(userList) ListUser userList);insert idbatchInsert INSERT INTO user (name, age, email, status) VALUES foreach collectionuserList itemuser separator, (#{user.name}, #{user.age}, #{user.email}, #{user.status}) /foreach /insert生成的 SQL 类似INSERT INTO user (...) VALUES (...), (...), (...)注意虽然批量插入高效但单条 SQL 语句的长度和参数数量受数据库配置限制如max_allowed_packet。如果列表过大需要分批处理。3.5sql与include标签代码复用用于提取公共的 SQL 片段避免重复编码。!-- 定义可复用的列名列表 -- sql idBase_Column_List id, name, age, email, status, create_time /sql !-- 定义可复用的查询条件片段 -- sql idBase_Where_Condition where if testname ! null and name ! AND name LIKE CONCAT(%, #{name}, %)/if if teststatus ! nullAND status #{status}/if /where /sql !-- 在查询语句中引用 -- select idselectByCondition resultTypeUser parameterTypeUserQuery SELECT include refidBase_Column_List/ FROM user include refidBase_Where_Condition/ ORDER BY create_time DESC /select4. 构建一个完整的多条件查询服务现在我们将上述标签组合起来实现一个完整的、可复用的用户查询服务并处理分页。4.1 完善 Mapper 与 Service首先在UserMapper.xml中整合一个功能强大的查询select idselectByConditionWithPage resultTypeUser parameterTypeUserQuery SELECT include refidBase_Column_List/ FROM user where !-- 姓名模糊查询 -- if testname ! null and name ! bind namenamePattern value% name %/ AND name LIKE #{namePattern} /if !-- 年龄范围查询 -- if testminAge ! null AND age #{minAge} /if if testmaxAge ! null AND age #{maxAge} /if !-- 状态精确查询 -- if teststatus ! null AND status #{status} /if !-- 复杂条件邮箱不为空或状态为启用 -- if testemailNotNull true AND email IS NOT NULL /if choose when teststatusList ! null and statusList.size() 0 AND status IN foreach collectionstatusList items open( separator, close) #{s} /foreach /when when testdefaultActive true AND status 1 /when /choose /where ORDER BY create_time DESC /select新知识点bind标签创建一个新的变量并将其绑定到当前上下文。这里用于构建模糊查询的模式字符串使得 SQL 更清晰也便于在多个地方复用该模式。在choose中嵌套使用foreach实现了更复杂的逻辑优先按状态列表查询否则按默认启用状态查询。创建对应的 Mapper 接口方法和 Service// UserMapper.java ListUser selectByConditionWithPage(UserQuery query); // UserService.java Service public class UserService { Autowired private UserMapper userMapper; public ListUser queryUsers(UserQuery query) { // 在实际项目中这里可以添加业务逻辑如参数校验、数据转换等 return userMapper.selectByConditionWithPage(query); } }4.2 编写控制器进行测试创建一个简单的 REST 控制器来测试我们的动态查询RestController RequestMapping(/api/user) public class UserController { Autowired private UserService userService; GetMapping(/list) public ResponseEntityListUser getUserList(UserQuery query) { // 示例查询姓名包含“张”年龄在20到30之间状态为启用的用户 // 请求URL: /api/user/list?name张minAge20maxAge30status1 ListUser users userService.queryUsers(query); return ResponseEntity.ok(users); } }启动 Spring Boot 应用访问上述接口观察控制台打印的 SQL。你会看到根据传入参数的不同MyBatis 动态生成了完全不同的 SQL 语句这正是动态 SQL 的魅力所在。5. 动态 SQL 的常见问题与深度排查即使掌握了语法在实际开发中依然会遇到各种问题。下面是一些典型场景的排查思路。5.1 SQL 拼接错误与语法问题问题现象可能原因检查与解决控制台报错SQL 语法错误例如多出AND、WHERE后无条件等。1. 未使用where标签且所有if条件都不满足导致WHERE关键字后无内容。2. 在where标签内的条件前手动添加了WHERE。3.set标签内条件都不满足导致SET后无内容。1.始终使用where和set标签来包裹动态条件避免手动处理关键字。2. 检查生成的 SQL 日志对比预期与实际语句。IN查询时传入空列表导致 SQL 为IN ()语法错误。在foreach标签外未对集合进行判空。在foreach外层使用if判断集合是否为空或非空。例如if test“idList ! null and idList.size() 0”。模糊查询LIKE参数未正确拼接导致查询不到数据。在test表达式中直接拼接字符串如LIKE ‘%#{name}%’这会导致参数被当作字符串字面量而非预编译参数。使用CONCAT函数LIKE CONCAT(‘%’, #{name}, ‘%’)或使用bind标签提前构建模式字符串。5.2 参数绑定与类型处理问题问题现象可能原因检查与解决报错There is no getter for property ‘XXX’ in class ‘java.lang.Integer’在test表达式中直接使用了基本类型或包装类型的属性如test“status 1”。MyBatis 的 OGNL 表达式在处理基本类型时会尝试将其作为对象获取属性。对于简单类型的参数在test中直接使用参数名进行比较即可或者使用_parameter关键字。更推荐的做法是将查询条件封装成对象传入。传入的布尔类型参数在test表达式中判断失效。MyBatis OGNL 对于布尔值的判断比较严格。在test中使用 true或 false进行显式判断例如test“isAdmin true”。日期类型参数在比较时出错。在 SQL 中直接比较java.util.Date或LocalDateTime对象与数据库日期字段。确保传入的参数类型与数据库字段类型兼容。对于范围查询可以考虑在 Java 层将日期转换为字符串格式与数据库匹配或者在 SQL 中使用数据库函数如DATE()进行处理。5.3 性能与最佳实践考量避免过度使用动态 SQL过于复杂的动态 SQL 会降低 SQL 的可读性和可维护性也可能影响数据库的查询计划缓存。如果条件组合爆炸式增长可以考虑使用更专业的查询构建器如 MyBatis-Plus 的QueryWrapper或将部分逻辑移到业务层。foreach的批量大小批量操作时单次INSERT的 VALUES 列表不宜过长。建议在 Service 层进行分批每批处理 500-1000 条数据。索引失效风险动态 SQL 可能导致某些查询用不上索引。例如WHERE status #{status}当status为null时条件不拼接可能导致全表扫描。需要结合数据库表的具体索引设计来评估。使用sql片段将常用的列列表、条件片段提取出来不仅能减少代码量还能统一修改点。6. 进阶与 MyBatis 其他特性结合6.1 动态 SQL 与 ResultMap 结合ResultMap用于解决数据库字段名与 Java 对象属性名不一致的映射问题。动态 SQL 的查询结果可以映射到复杂的ResultMap。resultMap idUserDetailMap typeUser id propertyid columnid/ result propertyname columnuser_name/ !-- 字段别名映射 -- result propertycreateTime columncreate_time/ !-- 可以包含 association, collection 等复杂映射 -- /resultMap select idselectComplexUser resultMapUserDetailMap parameterTypeUserQuery SELECT id, name as user_name, age, create_time FROM user where !-- 动态条件... -- /where /select6.2 关于 MyBatis 的二级缓存在搜索热词中提到了“二级缓存”。二级缓存是 MyBatis 的会话工厂SqlSessionFactory级别的缓存可以跨 SqlSession 共享。但在使用动态 SQL 时需要特别注意缓存的失效问题。缓存键的生成MyBatis 根据 Mapper 语句的 ID、传递给语句的参数、分页参数等生成一个唯一的缓存键。如果动态 SQL 根据不同的参数生成了不同的 SQL它们会被视为不同的查询缓存键也不同。缓存失效对一张表执行了 INSERT、UPDATE、DELETE 操作后所有与该表相关的二级缓存区域都会被清空。在读写频繁的场景下开启二级缓存可能弊大于利。配置与使用需要在 MyBatis 全局配置中开启二级缓存并在具体的 Mapper XML 文件中使用cache/标签声明。对于动态 SQL 多的查询需要仔细评估数据一致性和性能提升的平衡。!-- 在 MyBatis 配置文件中 -- settings setting namecacheEnabled valuetrue/ /settings !-- 在具体的 Mapper.xml 中 -- mapper namespacecom.example.demo.mapper.UserMapper cache evictionLRU flushInterval60000 size1024 readOnlytrue/ !-- 你的动态 SQL 语句 -- /mapper6.3 在 Spring Boot 中集成 PageHelper 分页另一个热词是“springboot集成mybatis pagehelper”。PageHelper 是一个优秀的分页插件它与动态 SQL 可以完美结合。添加依赖dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version1.4.6/version /dependency在 Service 层使用public PageInfoUser queryUsersByPage(UserQuery query) { // 紧跟在查询方法前调用传入页码和每页数量 PageHelper.startPage(query.getPageNum(), query.getPageSize()); // 接下来执行的第一条 MyBatis 查询方法会被自动分页 ListUser list userMapper.selectByConditionWithPage(query); // 用 PageInfo 包装结果包含总条数、总页数等信息 return new PageInfo(list); }关键点PageHelper.startPage()必须紧贴在执行数据库查询的代码之前。它通过一个本地线程变量ThreadLocal设置分页参数然后由插件在运行时动态修改你的 SQL添加LIMIT子句和计算总数的查询。你的动态 SQL 完全不需要为分页做任何修改。7. 总结与最佳实践清单通过本文你应该已经掌握了 MyBatis 动态 SQL 从基础到进阶的核心用法。最后我们整理一份在项目中使用动态 SQL 的最佳实践清单帮助你规避常见陷阱写出更健壮的代码优先使用where和set永远不要手动拼接WHERE 11或处理SET子句末尾的逗号让标签自动处理。始终进行非空判断在if的test表达式中对字符串判断null和对集合判断null和size()。善用bind处理复杂表达式对于重复的字符串拼接如模糊查询或复杂的 OGNL 表达式使用bind提升可读性。控制foreach的集合大小批量操作时在业务层控制每次传入的集合大小避免单条 SQL 过长。提取公共 SQL 片段使用sql和include维护列名、条件等公共部分保证一致性并便于修改。结合分页插件对于列表查询集成 PageHelper 等分页插件让动态 SQL 专注于业务条件分页逻辑由插件透明处理。关注生成的 SQL开发阶段开启 MyBatis SQL 日志 (log-impl: org.apache.ibatis.logging.stdout.StdOutImpl)仔细核对动态生成的 SQL 是否符合预期。谨慎使用二级缓存在包含大量动态 SQL 或数据更新频繁的场景下评估二级缓存带来的收益和潜在的数据一致性问题。参数封装将多个查询条件封装成 QueryDTO 对象传入避免 Mapper 接口出现过多参数也便于在test表达式中使用。保持 XML 可读性合理的缩进和注释对于复杂的动态 SQL 至关重要。如果一段动态 SQL 超过 50 行考虑是否可以通过拆分或使用查询构建器来简化。动态 SQL 是 MyBatis 的灵魂特性之一它将 SQL 的灵活性与 Java 代码的结构化控制完美结合。从简单的if条件判断到复杂的foreach批量操作理解并熟练运用这些标签能让你在面对复杂多变的业务查询时游刃有余真正实现“少写代码多做事”的目标。在实际项目中建议从简单的条件查询开始实践逐步应用到更复杂的场景并时刻关注生成的 SQL 语句确保其正确性和性能。