企业官网建设流程全解析

后端开发做久了，和日期打交道的时间远比想象中多。前阵子接手一个需求：优惠券的有效期等于“创建时间 + 有效天数”，列表页要展示精确到秒的到期时间，还要能筛选出三天内到期的记录。我先想到的是Java里LocalDateTime.plusDays()一把梭，参数传出去就能用。结果越往细想越不对——分页、排序、条件过滤全得下推到数据库，应用层算出的日期在SQL里根本没法直接参与查询。折腾到最后，老老实实走了“ORM调用MySQL库函数”这条路，在SQL里用DATE_ADD()完成“时间 + 天数”的运算。

这篇文章就围绕这个需求展开：什么时候必须让数据库来算日期，ORM怎么调用MySQL的库函数，DATE_ADD()这类函数有哪些使用边界，以及我在实际排查中踩过的几个典型坑。全文不给你复述官方文档，而是把试过的方案、留下的可用代码、以及为什么这么做都交代清楚。适合正在用MyBatis-Plus、JPA做业务开发的兄弟，尤其是做过期提醒、会员续费、试用期到期这类功能的人。别的不多说，直接进正文。

1. 项目拆解与方案选型：为什么必须让数据库参与计算

1.1 从标题里拆出三层问题

“ORM调用MySQL库函数，实现时间+天数”这个标题看着不长，拆开其实是三件事。

第一，ORM。项目里拿到的是实体对象，你不能像JDBC时代那样直接拿Connection执行任意SQL，一切查询都得通过Mapper接口或者查询构造器走。第二，调用MySQL库函数。这在ORM语境里意味着SQL片段里会出现DATE_ADD()、DATE_SUB()这类内置函数，而标准ORM方法并不会给你封装好。第三，时间+天数。这里的“天数”往往不是代码里写死的数字，而是数据库表里的另一个字段，比如valid_days。

实际业务建模很常见：记录表里存start_time和valid_days，两者相加才是业务意义上的“截止时间”。比如优惠券的创建时间是2024-06-01，有效天数是30，那截止时间就是2024-07-01。这个字段组合有两个特点：一是两个值都落在同一行数据里，二是截止时间会随着任一个字段变化而变化。

这里有一个设计取舍：为什么不直接在表里冗余一列expire_time，写入时由应用层算好？如果业务比较简单，这么干完全没问题。但如果你期望修改valid_days后截止时间自动变化，或者你根本不想承担“应用层写漏导致数据不一致”的风险，那在查询时用库函数动态计算就是更稳妥的选择。这两个方向没有绝对对错，我在第3节末尾会给出我的倾向。

1.2 三条技术路线对比

针对这个需求，我梳理过三条实现路线。

第一条是最直觉的方案：应用层计算。

LocalDateTime expire = record.getStartTime().plusDays(record.getValidDays());

算完以后，把expire作为查询参数传进SQL，比如查WHERE expire < :now。问题在于，SQL里的expire是什么？表里没有这个字段，你只能把全表数据拉到内存里，算完再过滤，再分页，再排序。数据量小没事，一旦上到几十万行，这个方案直接作废。

第二条是ORM查询构造器的SQL片段，比如MyBatis-Plus的QueryWrapper.apply()。它能让你在以ORM风格写代码的同时，往WHERE后面塞一段原生SQL函数表达式。好处是代码量小，参数能走预编译，坏处是只适合短小的条件片段，遇到复杂逻辑读起来还是费劲。

第三条是自定义SQL，用@Select注解或者XML Mapper文件。完整度最高，可以写子查询、联合更新、存储过程，也方便DBA接手优化。缺点是项目里的XML文件一多，配置问题就开始冒头，比如后面要讲的“读取实体类xml错误”。

三条路线我用一个表总结，方便你按项目情况对号入座：

1.3 我最终怎么选

我的结论分两层。常规查询，优先用QueryWrapper.apply()，把DATE_ADD()塞进WHERE条件，代码简洁且安全。批量过期更新、复杂统计这类操作，直接上XML自定义SQL，因为apply()只适合条件片段，不适合整段复杂的更新逻辑。

其实这个选择背后有一个原则：ORM能覆盖的用ORM，ORM覆盖不了的用原生SQL，但原生SQL必须走Mapper接口，不能越权去拿JDBC连接。这么做保证了项目结构统一，也方便后续做SQL审查。

2. 核心原理：MySQL日期函数和ORM的拼接机制

