摘要唯一性校验是几乎所有业务系统都绕不开的需求——还在Service层写满if (exists) throw不仅代码臃肿更新逻辑还容易写错。本文结合《鹿鲸项目管理工具》实战教你用“一个注解”彻底消灭查重代码让业务逻辑回归纯净。开篇这是每个后端都踩过的坑在业务系统里唯一性校验是我们绕不开的“体力活”。极少的框架会去封装唯一性校验逻辑因为它具有业务性质在企业中对于一些不需参与写业务代码的架构师他们感受不到这里的无奈与痛点。 作为深耕一线的程序员我们的 Service 层往往充斥着大量“复制粘贴”式的代码。看着满屏的if (exists) throw你是不是也想过能不能简单声明一下规则剩下的交给框架自动做今天就结合我们在《鹿鲸项目管理工具》中的实战经验聊聊如何用一个注解一个切面彻底告别繁琐的数据库查重。一、满屏的 if-else传统方案的“痛让我们先回顾一下那段“不堪回首”的代码假设我们要新增一个用户需要校验用户名和手机号的唯一性。传统的写法是这样的Service public class UserServiceImpl { Resource private UserMapper userMapper; public boolean addUser(AddUserDTO dto) { // ❌ 手动查询用户名是否已存在 UserPO existUser userMapper.selectOne( new QueryWrapper().eq(”user_name”, dto.getUserName()) ); if (existUser ! null) { throw new BusinessException(”用户名已存在”); } // ❌ 手动查询手机号是否已存在 UserPO existPhone userMapper.selectOne( new QueryWrapper().eq(”telephone”, dto.getTelephone()) ); if (existPhone ! null) { throw new BusinessException(”手机号已被注册”); } // 终于可以写核心业务了... UserPO userPO new UserPO(); BeanUtils.copyProperties(dto, userPO); return userMapper.insert(userPO) 0; } }这种写法的痛点在哪里1.重复造轮子N 个实体 × M 个字段 烂大街的重复代码。2.逻辑混杂业务代码里夹杂着大量的校验逻辑主次不分。3.更新更麻烦新增时查一次更新时还得加个id ! ?排除自己逻辑翻倍。4.维护噩梦如果哪天产品经理说“这个字段不用唯一了”你得满世界去删if判断。二、灵感能不能像 Transactional 一样简单既然Transactional能自动管理事务那我们能不能写个UniqueVerification让它自动帮我们查重呢答案是肯定的。我们的设计思路非常简单声明式编程。你只需要在方法上声明“我要校验哪些字段”至于怎么连数据库、怎么拼 SQL、怎么抛异常统统由框架在背后帮你搞定。最终效果代码“瘦身”90%看看我们在项目中实际使用的代码以字典项管理为例新增数据时只需要加一行注解无需写任何校验代码Override UniqueVerification( attrs {dictItemValue, dictItemName}, conditions {dictCode}, messages {字典项值已存在, 字典项名称已存在} ) public boolean insertInfo(AddDictItemDTO dto) { // 只需专注写“保存”逻辑校验已自动生效 return service.insertInfo(dto); }更新数据时多加一个exclude true框架自动帮你排除当前记录再也不用手动拼id ! ?了。Override UniqueVerification( attrs {dictItemValue, dictItemName}, conditions{dictCode}, messages {字典项值已存在, 字典项名称已存在}, exclude true // 就是这么简单 ) public boolean updateInfo(ModifyDictItemDTO dto) { return service.updateInfo(dto); }三、核心揭秘它是怎么跑起来的1.方案全貌这套方案的底层其实并不神秘核心就是Spring AOP面向切面编程。该方案由3个核心组件组成协同工作2.2 组件一UniqueVerification —— 注解配置 触发UniqueVerification 标注在Service方法上既定义校验规则又触发校验执行Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) public interface UniqueVerification { /** 需要校验唯一性的字段名数组 */ String[] attrs() default {}; /** 校验时的附加条件字段如限定范围 */ String[] conditions() default {}; /** 与attrs对应的错误提示消息 */ String[] messages() default {}; /** 是否排除自身记录更新场景用 */ boolean exclude() default false; /** 检测到重复时是否继续执行仅警告场景用 */ boolean existContinue() default false; }实际使用项目中 DictItemServiceImpl 的配置Service public class DictItemServiceImpl extends OneEntityServiceImpl... { Override Transactional(rollbackFor Exception.class) UniqueVerification( attrs {dictItemValue, dictItemName}, conditions {dictCode}, messages {字典项值已存在, 字典项名称已存在} ) public boolean insertInfo(AddDictItemDTO addDictItemDTO) { DictItemPO dictItemPO dictItemConverter.toPO(addDictItemDTO); // ... return this.save(dictItemPO); } Override Transactional(rollbackFor Exception.class) UniqueVerification( attrs {dictItemValue, dictItemName}, conditions {dictCode}, messages {字典项值已存在, 字典项名称已存在}, exclude true ) public boolean updateInfo(ModifyDictItemDTO modifyDictItemDTO) { DictItemPO dictItemPO dictItemConverter.toPO(modifyDictItemDTO); // ... return this.updateById(dictItemPO); } }这段配置的含义是在指定dictCode字典编码范围内dictItemValue和dictItemName两个字段各自需要唯一。如果dictItemValue重复则提示字典项值已存在如果dictItemName重复则提示字典项名称已存在。更新时通过exclude true排除自身记录。三个核心使用场景// 场景1新增 —— 默认全量校验 UniqueVerification( attrs {dictItemValue, dictItemName}, conditions {dictCode}, messages {字典项值已存在, 字典项名称已存在} ) public boolean insertInfo(AddDictItemDTO dto) { return service.insertInfo(dto); }// 场景2更新 —— 排除自身记录 UniqueVerification( attrs {dictItemValue, dictItemName}, conditions {dictCode}, messages {字典项值已存在, 字典项名称已存在}, exclude true ) public boolean updateInfo(ModifyDictItemDTO dto) { return service.updateInfo(dto); }// 场景3存在继续不存在则终止抛出异常 UniqueVerification( attrs {email}, messages {邮箱不存在}, existContinue true ) public boolean sendEmail(SendEmailDTO dto) { // 存在继续不存在则终止抛出异常 return service.sendEmail(dto); }2.3 组件二UniqueVerificationAspect —— AOP切面核心引擎UniqueVerificationAspect 是整个方案的引擎通过AOP拦截Service方法自动执行校验Aspect Component Order(2) public class UniqueVerificationAspect { Around(annotation(com.deer.whale.framework.spring.annotation.UniqueVerification)) public Object around(ProceedingJoinPoint joinPoint) throws Throwable { Method method ((MethodSignature) joinPoint.getSignature()).getMethod(); boolean validated method.isAnnotationPresent(UniqueVerification.class); if (validated) { UniqueVerification uniqueValidated method.getAnnotation(UniqueVerification.class); Object[] args joinPoint.getArgs(); if (args.length 0) { // 1. 提取注解配置 boolean exclude uniqueValidated.exclude(); boolean existContinue uniqueValidated.existContinue(); String[] attrs uniqueValidated.attrs(); String[] conditions uniqueValidated.conditions(); String[] messages uniqueValidated.messages(); // 2. 将参数对象转为JSON方便按字段名取值 Object param args[0]; String paramValueJson JSONObject.toJSONString(param); JSONObject paramValueInfo JSONObject.parseObject(paramValueJson); // 3. 获取目标Service Bean用于调用exists方法 Object target joinPoint.getTarget(); Class? s Class.forName(target.getClass().getName()); Object o BeanFactory.getBean(s); MapString, String messageMap new HashMap(); // 4. 逐个字段校验唯一性 for (int i 0; i attrs.length; i) { QueryWrapper queryWrapper new QueryWrapper(); // 4.1 添加附加条件 for (String condition : conditions) { String columnName StringUtil.humpToLine(condition); String columnValue paramValueInfo.getString(condition); queryWrapper.eq(columnName, columnValue); } // 4.2 添加唯一性字段条件驼峰转下划线 Method exists s.getSuperclass().getMethod(”exists”, QueryWrapper.class); String columnName attrs[i].replaceAll(”[A-Z]”, ”_$0”).toUpperCase(); queryWrapper.eq(columnName, paramValueInfo.get(attrs[i])); // 4.3 更新场景排除自身记录 if (exclude) { queryWrapper.ne(”ID”, paramValueInfo.get(”id”)); } // 4.4 查询数据库 boolean exist (boolean) exists.invoke(o, queryWrapper); if (exist) { messageMap.put(attrs[i], messages[i]); } queryWrapper.clear(); } // 5. 根据策略决定是否中断 if ((!existContinue !messageMap.isEmpty()) || (existContinue messageMap.isEmpty())) { throw UniqueVerificationException.of(JSON.toJSONString(messageMap)); } } } return joinPoint.proceed(); } }执行流程图方法被调用│▼读取 UniqueVerification 注解 ──→ 无配置──→ 直接放行│ 有配置▼遍历 attrs[] 数组│├── 字段1: 构建 QueryWrapper含conditions exclude│ └── 调用 exists() 查询数据库│ └── 存在→ 记录错误消息│├── 字段2: 构建 QueryWrapper│ └── 调用 exists() 查询数据库│ └── 存在→ 记录错误消息│└── ... 所有字段校验完毕│▼有错误 existContinuefalse ──→ 抛出 UniqueVerificationException│▼放行执行业务方法2.4 组件三GlobalErrorHandler —— 统一异常处理GlobalErrorHandler 捕获UniqueVerificationException返回统一格式的错误响应RestControllerAdvice public class GlobalErrorHandler { ExceptionHandler(UniqueVerificationException.class) public ResultBody? handleUniqueVerificationException( HttpServletRequest request, UniqueVerificationException exception) { String errorMessage exception.getMessage(); log.warn(⚠️ 数据库唯一性验证失败 - 接口: {}, 错误: {}, request.getRequestURI(), errorMessage); return ResultBody.fail(UNIQUE_VERIFICATION_ERROR, errorMessage); } }校验失败时前端收到的响应{ type: fail, code: UNIQUE_VERIFICATION_ERROR, data: null, message: {\”dictItemValue\”:\”字典项值已存在\”,\”dictItemName\”:\”字典项名称已存在\”} }前端可以解析message中的JSON精准定位到哪个字段重复在表单对应位置显示错误提示。四、那些“只有踩过坑才知道”的设计细节做一个通用的工具不仅要好用更要健壮。在开发过程中我们处理了几个非常关键的细节这也是这套方案“人性化”的地方驼峰与下划线的自动转换Java 里我们习惯用 userName驼峰数据库里习惯用 user_name下划线。切面内部会自动帮你做转换你完全不用操心列名的问题。批量报错而不是“只报一个”传统写法里通常遇到第一个错误就抛出了。我们的方案会遍历所有字段把所有重复的字段都找出来一次性返回给前端。比如你同时填重了“用户名”和“手机号”前端可以一次性在两个输入框旁边标红而不是改完一个提交再报另一个。范围限定Conditions业务往往很复杂。比如“字典项值”要求在同一个字典编码下唯一但不同字典之间可以重复。通过 conditions {dictCode}我们可以轻松实现这种“范围限定”的唯一性校验。五、真实对比传统 vs 注解为了让你更直观地感受到差异我们做了一个简单的对比维度传统手写 if-else鹿鲸注解方案新增校验手动写查询 判空 抛异常一行注解配置即生效更新校验需手动加id ! ?逻辑只需设置excludetrue维护成本散落在各处修改容易遗漏集中在注解上一目了然代码观感业务逻辑被淹没在样板代码中纯净的业务代码赏心悦目六、写在最后关于“完美”的思考虽然这套方案让我们在开发中“偷懒”成功但我也必须诚实地告诉你它的局限性以便你在使用时做出最佳判断1.并发安全应用层的校验无法 100% 防止并发插入传统实现方式也存在一样的局限性。最佳实践是应用层校验 数据库唯一索引双重保险。应用层负责提示友好信息数据库负责兜底。2.字段约定处理方案中默认将dto和po待校验字段名称当作保持一致的mybatis flex才能够进行的自动处理从而减少了较多代码量。3.性能考量目前的实现是“一个字段一次查询”。虽然对于大多数业务系统毫秒级的损耗可以忽略但在超高并发场景下可以考虑引入 Redis 缓存或优化为批量查询。小结这套方案的本质是声明式编程开发者只需声明什么需要唯一校验UniqueVerification具体的校验逻辑由AOP切面自动执行。这与Spring的Transactional、Cacheable等注解的设计思想一脉相承——用注解描述意图用AOP实现细节。编程的本质是抽象。当我们把重复的劳动抽象成一个注解后我们就能腾出更多精力去思考业务本身。最后的一个比喻传统方案就像每道菜都从头切起——洗菜、切菜、炒菜全自己来。注解方案就像预制菜——配置好菜谱并按下启动键UniqueVerification切面就是自动炒菜机帮你完成所有步骤。在你的项目中是怎么处理唯一性校验的是手写SQL还是用了其他框架欢迎在评论区留言讨论希望这个小方案能帮你解放双手少写几个 if-else关注引导本文为鹿鲸项目管理工具——架构实战第5篇如果你想你查看往期文章可以关注【AI低码加速派】进行更多技术文章查阅。希望这篇文章对你有所帮助如果觉得有用欢迎点赞、收藏、分享~「AI低码加速派」专注于项目架构、低代码平台建设的实战分享。在这里你会看到大型项目架构设计的真实案例拆解框架级抽象设计的思路与方法论AOP、注解驱动、泛型模板等进阶技巧的落地实践从 0 到 1 构建企业级项目的完整复盘扫码关注一起成长关注点赞 转发是我持续输出的最大动力~