不知道你有没有遇到过这种情况明明数据库里有一堆记录前端传了个字符串时间范围过来你用 MyBatis-Plus 的 QueryWrapper 去查结果数据偏偏少了当天最后几秒的记录甚至直接查出空列表。我在项目里就栽过跟头——订单筛选页面用户选了 5 月 1 号到 5 月 31 号结果 5 月 31 号那天只有凌晨的数据被查出来其他全没了。排查到最后问题恰恰出在“字符串时间格式”这几个字上。这篇文章就把我在 MyBatis-Plus 里处理字符串时间查询的完整经验拆开讲清楚包括三种条件写法、字段类型怎么选、哪些坑必须躲以及最后怎么把查询接口改舒服。不管是刚接触 MyBatis-Plus 的新手还是被时间边界坑过的老开发这篇内容都能直接帮你少走弯路。1. 字符串时间查询的本质从一次“查不到数据”的线上事故说起先复盘一下我遇到的那次事故只有理解了本质后面所有的写法才有依据。订单表orders的结构很简单create_time字段是数据库的datetime类型存的数据长这样2023-05-31 14:32:10。前端页面是一个日期选择器用户选完日期范围后传给后端的参数是两个字符串startDate 2023-05-01、endDate 2023-05-31。我当时的 MyBatis-Plus 代码写得很“天真”QueryWrapperOrder wrapper new QueryWrapper(); wrapper.between(create_time, startDate, endDate);满心以为这就是查询“5月1日到5月31日”的订单结果线上反馈说 5 月 31 号的订单统计不全。我本地一跑 SQLMyBatis-Plus 实际生成的 SQL 是这样的SELECT * FROM orders WHERE create_time BETWEEN 2023-05-01 AND 2023-05-31如果create_time是字符串类型这条 SQL 也许还能歪打正着但它是datetime类型MySQL 在执行时会做一个隐式类型转换——把字符串2023-05-31转成日期时间类型不写时分秒就默认补00:00:00。也就是说这条 SQL 实际等价于SELECT * FROM orders WHERE create_time 2023-05-01 00:00:00 AND create_time 2023-05-31 00:00:00所以 5 月 31 日当天只有00:00:00这一瞬间的数据会被包含进去其他 23 小时 59 分 59 秒的数据全部被过滤掉了。这就是字符串时间格式查询的核心问题你提供给 SQL 的字符串和数据库字段的实际类型之间需要有一条清晰的转换规则。如果这条规则不明确最终结果就取决于数据库的隐式转换行为而很多隐式转换的结果并不是我们想要的范围。1.1 区分字段类型datetime 和 varchar 的完全不同的表现同样的字符串范围查询如果create_time字段是varchar类型存的值是2023-05-31 14:32:10那么WHERE create_time BETWEEN 2023-05-01 AND 2023-05-31这里的比较变成了纯字符串字典序比较。2023-05-31 14:32:10和2023-05-31逐字符比前 10 个字符都是2023-05-31接着前者后面有空格而字符串比较时空格是小于结束符或者说空字符的所以2023-05-31 14:32:10 2023-05-31反而会把 5 月 31 日全天的数据都包含进来。看着好像是“对了”实际上极其危险。因为如果哪天有笔数据的时间是2023-05-30 23:59:59它和2023-05-31比较时前面已经是2023-05-3而2023-05-31对应位置是2023-05-31比较到第 9 位时一个是0一个是10 1所以2023-05-30 23:59:59又会被排除在范围外这看起来又对了。但如果有人存了2023-05-1这种不规范的格式结果立刻乱套。所以我的第一个结论是在 MyBatis-Plus 里做时间范围查询永远不要直接拿前端传来的原始字符串丢给between先搞清楚字段类型再决定是转时间对象还是补全时间字符串。2. MyBatis-Plus 条件构造器里时间比较的三种写法与底层逻辑MyBatis-Plus 的QueryWrapper和LambdaQueryWrapper提供了丰富的方法但针对时间字段常用的核心就三招ge/le范围、between区间、以及兜底的apply原生 SQL 片段。逐个说。2.1 用 ge 和 le 构建左闭右闭范围字符串入参需要补全时分秒这是最直白的写法。假设前端传的是2023-05-01和2023-05-31如果非要用字符串可以在代码里手动拼上时间String start 2023-05-01 00:00:00; String end 2023-05-31 23:59:59; QueryWrapperOrder wrapper new QueryWrapper(); wrapper.ge(create_time, start) .le(create_time, end);生成的 SQLSELECT * FROM orders WHERE create_time 2023-05-01 00:00:00 AND create_time 2023-05-31 23:59:59这里 MyBatis-Plus 会把字符串值通过预编译参数#{}绑定进 SQL。数据库在执行比较时依然需要把字符串转换为datetime类型但因为字符串本身已经带上了完整的时分秒转换后的边界就是我们想要的范围不会出现“午夜截断”的问题。这段代码的可读性还行但有几个隐患你手动拼接的 00:00:00和 23:59:59是魔法字符串如果哪天前端传的日期格式变成了2023/05/01拼接结果就变成了2023/05/01 00:00:00数据库能否正确隐式转换取决于数据库方言跨数据库时容易出问题。当end本身就是2023-05-31 23:59:59时你再次拼接会变成2023-05-31 23:59:5923:59:59直接报错。所以我的建议是如果参数是字符串就统一按照yyyy-MM-dd接收然后编程式地补全边界如果参数已经是yyyy-MM-dd HH:mm:ss就不要画蛇添足。2.2 between 的边界问题配合日期格式化避免丢掉最后一天between是很多人喜欢用的方法写起来简洁。但正如前面事故所展示的直接between字符串很容易踩坑。更安全的办法是先对日期字符串做规范化处理String start 2023-05-01; String end 2023-05-31; // 转成标准时间字符串 String startDateTime start 00:00:00; String endDateTime end 23:59:59; wrapper.between(create_time, startDateTime, endDateTime);这样生成的 SQL 是SELECT * FROM orders WHERE create_time BETWEEN 2023-05-01 00:00:00 AND 2023-05-31 23:59:59其效果与上面的ge/le完全一样但要注意between是包含两个端点的闭区间。如果哪天的数据恰好整点在23:59:59.500毫秒这个条件会把23:59:59.500排除掉因为2023-05-31 23:59:59.500 2023-05-31 23:59:59。如果你的系统有毫秒精度要求between的右边界就会成为新的隐患。更稳健的做法是用gelt左闭右开代替between见第 4 节。2.3 apply 方法写原生 SQL 片段处理复杂时间逻辑有些查询场景没法直接用列名 参数搞定比如需要对时间字段先做格式化再比较或者需要查询“本月”、“本周”这种动态范围。这时候QueryWrapper.apply就派上用场了。例如要查询某一天的所有数据但希望直接用字符串日期匹配你可能会写成wrapper.apply(DATE_FORMAT(create_time, %Y-%m-%d) {0}, 2023-05-31);这能查出 5 月 31 日的所有记录但要提醒你对字段使用函数会使得该列上的索引失效。如果orders表数据量大这条 SQL 会走全表扫描性能惨不忍睹。所以apply里的 SQL 片段虽然灵活但尽量别让字段被函数包裹。如果确实需要匹配某一天更好的原生写法是wrapper.apply(create_time {0} AND create_time {1}, 2023-05-31 00:00:00, 2023-06-01 00:00:00);这样既有边界又不触发索引失效。{0}、{1}是 MyBatis-Plus 的参数占位最终会以预编译参数的形式绑定避免 SQL 注入。3. 实体字段类型的选择String 字段 vs LocalDateTime 字段决定了你是否需要转型上面的写法都是基于字符串入参、数据库字段保持原样的思路。但在真实项目里更值得花精力的是把实体字段类型选对这会直接影响查询代码的优雅程度。3.1 实体字段用 String 映射 datetime 列能跑但别轻易用有些人图省事建表时create_time是datetime实体类里却写成private String createTime;MyBatis-Plus 查出来时JDBC 驱动会把datetime转成java.sql.Timestamp然后根据配置再转成 String。你写条件查询时可以直接ge(create_time, startStr)看起来方便但实际上查询结果里的时间格式不可控取决于 JDBC 驱动的serverTimezone等参数可能带.0后缀也可能不带前端拿到后还得二次处理。插入时字符串被隐式转换如果格式不对直接报错压根不知道。时间排序、分组、按月统计时字符串语义与时间语义会产生偏差后面各种坑。所以除非是历史遗留项目否则不要在新代码里用 String 映射时间列。3.2 实体字段用 LocalDateTime推荐的方式入参加一层转换Java 8 以后LocalDateTime是时间字段的最佳选择。配合 MyBatis-Plus实体类写TableName(orders) public class Order { TableId private Long id; TableField(create_time) private LocalDateTime createTime; // 其他字段... }查询的时候把前端字符串转成LocalDateTime即可DateTimeFormatter formatter DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss); LocalDateTime start LocalDateTime.parse(2023-05-01 00:00:00, formatter); LocalDateTime end LocalDateTime.parse(2023-05-31 23:59:59, formatter); LambdaQueryWrapperOrder wrapper new LambdaQueryWrapper(); wrapper.ge(Order::getCreateTime, start) .le(Order::getCreateTime, end);使用LambdaQueryWrapper的Order::getCreateTime还避免了字段名写错属于编译期安全。这种写法的好处是类型明确不会出现字符串隐式转换的意外。LocalDateTime有丰富的时间计算 API可以自由增减天数、小时边界处理更优雅。序列化到前端时配合 Jackson 的JsonFormat可以完全掌控输出格式。3.3 TypeHandler 能解决什么让它做最后的兜底而不是主要方案如果你确实不得不让实体字段保持 String比如对接老系统MyBatis-Plus 提供了TypeHandler机制可以对字段读写时的类型转换做自定义处理。实现一个StringToLocalDateTimeTypeHandler在实体字段上标注TableField(typeHandler ...)。这样查询时数据库的datetime依然能映射成 String但格式可以固定成你想要的yyyy-MM-dd HH:mm:ss。不过这属于“戴着镣铐跳舞”只适用于极端兼容场景正常新项目还是优先用LocalDateTime 方法引用。4. 字符串时间查询避坑清单时区、日期边界、索引失效这一节是我认为全文最有价值的部分每一个坑都是真金白银换来的。整理了四条高频踩坑点挨个说透。4.1 时区字符串不带时区LocalDateTime 也不带但数据库连接却有时区很多人忽略时区直到线上数据差 8 小时才如梦方醒。前端传的2023-05-01 00:00:00是一个“墙上时间”它没有时区概念。Java 的LocalDateTime同样没有时区。但 MySQL 的datetime类型也不存储时区信息真正出问题的地方在于JDBC 连接参数serverTimezone。如果你的服务器和数据库不在同一个时区或者连接串配置不对MyBatis-Plus 查询时在驱动层做的时间转换就可能偏移。比如jdbc:mysql://localhost:3306/test?serverTimezoneUTC而数据库写入的时间是按北京时间存的。查询时驱动把LocalDateTime参数转换成Timestamp时可能会按 UTC 解析结果就差了 8 小时。应对策略应用、数据库、连接串统一为正 8 时区Asia/Shanghai。实体字段统一使用LocalDateTime避免Date 时区转换的坑。存储到数据库时明确写入的时间就是业务本地时间。如果是在云环境部署建议把容器时区也设成Asia/Shanghai避免Instant.now()之类的调用产生偏差。4.2 日期边界用左闭右开彻底告别 23:59:59这是我在实际项目里最推荐的写法。不要用ge(left)le(right)也不要用between而是使用ge(左边界)lt(右边界)其中右边界是结束日期的下一天 00:00:00。比如要查 5 月 1 日到 5 月 31 日// 左边界5月1日 00:00:00 LocalDateTime start LocalDate.parse(2023-05-01).atStartOfDay(); // 右边界6月1日 00:00:00 LocalDateTime end LocalDate.parse(2023-05-31).plusDays(1).atStartOfDay(); wrapper.ge(Order::getCreateTime, start) .lt(Order::getCreateTime, end);生成的 SQLWHERE create_time 2023-05-01 00:00:00 AND create_time 2023-06-01 00:00:00这种写法的好处无论数据有没有毫秒5 月 31 日 23:59:59.999 也能被包含进去。不需要拼23:59:59这种终点值也不会因为日期带了下一天而搞混。左闭右开是时间范围查询的最佳实践源码里很多分页、统计也偏好这种。4.3 索引失效永远不要把时间列包在函数里数据库索引最怕的就是在条件列上做函数运算。举个例子有些同学为了省去格式转换写出这种条件wrapper.apply(DATE(create_time) {0}, 2023-05-31);虽然DATE()函数很直观但它会让create_time上的索引完全失效即使这个字段建了索引MySQL 也无法使用只能老老实实全表扫描。数据量小的时候没感觉一旦到百万级别接口响应直接飙到好几秒。永远优先使用范围查询代替函数计算后的等值查询。把DATE(create_time) 2023-05-31改成create_time 2023-05-31 00:00:00 AND create_time 2023-06-01 00:00:00既能查同一逻辑又完美利用索引。4.4 自动填充字段与字符串时间查询的冲突MyBatis-Plus 的MetaObjectHandler能自动填充create_time、update_time方便得很。但要注意如果你在实体类里把这两个字段定义成 String自动填充的LocalDateTime.now()类型与字段类型不匹配会直接报错。所以自动填充功能从侧面也倒逼我们使用LocalDateTime。如果你真的用了 String 字段又不小心配了自动填充只能让MetaObjectHandler里也统一转成DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss).format(LocalDateTime.now())里外里多了很多固定代码没太大必要。5. 进阶当字符串时间查询遇到复杂场景——动态 SQL、多条件组合、分页统计当你熟悉了上面的基础写法真正工程化的时候还会遇到组合场景。这里选取最常见的三个进阶需求来说明。5.1 多时间段组合and/or 嵌套别让条件糊成一团有时候查询条件不是一个连续区间而是“这个月的前半月”加“上个月的后半月”两个独立区间。用 QueryWrapper 的and和or方法可以组织出清晰的 SQLwrapper.and(w - w.ge(create_time, firstStart).le(create_time, firstEnd)) .or(w - w.ge(create_time, secondStart).le(create_time, secondEnd));生成的 SQLWHERE (create_time ? AND create_time ?) OR (create_time ? AND create_time ?)这里有个小细节QueryWrapper的or默认是“或”关系但如果你既有普通条件eq(status, 1)又有or要注意运算优先级最好用and(...)把同类条件包起来避免 SQL 含义和预期不一致。5.2 分页查询时时间条件保持原样即可MyBatis-Plus 分页很简单构造好Page对象再selectPage就行IPageOrder page new Page(pageNum, pageSize); IPageOrder result orderMapper.selectPage(page, wrapper);时间条件放在wrapper里分页插件会自动生成带LIMIT的 SQL不需要额外处理。唯一要注意的是如果同时要做时间范围内的总数统计selectPage里的total会自动执行 count 查询条件是同一个 wrapper不会有偏差。5.3 什么时候回到 XML 自定义 SQL虽然 MyBatis-Plus 的 Wrapper 已经很强但当查询条件特别复杂比如需要 join 多张表、case when 动态计算时间差、或者某个时间条件要参与子查询这时候继续堆apply反而让代码变成一团乱麻。我遇到这种情况会直接在 Mapper XML 里写原生 SQL用if动态拼条件select idselectByTimeRange resultTypecom.example.Order SELECT * FROM orders where if teststartTime ! null AND create_time gt; #{startTime} /if if testendTime ! null AND create_time lt; #{endTime} /if /where /select这里startTime和endTime直接用LocalDateTime类型传入参数格式清晰XML 里也不用做任何字符串拼接。对于喜欢原生 SQL 可读性的团队来说这是比 QueryWrapper 更稳妥的选择。5.4 性能优化给时间列建索引时机要对时间范围查询是很常见的高频查询一定记得在create_time上建索引ALTER TABLE orders ADD INDEX idx_create_time (create_time);如果是复合查询比如WHERE status 1 AND create_time ?可以考虑建立(status, create_time)联合索引让排序和范围判断都走到索引。不过要注意索引不是越多越好写频繁的表要权衡。有时候查询慢不是因为没索引而是 MySQL 优化器觉得“范围太大干脆全表扫描干净利落”。这时可以用FORCE INDEX或者调整 SQL 范围都是后话。真正靠谱的做法是先EXPLAIN看执行计划再用数据说话别拍脑袋。6. 实测复盘一个查询接口从 DTO 到 SQL 的完整改造记录最后用一个完整例子走一遍从“接收字符串时间参数”到“生成正确 SQL”的整个改造链路方便你直接抄作业。需求订单管理后台按时间范围分页查询订单前端传startDate和endDate格式均为yyyy-MM-dd语义是包含当天全天。改造前错误public IPageOrder page(OrderQuery query) { LambdaQueryWrapperOrder wrapper new LambdaQueryWrapper(); wrapper.between(StringUtils.isNotBlank(query.getStartDate()) StringUtils.isNotBlank(query.getEndDate()), Order::getCreateTime, query.getStartDate(), query.getEndDate()); return orderMapper.selectPage(new Page(query.getPageNum(), query.getPageSize()), wrapper); }这条代码生成的 SQL 就是前面事故里的样子边界第二天会丢数据。改造后正确public IPageOrder page(OrderQuery query) { LambdaQueryWrapperOrder wrapper new LambdaQueryWrapper(); if (StringUtils.isNotBlank(query.getStartDate())) { LocalDateTime start LocalDate.parse(query.getStartDate()).atStartOfDay(); wrapper.ge(Order::getCreateTime, start); } if (StringUtils.isNotBlank(query.getEndDate())) { LocalDateTime end LocalDate.parse(query.getEndDate()).plusDays(1).atStartOfDay(); wrapper.lt(Order::getCreateTime, end); } return orderMapper.selectPage(new Page(query.getPageNum(), query.getPageSize()), wrapper); }核心改动点解析字符串日期用LocalDate.parse统一格式如果前端格式不标准可以加DateTimeFormatter兼容。左边界取当天00:00:00。右边界用plusDays(1).atStartOfDay()取第二天的00:00:00配合lt实现左闭右开。判空通过StringUtils.isNotBlank控制实现动态拼接。最终生成的 SQLSELECT * FROM orders WHERE create_time 2023-05-01 00:00:00 AND create_time 2023-06-01 00:00:00 ORDER BY create_time DESC LIMIT ?这条 SQL 在EXPLAIN下能正常走idx_create_time索引返回结果包含 5 月 1 日 00:00:00 到 5 月 31 日 23:59:59.999 的所有记录行为完全符合产品预期。顺带说一个实际验证的细节如果你的数据库表里已经有很多历史数据而之前用的是错误写法可能已经产生了“看起来对但有偏差”的查询结果。改完代码后建议写个临时脚本对比改造前后的查询结果把差异数据暴露出来避免产品和你都以为没问题。我在改造那个订单接口时就是用SELECT COUNT(*)按天分组对比了 3 个月的数据确认每天的数量都对上了才敢发布上线。6.1 字符串格式化错误导致的时间解析异常改造过程中还有一个容易忽略的小坑LocalDate.parse默认只接受yyyy-MM-dd。如果前端在日期字符串后面带了时间比如2023-05-31T10:00:00尤其是搜索框自动补全或者从别的系统接过来的值直接解析会抛DateTimeParseException。代码要宽容一点做一个简单的解析工具方法public static LocalDate parseDate(String dateStr) { try { return LocalDate.parse(dateStr, DateTimeFormatter.ISO_LOCAL_DATE); } catch (DateTimeParseException e) { return LocalDate.parse(dateStr, DateTimeFormatter.ISO_LOCAL_DATE_TIME); } }同理LocalDate.parse(2023-05-31).atStartOfDay()得到的是本地时区的午夜如果和LocalDateTime.now()混用也要确保都走同一个时区。6.2 与前端接口约定的最终实践经过了这次改造我把项目里的查询时间参数约定成了一种通用规范分享给你参考接口入参统一使用String类型格式严格为yyyy-MM-dd只表示日期不包含时间。后端在 Service 层负责把日期字符串转换为LocalDateTime区间并填充到查询条件中。如果需要精确到时分秒入参格式由前端改为yyyy-MM-dd HH:mm:ss后端按完整格式解析。实体类中时间字段一律使用LocalDateTime禁止 String 存时间。所有时间查询条件优先用gelt左闭右开禁止直接用between配字符串。这套规范在团队里落地后跟时间相关的 bug 直线下降代码 review 也轻松很多。MyBatis-Plus 本身并不难难的是把边界条件、类型转换和数据库特性揉在一起时还能保持逻辑清晰。希望这篇能让你少踩几个我用时间换来的坑。