2.1 DATE_ADD()的语法与INTERVAL细节

MySQL里做日期加法最常用的就是DATE_ADD()，语法是：

DATE_ADD(date, INTERVAL expr unit)

date是起始时间，expr是一个数值表达式，unit是单位。看两个例子：

SELECT DATE_ADD('2024-06-01 00:00:00', INTERVAL 30 DAY); -- 结果：2024-07-01 00:00:00 SELECT DATE_ADD(start_time, INTERVAL valid_days DAY) AS expire_time FROM coupon;

这里有个容易卡住的点：平时写INTERVAL 7 DAY都是常量，没人觉得奇怪。但INTERVAL后面跟的是expr，这个表达式可以是列名，所以INTERVAL valid_days DAY完全合法。很多新手第一次看到列名出现在INTERVAL后面会懵，怀疑语法错了，其实这是DATE_ADD()最实用的写法。

常见单位有以下这些：

• DAY：天数相加，最常见
• HOUR、MINUTE、SECOND：时间粒度计算
• WEEK：周数相加
• MONTH、YEAR：月份、年份相加，注意月末边界问题
• DAY_HOUR、DAY_MINUTE等复合单位：不常用，可读性差

对应的还有个DATE_SUB()，做减法。

写日期计算时，NOW()和CURDATE()的差异要记牢。NOW()返回“日期+时分秒”，CURDATE()只返回日期，时间部分归零。判断“是否已过期”这种要精确到秒的业务，一般用NOW()；只按自然日判断的，可以看情况用CURDATE()。

2.2 ORM把Java代码编译成了什么SQL

很多用MyBatis-Plus的兄弟，QueryWrapper用了不少，但没想过它底层是怎么把Java方法变成SQL的。

QueryWrapper本质上是一个条件构造器，每个方法（eq、gt、like等）都在往内部的条件列表里追加片段。最终执行时，MyBatis把这些片段拼成完整的SQL，同时把参数填入PreparedStatement。这就是为什么你能写wrapper.eq("name", "张三")，而不需要关心单引号转义——参数走的是预编译通道。

但问题来了：条件构造器里没有dateAdd()方法。你要调用DATE_ADD()这样的库函数，就得用apply()这个方法，它相当于给ORM开了一个原生SQL片段后门：

QueryWrapper<Coupon> wrapper = new QueryWrapper<>(); wrapper.apply("DATE_ADD(start_time, INTERVAL valid_days DAY) > NOW()");

这样SQL在生成后，WHERE子句里就会原样出现DATE_ADD(start_time, INTERVAL valid_days DAY) > NOW()。这里要特别强调，apply()里的SQL片段是字符串拼接进去的，而不是参数绑定进去的。你在apply()里写的每一个字都会出现在最终SQL里。所以它是一把双刃剑——灵活，但使用不当会留SQL注入口子，后面专门讲。

2.3 应用层计算方案到底为什么行不通

前面说应用层plusDays()方案在大数据量下不可用，下面把原因讲透。

数据库执行WHERE过滤时，它只能基于原始行数据做判断。索引是建立在列上的，不是建立在“列经过函数计算后的结果”上的。如果你在Java里算好到期时间，再把这个时间传到SQL里，SQL怎么拿它和每行数据的start_time + valid_days做比较？要么你提前把每个计算结果写进表里，要么数据库就得逐行做DATE_ADD()运算再比较，这种情况下索引、分页、排序全部失效。

更深一层的问题是执行模型。分页需要数据库先确定过滤结果的行数，再按LIMIT/OFFSET或者游标取数据。如果过滤条件的计算逻辑在应用层完成，数据库只能选择“全表扫描，逐行试探”，性能完全不可控。

我见过有人这么写：

List<Coupon> coupons = couponMapper.selectList(null); coupons.stream() .filter(c -> c.getStartTime().plusDays(c.getValidDays()).isBefore(now)) .collect(Collectors.toList());

表里100万行，它就拉100万行到内存，再在Java里算。这属于把数据库该干的事挪到应用层干，数据量一上来就是事故现场。

所以结论很明确：只要这个“时间+天数”的运算参与了WHERE过滤、ORDER BY排序或者分页，就必须下推到SQL层。这也是本篇文章标题的核心意义。

3. 实操落地：在ORM里调用MySQL库函数的几种姿势

3.1 MyBatis-Plus QueryWrapper.apply()：最简单的查询写法

