1. 项目概述与核心价值在任何一个涉及数据库持久化的业务系统中数据记录的“元信息”管理都是一个绕不开的基础问题。这里的元信息指的就是每条数据“谁在什么时候创建谁在什么时候最后修改过”。听起来简单不就是给表加几个字段然后在插入和更新时赋值吗但真做起来你会发现坑一个接一个每个实体类都要手动写一遍字段每个insert和update方法都要记得去赋值一旦遗漏数据就乱了套后期排查起来更是头疼。更麻烦的是在微服务或分布式架构下如何准确、一致地获取当前操作人信息又是一个新的挑战。MyBatis-Plus简称MP作为MyBatis的增强工具其核心魅力之一就是通过优雅的插件机制帮我们自动化处理这些繁琐的、重复的样板代码。今天要聊的就是如何利用MP的元对象处理器MetaObjectHandler和自动填充功能一劳永逸地统一管理create_time创建时间、update_time更新时间、create_by创建人、update_by更新人这四个字段。这不仅仅是省了几行代码更是将数据审计的规范性和一致性提升到了框架层面让团队所有成员在操作数据库时无需再关心这些细节从而将精力完全聚焦在核心业务逻辑上。2. 整体方案设计与核心思路拆解2.1 为什么选择 MyBatis-Plus 的自动填充在深入代码之前我们先理清为什么这个方案是当前Java后端开发中的“最优解”。处理创建/更新信息的传统方式主要有两种一是在业务代码中手动set二是在数据库层面使用触发器。手动set的弊端显而易见代码侵入性强、容易遗漏、难以维护。数据库触发器则把逻辑藏在数据库里不利于应用层统一管理和调试特别是在分库分表或使用ORM框架时兼容性是个问题。MyBatis-Plus的自动填充机制完美地折中了这两者。它通过在应用层定义一个处理器MetaObjectHandler在MP执行insert或update操作时由框架自动回调这个处理器来为指定字段填充值。这样做的好处是无侵入性实体类只需通过注解标记需要填充的字段业务Service和Mapper的代码完全不用修改。集中管理所有填充逻辑集中在一个类中修改和维护成本极低。灵活可扩展填充的值可以从任何地方获取如Spring Security的上下文、ThreadLocal、请求头等轻松适配各种用户身份认证体系。框架级保障只要是通过MP的insert()或updateById()等方法操作填充逻辑就会生效避免了人为遗漏。2.2 核心组件与工作流程整个方案的核心是三个部分的协同工作实体类Entity使用TableField注解标记哪些字段需要自动填充以及填充的时机插入时、更新时或两者都有。元对象处理器MetaObjectHandler实现MP提供的这个接口在其中定义字段被填充时的具体逻辑即“用什么值去填”。用户上下文User Context一个用于在整个请求生命周期内存储和获取当前登录用户信息的工具。这是填充“创建人/更新人”的关键。其工作流程可以概括为当MP准备执行一条INSERT或UPDATESQL时它会检查实体对象中带有TableField(fill ...)注解的字段。如果发现需要填充MP就会调用我们自定义的MetaObjectHandler实现类的对应方法insertFill或updateFill并将实体对象的元信息MetaObject传递过来。我们在处理器中通过metaObject.setValue(“fieldName”, value)方法将计算好的值如当前时间、当前用户ID设置进去。最后MP才会将包含了填充后值的实体对象转换为SQL执行。3. 核心细节解析与实操要点3.1 实体类字段定义与注解详解实体类的定义是这一切的起点。字段的命名和类型选择至关重要它直接影响到数据库表的设计和后续查询的便利性。import com.baomidou.mybatisplus.annotation.*; import lombok.Data; import java.time.LocalDateTime; Data TableName(“sys_user”) // 对应数据库表名 public class User { TableId(type IdType.AUTO) // 主键自增 private Long id; private String username; private String email; // 核心创建时间只在插入时填充 TableField(fill FieldFill.INSERT) private LocalDateTime createTime; // 核心创建人ID只在插入时填充 TableField(fill FieldFill.INSERT) private Long createBy; // 核心更新时间在插入和更新时都填充 TableField(fill FieldFill.INSERT_UPDATE) private LocalDateTime updateTime; // 核心更新人ID在插入和更新时都填充 TableField(fill FieldFill.INSERT_UPDATE) private Long updateBy; }关键点解析字段类型选择时间字段强烈推荐使用LocalDateTime。它是Java 8引入的日期时间API比老的Date和Calendar更清晰、更强大且完美支持MP和主流数据库MySQL 5.7的DATETIME/TIMESTAMP PostgreSQL的timestamp。避免使用String存储时间否则会失去日期比较、计算等数据库原生优势。操作人字段通常使用与用户主键一致的类型如Long用户ID。也可以使用String存储用户名但用ID关联查询效率更高且不受用户名修改的影响。TableField的fill属性FieldFill.INSERT仅在执行insert操作时填充该字段。适用于createTime和createBy它们一旦创建就不应再被更改。FieldFill.UPDATE仅在执行update操作时填充该字段。单独使用场景较少。FieldFill.INSERT_UPDATE在执行insert和update操作时都会填充。这是updateTime和updateBy的标配确保每次数据变动都留下痕迹。FieldFill.DEFAULT默认值不进行自动填充。数据库表设计建议对应的数据库字段建议设置为NOT NULL并给时间字段设置默认值如CURRENT_TIMESTAMP作为最后一道保障。对于create_by和update_by可以设置外键关联到用户表以保证数据完整性。注意TableField注解是MP提供的用于补充或覆盖MP对字段的默认映射行为。除了fill它还有value映射数据库列名、exist是否为表字段等重要属性需要根据实际情况使用。3.2 实现元对象处理器 (MetaObjectHandler)这是整个自动填充逻辑的大脑。我们需要创建一个类实现com.baomidou.mybatisplus.core.handlers.MetaObjectHandler接口并将其注册为Spring的Bean。import com.baomidou.mybatisplus.core.handlers.MetaObjectHandler; import lombok.extern.slf4j.Slf4j; import org.apache.ibatis.reflection.MetaObject; import org.springframework.stereotype.Component; import java.time.LocalDateTime; Slf4j Component // 关键必须声明为Spring组件MP才能自动发现并调用 public class MyMetaObjectHandler implements MetaObjectHandler { Override public void insertFill(MetaObject metaObject) { log.debug(“开始执行插入数据自动填充...”); // 填充创建时间和更新时间 LocalDateTime now LocalDateTime.now(); // strictInsertFill 是MP 3.3.0推荐的方法它更安全会判断字段是否存在且为null this.strictInsertFill(metaObject, “createTime”, LocalDateTime.class, now); this.strictInsertFill(metaObject, “updateTime”, LocalDateTime.class, now); // 填充创建人和更新人 Long currentUserId getCurrentUserId(); this.strictInsertFill(metaObject, “createBy”, Long.class, currentUserId); this.strictInsertFill(metaObject, “updateBy”, Long.class, currentUserId); } Override public void updateFill(MetaObject metaObject) { log.debug(“开始执行更新数据自动填充...”); // 只填充更新时间和更新人 this.strictUpdateFill(metaObject, “updateTime”, LocalDateTime.class, LocalDateTime.now()); this.strictUpdateFill(metaObject, “updateBy”, Long.class, getCurrentUserId()); } /** * 获取当前登录用户的ID。 * 这是实现中最需要根据项目安全框架定制的部分。 */ private Long getCurrentUserId() { // 示例1使用Spring Security (最常见) // Authentication authentication SecurityContextHolder.getContext().getAuthentication(); // if (authentication ! null authentication.isAuthenticated()) { // UserDetails userDetails (UserDetails) authentication.getPrincipal(); // return Long.valueOf(userDetails.getUsername()); // 假设用户名是ID // // 或者从自定义的UserDetail实现中获取ID字段 // } // return null; // 或一个系统默认用户ID如 -1L // 示例2从自定义的ThreadLocal上下文持有者中获取 // UserContext currentUser UserContextHolder.getCurrentUser(); // if (currentUser ! null) { // return currentUser.getId(); // } // 示例3模拟返回一个固定ID用于演示和测试 return 1001L; } }实操心得与避坑指南strictInsertFillvssetFieldValByName在MP 3.3.0之后推荐使用strictInsertFill和strictUpdateFill。这两个方法会检查字段是否存在且当前值为null只有满足条件才填充避免了意外覆盖已存在值的风险。老版本的setFieldValByName是强制设置不够安全。getCurrentUserId()的实现是关键这是连接业务用户身份和技术自动填充的桥梁。你必须根据项目实际使用的安全框架Spring Security, Shiro, JWT等来编写这里的逻辑。通常的做法是在用户登录成功后将用户信息存入SecurityContextHolder或一个自定义的ThreadLocal变量中然后在这里取出。处理未登录场景在定时任务、消息队列消费者等没有用户上下文的场景调用insert/update时getCurrentUserId()可能返回null。你需要决定策略是允许为null还是填充一个“系统用户”或“默认用户”的ID。为了数据一致性建议设置一个兜底的系统用户ID如0或-1。关于时间精度LocalDateTime.now()默认精度是纳秒但MySQL的DATETIME/TIMESTAMP精度是秒或微秒。在极高并发或对时间戳有严格顺序要求的场景下需要考虑时钟回拨或精度损失问题。对于绝大多数业务LocalDateTime.now()已经足够。如果要求绝对单调递增可以考虑使用分布式ID生成器如雪花算法来生成时间戳或者使用数据库自身的时间函数但这会失去应用层控制的灵活性。3.3 构建用户上下文UserContext为了优雅地在MetaObjectHandler中获取用户信息我们需要一个线程安全的上下文管理工具。这里展示一个基于ThreadLocal的经典实现。/** * 用户上下文持有者用于在当前线程中存储和获取用户信息。 */ public class UserContextHolder { private static final ThreadLocalUserContext USER_CONTEXT new ThreadLocal(); /** * 设置当前线程的用户上下文。 */ public static void setCurrentUser(UserContext userContext) { USER_CONTEXT.set(userContext); } /** * 获取当前线程的用户上下文。 */ public static UserContext getCurrentUser() { return USER_CONTEXT.get(); } /** * 获取当前登录用户的ID。如果未登录返回null或默认值。 */ public static Long getCurrentUserId() { UserContext user getCurrentUser(); return user ! null ? user.getUserId() : null; } /** * 清除当前线程的用户上下文防止内存泄漏。 */ public static void clear() { USER_CONTEXT.remove(); } } /** * 用户上下文信息可根据需要扩展。 */ Data public class UserContext { private Long userId; private String username; private String tenantId; // 在多租户系统中可能用到 // ... 其他用户相关属性 }然后你需要在你的认证过滤器或拦截器中在用户认证成功后将用户信息存入上下文Component public class AuthenticationFilter extends OncePerRequestFilter { Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws ServletException, IOException { // 1. 从请求头如Token、Session或Cookie中解析用户信息 String token request.getHeader(“Authorization”); UserContext userContext authService.validateToken(token); // 假设的验证服务 if (userContext ! null) { // 2. 将用户信息设置到当前线程上下文 UserContextHolder.setCurrentUser(userContext); } try { chain.doFilter(request, response); } finally { // 3. 请求处理完毕后务必清理上下文这是防止内存泄漏的关键 UserContextHolder.clear(); } } }这样在MyMetaObjectHandler的getCurrentUserId()方法中就可以直接调用UserContextHolder.getCurrentUserId()来获取了。4. 实操过程与核心环节实现4.1 完整配置与集成步骤假设我们正在一个标准的Spring Boot项目中集成此功能。步骤一添加依赖确保你的pom.xml中已经引入了MyBatis-Plus的Spring Boot Starter。dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3.1/version !-- 请使用最新稳定版 -- /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency步骤二创建实体类如上文所示创建你的业务实体类如UserOrder并使用TableField(fill ...)注解标记四个元数据字段。步骤三实现并注册 MetaObjectHandler创建MyMetaObjectHandler类并确保其被Component注解标记Spring会自动扫描并管理它。步骤四实现用户上下文与过滤器创建UserContextHolder和UserContext类并实现一个过滤器如AuthenticationFilter来在请求生命周期内管理用户信息。记得将该过滤器注册到Spring Security的过滤器链或直接通过Configuration配置到Servlet容器中。步骤五配置MyBatis-Plus可选但推荐在application.yml中配置MP开启一些有用的特性并确保你的Mapper扫描路径正确。mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl # 开发时开启SQL日志 global-config: db-config: logic-delete-field: deleted # 全局逻辑删除字段名如果用到 logic-delete-value: 1 # 逻辑已删除值 logic-not-delete-value: 0 # 逻辑未删除值 mapper-locations: classpath*:/mapper/**/*.xml type-aliases-package: com.yourcompany.yourproject.entity4.2 业务层使用示例配置完成后在你的Service或Controller中你可以像平常一样使用MP的IService方法完全无需关心四个元数据字段的赋值。Service public class UserServiceImpl extends ServiceImplUserMapper, User implements UserService { Override public boolean createUser(CreateUserRequest request) { User user new User(); user.setUsername(request.getUsername()); user.setEmail(request.getEmail()); // 注意这里完全没有设置 createTime, createBy, updateTime, updateBy return this.save(user); // 调用 save() 方法MP会自动触发 insertFill } Override public boolean updateUserEmail(Long userId, String newEmail) { User user this.getById(userId); if (user null) { throw new RuntimeException(“用户不存在”); } user.setEmail(newEmail); // 注意这里完全没有设置 updateTime 和 updateBy return this.updateById(user); // 调用 updateById()MP会自动触发 updateFill } }执行this.save(user)后查看数据库你会发现create_time,create_by,update_time,update_by四个字段已经被自动填充了当前时间和当前用户ID。执行updateById后update_time和update_by会被更新。4.3 处理特殊场景批量操作与自定义SQL自动填充在MP的通用方法save,updateById,saveOrUpdate等中工作良好但有些场景需要特别注意批量插入 (saveBatch)saveBatch方法默认不会触发自动填充这是一个常见的坑。MP的批量操作基于动态SQL拼接为了性能默认绕过了元对象处理器。解决方案有两种方案A在代码中循环调用save。虽然会生成多条SQL语句但能触发填充。**方案B使用MP的sqlInjector并开启批量操作的填充支持较复杂需自定义注入器。更简单的做法是在saveBatch之前手动为列表中的每个对象调用一次填充逻辑模拟insertFill但这破坏了封装性。个人建议对于必须批量插入且需要填充的场景如果数据量不是特别巨大优先考虑方案A代码清晰可控。或者评估是否可以将填充逻辑下推到数据库通过INSERT ... VALUES (),(),()语句和数据库函数如NOW()但这需要统一应用层和数据库层的用户信息获取方式。使用Wrapper进行更新 (update(Wrapper))当你使用update(user, updateWrapper)时自动填充仍然有效但填充的是你传入的user实体对象中的字段。如果你使用update(null, updateWrapper).set(“email”, “newemail.com”)这种不传入实体对象的方式则自动填充不会生效因为MP没有实体对象可以操作。在这种情况下你需要在Wrapper中手动设置更新时间和更新人.set(“update_time”, LocalDateTime.now()).set(“update_by”, currentUserId)。自定义XML或注解SQL在Mapper的XML文件中手写的insert或update语句MP的自动填充机制是完全无效的。因为MP的插件只拦截由其自身SqlInjector生成的方法。如果你必须使用自定义SQL又需要填充这些字段有两条路在SQL语句中直接写死值例如INSERT INTO ... (create_time, ...) VALUES (NOW(), ...)。但create_by和update_by这种需要当前用户ID的字段你仍然需要从参数中传入。放弃部分自动填充将这四个字段设置为可为空NULL并在业务逻辑中手动赋值。这退回到了最初的手动模式不推荐。5. 常见问题与排查技巧实录即使方案设计得再完美在实际开发和运维中还是会遇到各种问题。下面是我在实践中总结的一些典型问题及其解决方法。5.1 自动填充不生效这是最常见的问题。请按照以下清单逐一排查问题现象可能原因排查步骤与解决方案插入/更新后字段仍为NULL1.MetaObjectHandler未注册为Spring Bean。2. 实体类字段未加TableField(fill…)注解。3. 使用了saveBatch等不触发填充的方法。4. 字段名与strictInsertFill中指定的字符串不匹配大小写、下划线转驼峰。1. 检查MyMetaObjectHandler类是否有Component注解并确保在Spring扫描路径下。2. 检查实体类字段注解确认fill属性值正确INSERT, UPDATE, INSERT_UPDATE。3. 确认调用的方法是MP的通用方法如save,updateById。对于saveBatch需采用替代方案。4. 检查strictInsertFill方法的第一个参数字段名字符串是否与实体类属性名完全一致是createTime而不是create_timeMP会自动进行驼峰下划线转换但这里要写属性名。插入时updateTime未填充实体类中updateTime字段的TableField(fill…)可能只设置了FieldFill.UPDATE。对于updateTime和updateBy在插入时通常也需要填充初始值应设置为FieldFill.INSERT_UPDATE。更新时字段值被意外覆盖使用了老版本的setFieldValByName方法或者传入的实体对象中该字段已有非null值。1. 升级到MP 3.3.0并使用strictUpdateFill它会在填充前检查字段是否为null。2. 确保在更新前从数据库查询出的实体对象中需要自动填充的字段值是null或者你希望它被覆盖。MP的strictUpdateFill只在字段值为null时才填充。一个实用的调试技巧在你的MyMetaObjectHandler的insertFill和updateFill方法开始处打上断点然后执行一个保存或更新操作。观察调试器断点是否被触发如果没有说明处理器未被调用检查Bean注册和MP方法调用。断点触发后观察metaObject对象里的原始值和你准备设置的值。单步执行strictInsertFill看它是否成功执行了setValue。5.2 获取当前用户信息为null在getCurrentUserId()方法中获取不到用户信息导致填充的create_by/update_by为null。场景原因分析解决方案普通HTTP请求1. 认证过滤器未正确设置UserContext。2. 过滤器顺序问题MP的拦截器在认证过滤器之前执行了。3. 用户未登录或Token失效。1. 检查认证过滤器的doFilterInternal方法确保成功认证后调用了UserContextHolder.setCurrentUser()。2. 在Spring Security配置或FilterRegistrationBean中调整过滤器顺序确保认证过滤器在MP的PaginationInterceptor等之前执行。3. 增加日志打印请求和认证过程。异步任务AsyncThreadLocal变量无法在子线程中传递。使用TransmittableThreadLocal阿里开源替代ThreadLocal或者在提交异步任务时手动将用户上下文作为参数传递过去在任务开始时重新设置。定时任务Scheduled没有HTTP请求上下文。为定时任务定义一个“系统用户”或“任务执行者”身份在任务开始前手动向UserContextHolder设置一个固定的系统用户ID。消息队列监听消息生产时未携带用户信息或消费端未正确解析。在消息体Header或Payload中附带用户ID信息。在消费端监听器的入口处从消息中解析出用户ID并设置到UserContextHolder。实操心得对于非请求线程的场景一个健壮的系统应该在getCurrentUserId()方法中做好兜底。我的习惯是private Long getCurrentUserId() { // 1. 优先从请求上下文获取 Long userId UserContextHolder.getCurrentUserId(); if (userId ! null) { return userId; } // 2. 尝试从其他可能的地方获取如JWT工具类直接解析请求头 // ... // 3. 最终兜底返回系统用户ID return SYSTEM_USER_ID; // 例如: 0L 或 -1L并在数据库中预留这个ID的用户 }5.3 时间字段的时区与序列化问题问题前端显示的时间比数据库存储的时间少8小时或其他时区差。原因Java应用JVM、MySQL数据库、以及前端或JSON序列化工具如Jackson可能处于不同的时区配置下。解决方案统一时区最根本的解决方式是确保整个技术栈使用统一的时区推荐UTC8亚洲上海或UTC。JVM在启动参数中添加-Duser.timezoneGMT08:00。MySQL连接字符串中指定serverTimezoneAsia/Shanghai。Jackson (Spring Boot默认)在application.yml中配置spring: jackson: time-zone: GMT8数据库字段类型使用TIMESTAMP类型会受数据库时区影响而DATETIME类型是单纯的日期时间字符串不受时区转换影响。根据业务需求选择。如果业务涉及多时区存储UTC时间并在显示时转换是更好的实践。问题返回给前端的LocalDateTime格式混乱。解决在字段上使用JsonFormat注解统一格式。TableField(fill FieldFill.INSERT) JsonFormat(pattern “yyyy-MM-dd HH:mm:ss”, timezone “GMT8”) private LocalDateTime createTime;5.4 在复杂更新场景下的注意事项场景使用UpdateWrapper进行部分字段更新但希望update_time仍能自动更新。分析如果使用update(null, wrapper).set(“column”, value)自动填充失效。如果使用update(entity, wrapper)则只有entity对象里非空的字段会被更新MP的默认策略如果entity中updateTime为null则不会被更新。解决方案方案一推荐在UpdateWrapper中手动设置update_time和update_by。UpdateWrapperOrder wrapper new UpdateWrapper(); wrapper.eq(“id”, orderId) .set(“status”, newStatus) .set(“update_time”, LocalDateTime.now()) // 手动设置 .set(“update_by”, UserContextHolder.getCurrentUserId()); // 手动设置 this.update(null, wrapper);方案二配置MP的全局更新策略但这样会影响所有更新操作需谨慎。mybatis-plus: global-config: db-config: update-strategy: not_empty # 或 always, 但 not_empty 是更安全的默认值设置为not_empty后update(entity, wrapper)时entity中非空的字段都会加入SET语句。此时你可以先setUpdateTime(null)再调用update但这样很奇怪。所以对于这种复杂更新手动在Wrapper中设置通常更清晰。最后关于网络热词中提到的“mybatis-plus 动态取消租户隔离”这属于MP的多租户插件范畴。如果你的系统同时使用了多租户插件和这个自动填充处理器需要注意填充逻辑中获取的用户ID是否与租户ID关联正确以及处理器是否在租户上下文已设置后才被调用避免数据错乱。这通常需要你根据多租户插件的文档调整过滤器和处理器执行的顺序。
