架构实战第5篇:告别繁琐的数据库查重——字段唯一性校验的“懒人”封装方案

摘要：唯一性校验是几乎所有业务系统都绕不开的需求——还在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); Map<String, 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() 查询数据库│ └── 存在？→ 记录错误消息│└── ... 所有字段校验完毕│▼有错误 && existContinue=false ──→ 抛出 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，精准定位到哪个字段重复，在表单对应位置显示错误提示。

四、那些“只有踩过坑才知道”的设计细节

做一个通用的工具，不仅要好用，更要健壮。在开发过程中，我们处理了几个非常关键的细节，这也是这套方案“人性化”的地方：

1. 驼峰与下划线的自动转换
   Java 里我们习惯用 userName（驼峰），数据库里习惯用 user_name（下划线）。切面内部会自动帮你做转换，你完全不用操心列名的问题。

2. 批量报错，而不是“只报一个”
   传统写法里，通常遇到第一个错误就抛出了。我们的方案会遍历所有字段，把所有重复的字段都找出来，一次性返回给前端。
   比如：你同时填重了“用户名”和“手机号”，前端可以一次性在两个输入框旁边标红，而不是改完一个提交，再报另一个。

3. 范围限定（Conditions）
   业务往往很复杂。比如“字典项值”要求在同一个字典编码下唯一，但不同字典之间可以重复。通过 conditions = {"dictCode"}，我们可以轻松实现这种“范围限定”的唯一性校验。

五、真实对比：传统 vs 注解

为了让你更直观地感受到差异，我们做了一个简单的对比：

六、写在最后：关于“完美”的思考

虽然这套方案让我们在开发中“偷懒”成功，但我也必须诚实地告诉你它的局限性，以便你在使用时做出最佳判断：

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 构建企业级项目的完整复盘

扫码关注，一起成长！

关注+点赞 + 转发，是我持续输出的最大动力~