先给最典型的场景：查出“未来三天内到期的优惠券”。这里的“到期时间”不是单独一列，而是start_time + valid_days。代码这么写：

LocalDateTime now = LocalDateTime.now(); QueryWrapper<Coupon> wrapper = new QueryWrapper<>(); wrapper.apply("DATE_ADD(start_time, INTERVAL valid_days DAY) BETWEEN {0} AND {1}", now, now.plusDays(3)); List<Coupon> list = couponMapper.selectList(wrapper);

注意两点。

第一，apply()后面的SQL片段是作为WHERE后的一个完整条件存在的，绝不能带WHERE关键字。你写apply("WHERE DATE_ADD(...) ...")，最终生成的就是WHERE WHERE ...，直接语法报错。

第二，日期参数用了{0}和{1}这样的占位符。这是MyBatis-Plus准备好的预编译通道，框架会把now和now.plusDays(3)按顺序绑定到PreparedStatement上，安全且能避免时区字符串的格式化问题。

为什么推荐BETWEEN {0} AND {1}而不是>= {0} AND <= {1}？两者语义等价，但BETWEEN AND可读性更好，尤其在apply()这种已经自带原生SQL感的写法里，能把条件范围表达清楚。

3.2 批量过期更新：update + apply组合

还有一种高频需求：写个定时任务，把已过期的记录批量置为失效状态。SQL对应的是：

UPDATE coupon SET status = 2 WHERE DATE_ADD(start_time, INTERVAL valid_days DAY) < NOW();

用MyBatis-Plus写：

LambdaUpdateWrapper<Coupon> updateWrapper = new LambdaUpdateWrapper<>(); updateWrapper.apply("DATE_ADD(start_time, INTERVAL valid_days DAY) < NOW()") .set(Coupon::getStatus, 2); couponMapper.update(null, updateWrapper);

LambdaUpdateWrapper配合apply()，能让你在不写XML的情况下完成带函数的更新逻辑。这里用NOW()而不是CURDATE()，原因是状态变更这个操作需要精确到时分秒。如果你用CURDATE()，当天23:59:59过期的订单在晚上8点就可能被误判为“已过期”，因为它把时间部分当作0点来比较了。

定时任务跑这种更新的一个经验：分批执行，别一次性UPDATE几百万行。一次更新1万行，循环跑到结束，避免锁范围过大拖垮线上业务。apply()本身不提供批量能力，但你可以加LIMIT配合子查询或者主键范围分段，这个属于更新策略层面的话题，不展开。

3.3 注解式SQL：小Mapper的轻量选择

如果项目不想维护大量XML文件，@Select注解是一个很好的轻量选择。比如查所有已过期券，并限制返回条数：

@Select("SELECT * FROM coupon " + "WHERE DATE_ADD(start_time, INTERVAL valid_days DAY) < NOW() " + "LIMIT #{limit}") List<Coupon> findExpired(@Param("limit") int limit);

注意，@Select里只有一个参数时可以不写@Param("limit")，但写了能避免歧义，尤其当方法有多个参数时，@Param是必须的。

这里我要专门提一下，很多人在使用@Select时会踩一个“映射错乱”的坑，现象是启动时控制台报“读取实体类的xml错误”或者Invalid bound statement (not found)。排查到最后，往往不是@Select本身的问题，而是项目同时配置了mapper-locations指向某个XML目录，而XML文件不存在或者Mapper接口的namespace写错，导致MyBatis把注意力全放在了XML映射上，注解反而没生效。用注解就保持纯注解，用XML就保持纯XML，同一个Mapper接口里混用两个体系，维护成本会明显上升。

3.4 XML文件写法与维护习惯

稍微复杂一点的查询，我还是建议落到XML Mapper里。比如筛选“在任何两个时间点之间到期的券”：

<select id="selectExpiringBetween" resultType="cn.demo.entity.Coupon"> SELECT * FROM coupon WHERE DATE_ADD(start_time, INTERVAL valid_days DAY) BETWEEN #{start} AND #{end} </select>

XML的好处是SQL完整可见，DBA接手优化方便，还能用<sql>片段、<foreach>做动态条件。

但同时也要记住排查XML映射问题的三件套：

1. namespace必须等于Mapper接口全限定名，多写或少写一个包名，启动都会报绑定异常。
2. XML文件得在classpath里。Maven项目尤其容易漏，src/main/resources目录下的XML通常没问题，但如果XML放在src/main/java下，默认打包不会带过去。需要在pom.xml显式配置resources。
3. resultType别写成实体类的简单名，要用全限定名或配置好的别名。否则生成的SQL能查到，但映射结果集时报“找不到列”之类的错。

