企业官网建设流程全解析

不知道你有没有遇到过这种情况：明明数据库里有一堆记录，前端传了个字符串时间范围过来，你用 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 代码写得很“天真”：

QueryWrapper<Order> wrapper = new QueryWrapper<>(); wrapper.between("create_time", startDate, endDate);

满心以为这就是查询“5月1日到5月31日”的订单，结果线上反馈说 5 月 31 号的订单统计不全。我本地一跑 SQL，MyBatis-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一个是1，0 < 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"; QueryWrapper<Order> wrapper = new QueryWrapper<>(); wrapper.ge("create_time", start) .le("create_time", end);

生成的 SQL：

SELECT * 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的右边界就会成为新的隐患。

更稳健的做法是用ge+lt（左闭右开）代替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); LambdaQueryWrapper<Order> 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?serverTimezone=UTC

而数据库写入的时间是按北京时间存的。查询时，驱动把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);

生成的 SQL：

WHERE 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方法可以组织出清晰的 SQL：

wrapper.and(w -> w.ge("create_time", firstStart).le("create_time", firstEnd)) .or(w -> w.ge("create_time", secondStart).le("create_time", secondEnd));

生成的 SQL：

WHERE (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就行：

IPage<Order> page = new Page<>(pageNum, pageSize); IPage<Order> 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 id="selectByTimeRange" resultType="com.example.Order"> SELECT * FROM orders <where> <if test="startTime != null"> AND create_time &gt;= #{startTime} </if> <if test="endTime != 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 IPage<Order> page(OrderQuery query) { LambdaQueryWrapper<Order> 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 IPage<Order> page(OrderQuery query) { LambdaQueryWrapper<Order> 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); }

核心改动点：

1. 解析字符串日期，用LocalDate.parse统一格式，如果前端格式不标准，可以加DateTimeFormatter兼容。
2. 左边界取当天00:00:00。
3. 右边界用plusDays(1).atStartOfDay()取第二天的00:00:00，配合lt实现左闭右开。
4. 判空通过StringUtils.isNotBlank控制，实现动态拼接。

最终生成的 SQL：

SELECT * 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 存时间。
• 所有时间查询条件优先用ge+lt左闭右开，禁止直接用between配字符串。

这套规范在团队里落地后，跟时间相关的 bug 直线下降，代码 review 也轻松很多。MyBatis-Plus 本身并不难，难的是把边界条件、类型转换和数据库特性揉在一起时，还能保持逻辑清晰。希望这篇能让你少踩几个我用时间换来的坑。