每次报错先按这三条排查，能省下大量时间。

3.5 JPA/Hibernate场景的等价方案

如果是JPA/Hibernate项目，思路类似但API不同。JPA里可以用function()函数调用来映射MySQL的库函数：

@Query("SELECT c FROM Coupon c " + "WHERE function('DATE_ADD', c.startTime, concat(c.validDays, ' DAY')) < :now") List<Coupon> findExpired(@Param("now") LocalDateTime now);

function()会把第一个参数当函数名，后面的参数作为函数入参。MySQL方言下，这个JPQL最终生成的SQL就是DATE_ADD(start_time, concat(valid_days, ' DAY'))。这里的concat(c.validDays, ' DAY')是因为函数需要INTERVAL expr DAY的整体结构，但function()没法直接表达INTERVAL关键字，只能用字符串拼接模拟。

嫌绕的话，直接用原生SQL：

@Query(value = "SELECT * FROM coupon " + "WHERE DATE_ADD(start_time, INTERVAL valid_days DAY) < NOW()", nativeQuery = true) List<Coupon> findExpired();

nativeQuery = true意味着整条SQL交给数据库方言执行。代价是换了数据库就得跟着改，MySQL的DATE_ADD()在PostgreSQL里对应的是start_time + valid_days * INTERVAL '1 day'，语法差异不小。项目如果规划要跨数据库，JPA建议先把日期计算挪到应用层或者冗余字段上，再考虑SQL可移植性。

3.6 参数绑定与SQL注入防线

ORM调用库函数时，最大的安全隐患来自apply()的滥用。先看错误示范：

// 错误示范：列名、天数全部字符串拼接 String column = request.getColumn(); Integer days = request.getDays(); wrapper.apply("DATE_ADD(" + column + ", INTERVAL " + days + " DAY) > NOW()");

如果column和days来自前端请求参数，这就是一个标准的SQL注入点。攻击者传一个column = "start_time, INTERVAL 1 DAY) > NOW() OR 1=1 -- "，整个WHERE条件立刻被改写。

正确做法是把用户输入作为参数传给占位符，而SQL结构保持固定：

wrapper.apply("DATE_ADD(start_time, INTERVAL valid_days DAY) > {0}", now);

apply()的占位符{0}、{1}是走预编译的，MySQL端拿到的只是参数值，无法改变SQL结构。但列名、表名这类标识符不能占位，只能白名单校验。比如你允许按start_time或end_time排序，那就明确把可选值列出来，前端传什么都在白名单里查一下，查不到就报错。这是所有动态SQL标识符处理的通用准则。

4. 常见问题与排查技巧实录

4.1 Mapper XML读取报错，先按这三步查

“orm 读取实体类的xml错误”这个热词背后的现象，我在团队里排查过很多次。典型报错长这样：

org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): com.demo.mapper.CouponMapper.findExpired

注意，BindingException不只是“找不到语句”，它背后的真正含义是：MyBatis在启动阶段注册Mapper接口时，没能把XML里的<select>和接口方法关联上。三大原因按出现频率排序：

第一，mapper-locations通配符匹配不到XML。比如配置了classpath*:mapper/*.xml，但文件实际放在mapper/coupon子目录下，就扫不到。

第二，namespace与Mapper接口全限定名不一致。很多人复制XML模板时忘了改namespace，两个Mapper接口共用一个XML命名空间，第二个直接报错。

第三，XML没被打进jar包。Maven项目里XML放在src/main/java下，又没有额外配置resources时，编译后target/classes里压根没有XML文件。

排查顺序建议是：先看编译后的target/classes目录有没有XML；再看Spring启动日志里MyBatis扫描到了哪些Mapper；最后对照namespace和接口路径。按这个顺序，五分钟内能定位绝大多数问题。

4.2 算出来的时间和Java里差8小时

如果你在MySQL里明明看到2024-06-01 08:00:00，Java读出来却变成2024-06-01 16:00:00，或者反过来，那九成是连接时区配置出问题了。

最常见的坑是连串上面配了serverTimezone=CST。CST这个缩写非常阴险，它在不同语境下可以是“美国中部时间”“中国标准时间”或者“古巴标准时间”。MySQL驱动在拿不到明确时区时，会把CST解析成美国中部时间，也就是UTC-6，于是和北京时间的东八区差了14小时，换算后再跨一个夏令时，看起来就像乱了8小时。

解决方式很直接，连接串里显式指定：

jdbc:mysql://localhost:3306/demo?serverTimezone=Asia/Shanghai&useSSL=false

另外，字段类型也要注意。DATETIME在MySQL里是“无时区概念”的，存的是什么读出来就是什么；TIMESTAMP则会在写入和读取时按连接时区做转换。如果你的表用的是TIMESTAMP，就算连接串对了，数据库会话时区不对，也可能出现偏差。检查时先看连接串，再看MySQL全局和会话时区，逐个排除。

4.3 一用DATE_ADD查询就慢，索引怎么救

WHERE DATE_ADD(start_time, INTERVAL 7 DAY) > NOW()这种写法，MySQL无法直接使用start_time上的索引。原因在于B+树索引按原始列值排好序，而查询条件要求的是“列值加7天后的结果”，索引里根本没有这个计算结果，优化器只能全表扫描。

这个原理可以类比查词典：按字母顺序能很快找到以B开头的单词，但让你把每个单词首字母加一，再找结果等于C的那些单词，那就得把整本词典翻一遍。

三种应对思路：

第一种，把函数写到等号或不等号的右边，让左边保持纯列。比如查“七天内到期”：

WHERE start_time > DATE_SUB(NOW(), INTERVAL 7 DAY) AND start_time <= NOW()

这样start_time可以直接走索引范围扫描，性能好很多。前提是你的valid_days是个固定值，不用读表字段。如果天数来自valid_days列，这招就用不上，因为比较对象是每行不同的值。

第二种，MySQL 8.0支持函数索引：

CREATE INDEX idx_expire ON coupon ((DATE_ADD(start_time, INTERVAL valid_days DAY)));

查询条件里的表达式和索引表达式完全一致才能命中，有一点出入就失效。而且函数索引本身也有维护成本，适合高频查询、低写入的表。

第三种，也是最稳的，冗余expire_time列。业务写入时算好截止时间存进去，或者通过触发器同步。查询时它就是普通列，索引照建，SQL好写，DBA也好维护。代价是空间和写入时多一步计算，但读多写少的业务场景，这点代价很划算。

4.4 H2和MySQL方言不兼容导致单测失败

单元测试里一个常见的诡异情况：代码跑在真MySQL环境一切正常，跑mvn test的时候H2内存数据库却报DATE_ADD语法错误。这不是你代码写错了，是H2默认模式下不认识MySQL的函数。

快速修复方式如下。

让H2以MySQL兼容模式启动，连接串加参数：

jdbc:h2:mem:test;MODE=MySQL;DATABASE_TO_LOWER=TRUE

MODE=MySQL能让H2支持一部分MySQL语法，包括DATE_ADD。但兼容模式不是100%覆盖，遇到H2还不支持的函数，建议给测试单独配置一个SQL方言封装，或者干脆用Testcontainers在测试里启动真实MySQL容器。Testcontainers更重，但测出来的结果最可信。团队开发时，我倾向于后者，因为线上问题大部分都是“测试环境没复现出来”导致的，真实数据库不容妥协。

4.5 常见问题速查表

结束前再分享一点体会

最后说点个人感受。这个需求表面看是个“日期加天数”的小事，实际牵扯出来的全是老生常谈：SQL注入、时区、索引、数据库兼容。做完这套东西之后，我养成了一个习惯：凡是涉及ORM调用库函数的代码，都要求在Mapper接口上方留一行注释，把最终要生成的SQL写出来。为什么？因为QueryWrapper.apply()掩盖了SQL细节，后面接手的同事一眼看不出拼接出来的完整条件是什么，真出问题还得从头推一遍。有注释在，至少能省掉一步推导时间。

另一个体会是方案取舍。如果业务允许，我更倾向于冗余expire_time列而不是到处用DATE_ADD()。冗余列的好处是索引好建、查询好写、也不用为了一个日期运算研究各种ORM的“后门API”。计算放到写入时一次完成，读取时全是普通查询——空间换时间，长期看最省心。当然，如果表结构已经定了，或者valid_days会频繁调整，那走DATE_ADD()动态计算仍然是合理选择。把这两条想明白，再回头处理“ORM调用MySQL库函数，实现时间+天数”这类需求，思路就清晰多了。