一个UserService，被我从 v1 一路重写到 v6，每次重构都伴随着线上事故或者 code review 上的激烈争论。前两天还有人问我：Service 层不就查个库、存个数据，能翻出什么花？问出这句话的人，大概率没有经历过缓存穿透把数据库打挂的深夜，也没在并发注册的用户名唯一性校验上栽过跟头。本文不讲宏大的架构理论，只讲我手里这个 UserService 从最初一个巨型 helper 类演变成第六版的过程：它如何一步步把事务、缓存、并发、认证这些事理清楚，以及每一版重写背后真正的导火索。适合正在做用户系统、或者想把自己 Service 层收拾干净的 Java 后端开发者参考。下文代码基于 Spring Boot 3 + Spring Data JPA + Redis 这套比较常见的组合，细节我会尽量展开。
1. 六次重写的复盘：UserService到底在折腾什么
1.1 六个版本各自解决的问题
先把我这六版 UserService 的演进路线理一下，方便你对照自己的项目阶段：
| 版本 | 当时的技术方案 | 核心问题 |
|---|---|---|
| v1 | 一个巨型类包揽全部 CRUD，用 JdbcTemplate 拼 SQL | 所有方法堆在一起，controller 直接调用，改一处崩一片 |
| v2 | 引入 Spring Data JPA，拆分 Repository | Entity 直接暴露给 Controller，接口经常被字段变更打脸 |
| v3 | 在查询上套 Redis 缓存 | 缓存穿透、缓存与数据库不一致，用户改完头像看到的还是旧图 |
| v4 | 开始做 DTO/VO 分离 | 业务逻辑散落在 Service 和 Controller 两处，没人说得清注册到底校验了什么 |
| v5 | 处理并发注册和资料更新 | 锁用得太粗，注册流程整体加锁，吞吐量掉到个位数 |
| v6 | 模块化拆分、事件解耦、异常体系重建 | 这版才把 Service 真正变成业务入口，而不是数据库操作中转站 |
很多人看到这个表格第一反应是：你们团队是不是需求一直变？其实不是。这六版里，真正由新需求驱动的重写只有一次——v5 引入过赛马似的并发注册问题。剩下的全是设计债的清算：v2 的实体泄漏拖到 v4 才收拾，v3 的缓存策略问题在 v5 爆发，而 v5 的锁粒度问题又逼出了 v6。如果你现在手头也有一个改一个字段要动五个文件的 Service 类，基本可以断定重构时机已经到了。
1.2 逼着重写的不是需求，是设计债
我有一次印象特别深：v4 阶段，用户模块要新增一个“修改昵称”的能力。按说就是个 UPDATE 语句的事，结果我改了 Entity、改了 Repository、改了 Controller 里的入参对象，又发现 Swagger 文档里返回结构变了，再去翻调用方，两条业务线在依赖这个字段的旧名字。一个昵称字段折腾了整整一个下午。当时我就意识到，Service 层的价值不是写 SQL，而是把“业务意图”和“技术实现”之间的边界封死。
到 v6 我定下三条铁律，之后所有重构都围绕它们：第一，Service 的入参和出参必须是语义明确的命令对象和视图对象，不让 ORM 实体跨出这一层；第二，业务异常必须有统一的错误码体系，不能靠返回 null 或者抛 RuntimeException 糊弄；第三，Service 方法内部只做当前业务必须做的事，发短信、写审计日志这类副作用全部用事件踢出去。这三条看起来简单，真正做到却花了三个版本。
2. 版本6的核心骨架：接口边界与数据模型
2.1 接口先行：UserService定义了什么能力
v6 我做的第一件事不是写实现，而是把接口定义重新画了一遍。一个用户服务，到底对外提供哪些能力？我把散落在 Controller、Mapper、甚至工具类里的逻辑全部收拢，最终接口长这样：
public interface UserService { UserInfoVO register(RegisterCommand command); LoginResultVO login(LoginCommand command); void logout(Long userId); void changePassword(ChangePasswordCommand command); void updateProfile(UpdateProfileCommand command); UserInfoVO getUserInfo(Long userId); PageResult<UserInfoVO> pageQuery(UserQuery query); }接口里看不到任何 JPA、Redis、RedisTemplate 的影子，就是一个纯业务契约。这样做的好处是：调用方只需要关心“我能做什么”，不必在乎“你内部怎么实现”。v6 之前我最反感的就是在 Controller 里直接调userRepository.findById，因为一旦换存储方案或者改字段，所有调用方全部要跟着改。接口把实现细节挡住之后，Controller 和 Service 之间的耦合就只剩业务语义本身。
顺便说一句，接口定义完后我还会给每个方法写一行注释，说明它承诺了什么、抛什么异常。别小看这一步，它直接决定了后面测试用例怎么写。
2.2 DTO/VO与Entity的彻底分离
v4 虽然开始做 DTO 分离，但做得不彻底，Service 内部仍然在某些方法里直接返回 User 实体。到 v6 我把边界焊死：数据库实体是User，只能活动在 Repository 和 Service 实现内部；对外提供的一律是UserInfoVO；入参一律是带命令语义的对象，比如RegisterCommand、UpdateProfileCommand。
为什么不直接复用实体？道理很简单。User实体上挂着@Table、@Version、还有密码字段，如果 Controller 直接拿它当响应体序列化，轻则把passwordHash漏给前端，重则字段变更直接破坏接口契约。而且实体和视图的关注点完全不一样：实体关心持久化，视图关心展示。我见过一个项目为了复用实体，不得不在@JsonIgnore上叠了好几个注解，最后没人分得清哪些字段是能返回出去的。
命令对象的设计同样有讲究。比如注册命令：
@Getter @Builder public class RegisterCommand { @NotBlank(message = "用户名不能为空") @Size(min = 4, max = 32, message = "用户名长度需在4~32个字符之间") @Pattern(regexp = "^[a-zA-Z0-9_-]+$", message = "用户名仅支持字母、数字、下划线和中划线") private String username; @NotBlank(message = "密码不能为空") @Size(min = 8, max = 64, message = "密码长度需在8~64个字符之间") private String password; @NotBlank(message = "手机号不能为空") @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确") private String mobile; private String nickname; }校验注解放在命令对象上，Service 方法入口处统一触发@Validated校验。这样 Controller 很薄，只做参数收集，真正的业务校验规则跟着命令对象走，换一个入口调用也能复用同一套规则。
转换方面，v6 我改用了 MapStruct 来生成 VO 转换代码。之前手写的UserConverter类有几十个toVO、toEntity方法，全是样板代码，还容易漏字段。MapStruct 在编译期生成实现，漏字段或者字段类型不匹配直接编译报错，比运行时才炸要友好太多。
2.3 异常体系：从返回null到业务异常分层
v3 之前的 Service 方法处理“查不到用户”的方式是返回 null，Controller 再判断一次。结果就是到处都在空指针判断，而且错误提示五花八门。v6 我把异常彻底做成体系：
public abstract class BizException extends RuntimeException { private final ErrorCode errorCode; protected BizException(ErrorCode errorCode, String message) { super(message); this.errorCode = errorCode; } public ErrorCode getErrorCode() { return errorCode; } } public class UserNameAlreadyExistsException extends BizException { public UserNameAlreadyExistsException(String username) { super(ErrorCode.USERNAME_ALREADY_EXISTS, "用户名已被占用: " + username); } }错误码统一枚举，响应体也统一包装：
public enum ErrorCode { USER_NOT_FOUND(10001, "用户不存在"), USERNAME_ALREADY_EXISTS(10002, "用户名已被占用"), PASSWORD_ERROR(10003, "用户名或密码错误"), ACCOUNT_LOCKED(10004, "账号已被禁用"), // 省略其余错误码 }这么做最大的好处是：前端可以拿错误码做精确判断，而不是解析中文提示字符串；后端的全局异常处理器只需要一个@RestControllerAdvice就能把所有业务异常统一翻译成标准响应结构。排查线上问题的时候，日志里打出来的也是结构化的错误码，而不是各种风格混合的报错信息。
3. 事务、缓存与并发：版本6里最难啃的部分
3.1 @Transactional的自调用陷阱与边界划分
Spring 的@Transactional是基于 AOP 代理实现的，所以它有一个众所周知的坑：同一个类里方法调用另一个@Transactional方法，事务不会生效。我 team 里就有人写过这样的代码：
public void registerAndSendCoupon(Long userId) { changeNickname(userId, "新用户"); // 自调用，@Transactional 不生效 sendCoupon(userId); } @Transactional(rollbackFor = Exception.class) public void changeNickname(Long userId, String nickname) { // 更新数据库 }从外部调registerAndSendCoupon，里面的changeNickname实际上没有事务包裹，一旦后面sendCoupon抛异常，数据库里这次改名操作已经提交了，无法回滚，线上就会出现“券没发出去但昵称已经改了”的脏数据。解决方式有三种：把事务方法拆到另一个 Bean 里；或者用@SelfInjection注入自身代理；或者干脆把整个registerAndSendCoupon包上事务。我推荐第三种，因为事务边界本质上是“业务操作的单位”，而不是方法级别的装饰。
v6 的事务边界划分原则是这样的：一个对外提供的 Service 方法，如果它内部包含多个写操作，并且这几个写操作必须要么全成功要么全失败，那就在方法的入口标@Transactional(rollbackFor = Exception.class)。注意rollbackFor一定要写成Exception.class，因为 Spring 默认只对 RuntimeException 回滚，遇到受检异常是不会回滚的。我见过同事写了个@Transactional然后方法里抛IOException，数据库照样提交，查了半天才找到原因。
另外，注册成功之后给用户发欢迎短信这个操作，我一开始放在事务里，结果短信服务超时，整个注册事务跟着回滚，用户明明已经注册成功却被告知失败。后来我在 v6 把这类副作用全部挪到事务外，用事件机制处理，这个坑才算彻底填上。
3.2 乐观锁实现资料更新，分布式锁只留给真正的临界资源
用户资料更新是个很有意思的场景：两个请求同时改同一个用户的昵称和头像，一般都希望“后写覆盖先写”，但要防止丢失中间某个字段的更新。v5 的时候我图省事，给整个更新操作加了 Redis 分布式锁，结果注册和登录高峰期锁等待把接口拖到秒级，线上直接报警。
v6 我把方案换成了 JPA 的乐观锁，给 User 实体加一个@Version字段：
@Entity @Table(name = "t_user") public class User { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @Version private Integer version; private String nickname; private String avatar; // 省略其他字段和 getter/setter }更新时 JPA 自动生成UPDATE ... SET nickname = ?, version = version + 1 WHERE id = ? AND version = ?这样的语句。如果并发请求拿的是同一个旧版本号，后提交的那个会更新 0 行数据，再抛ObjectOptimisticLockingFailureException。捕获之后给用户提示“资料已被其他会话修改，请刷新后重试”就行。
我为什么不再用分布式锁？因为用户资料这种写操作，绝大多数情况下两个请求根本不会在同一秒改同一个人，为一个大概率不发生冲突的场景付出全局串行化的代价，完全不划算。分布式锁只应该留给真正的临界资源，比如 v6 里我唯一保留锁的场景是“给用户发放一次性优惠券”，同一张券不允许被两个人同时领走。
3.3 缓存一致性：读取防击穿，写入防脏读
v3 的缓存事故让我总结出一条血泪经验：缓存不是越简单越好，而是在“一致性”“可用性”和“成本”三者之间找平衡。用户资料属于读多写少、允许短期不一致的数据，所以我选了 cache-aside 模式，配合 30 分钟 TTL 保底。TTL 是最后一道防线，保证即使缓存逻辑写错了，数据也能在半小时内自愈。
获取用户信息的实现，v6 里做了防击穿处理：
private static final String USER_CACHE_PREFIX = "user:info:"; private static final Duration USER_CACHE_TTL = Duration.ofMinutes(30); public UserInfoVO getUserInfo(Long userId) { String cacheKey = USER_CACHE_PREFIX + userId; String json = stringRedisTemplate.opsForValue().get(cacheKey); if (StringUtils.isNotEmpty(json)) { return JsonUtils.parse(json, UserInfoVO.class); } // 互斥重建：防止缓存失效瞬间，大量请求同时打到数据库 RLock lock = redissonClient.getLock(USER_CACHE_PREFIX + "lock:" + userId); boolean locked = lock.tryLock(); if (locked) { try { json = stringRedisTemplate.opsForValue().get(cacheKey); if (StringUtils.isNotEmpty(json)) { return JsonUtils.parse(json, UserInfoVO.class); } User user = userRepository.findById(userId).orElse(null); if (user == null) { return null; } UserInfoVO vo = userConverter.toVO(user); stringRedisTemplate.opsForValue().set(cacheKey, JsonUtils.toJson(vo), USER_CACHE_TTL); return vo; } finally { lock.unlock(); } } // 抢不到锁的请求直接查库，不做等待 User user = userRepository.findById(userId).orElse(null); return user == null ? null : userConverter.toVO(user); }注意几个细节：锁的粒度是单个 userId，不会互相阻塞；拿不到锁的请求选择直接查库而不是自旋等待，因为大多数情况下库能扛住；重建缓存之前必须 double check，否则释放锁之后立刻有第二个线程又重建一遍，白白浪费资源。
更新资料的写入路径，我采用的是“先更新数据库，再删除缓存”。为什么不更新缓存？因为删除比更新简单，而且可以避免“两个并发写请求带着各自的新值互相覆盖缓存”的经典脏读问题。删除缓存失败怎么办？靠 TTL 兜底。更进一步可以用延迟双删，但我实测下来在用户资料这个场景里，30 分钟 TTL 已经足够掩盖掉绝大多数删除失败的窗口期，所以没有过度设计。
4. 注册登录闭环：认证链路的工程化设计
4.1 注册链路：校验、加密与唯一性兜底
注册是 UserService 里最核心的方法，因为它是用户体系所有数据的源头。v6 的注册实现长这样：
@Transactional(rollbackFor = Exception.class) public UserInfoVO register(RegisterCommand command) { if (userRepository.existsByUsername(command.getUsername())) { throw new UserNameAlreadyExistsException(command.getUsername()); } String encodedPassword = passwordEncoder.encode(command.getPassword()); User user = User.builder() .username(command.getUsername()) .password(encodedPassword) .mobile(command.getMobile()) .nickname(StringUtils.isBlank(command.getNickname()) ? command.getUsername() : command.getNickname()) .status(UserStatus.ACTIVE) .version(0) .build(); try { userRepository.save(user); } catch (DataIntegrityViolationException e) { // 唯一索引兜底：并发窗口下 existsByUsername 的检查可能被绕过 throw new UserNameAlreadyExistsException(command.getUsername()); } // 事务提交后发布注册成功事件 eventPublisher.publishEvent(new UserRegisteredEvent(user.getId(), user.getMobile())); return userConverter.toVO(user); }密码加密我用的 Spring 自带的BCryptPasswordEncoder。BCrypt 的特点是每次加密同一个密码得到的哈希值都不一样，因为里面掺了随机盐，这样即使数据库被拖走，也无法通过彩虹表反推出原始密码。曾经有人建议我用 MD5 加盐，我直接否了，MD5 的运算速度太快，暴力破解成本太低，对存凭证的场景来说不是一个量级的安全级别。
这里有一个必须强调的并发细节：existsByUsername检查和save之间有时间窗，两个请求同时注册同一个用户名，可能都通过了 exists 检查，然后都执行 insert。所以我在数据库层面给username加了唯一索引，同时在save时捕获DataIntegrityViolationException做兜底。业务层面的检查和数据库层面的约束各管一关，前者给用户友好的提示，后者守住最后一道防线。这套组合在 v5 上线之后再没出现过重复用户名。
4.2 登录链路：密码校验、Token与状态控制
登录方法看起来简单，但坑都在细节里：
public LoginResultVO login(LoginCommand command) { User user = userRepository.findByUsername(command.getUsername()) .orElseThrow(() -> new UsernameNotFoundException(command.getUsername())); if (!passwordEncoder.matches(command.getPassword(), user.getPassword())) { throw new BadCredentialsException("用户名或密码错误"); } if (user.getStatus() != UserStatus.ACTIVE) { throw new AccountLockedException("账号已被禁用"); } String token = tokenService.generateToken(user.getId(), user.getUsername()); userRepository.updateLastLoginTime(user.getId(), LocalDateTime.now()); return LoginResultVO.builder() .token(token) .userInfo(userConverter.toVO(user)) .build(); }这里特意用了updateLastLoginTime这样一个 Repository 方法，而不是先把 User 查出来再setLastLoginTime再 save。原因很简单：登录是高频操作，每次都把整个 User 实体加载出来再整体更新，白白多查一次库，还会触发@Version版本号变更，让乐观锁频繁工作。用一条精确的 UPDATE 只更新一个列，既省流量又不会误伤版本号。这条优化让我在登录接口的 p90 延迟上降了不少。
账号状态检查放在密码校验之后，是有意的。如果用户不存在或者密码错误，统一返回“用户名或密码错误”，避免攻击者通过不同的错误提示逐个探测哪些用户名是注册过的。账号被禁用的场景单独抛出锁定异常，这个信息应该让用户知道，否则他不知道为什么登录不上。
Token 我用的是一段 JWT，里面只放 userId 和 username 这两个必要声明，不放大对象。JWT 的好处是服务端无状态，网关可以直接校验签名，不用每次回调 UserService 查 Session。但无状态也意味着无法主动吊销，所以我在用户表里维护了一个tokenVersion字段，用户修改密码或者后台强制下线时把这个版本号加一，之后再校验 Token 发现版本不匹配就拒绝。这个设计既保留了 JWT 的无状态优势，又给了运维一个“踢人下线”的开关。
4.3 事件驱动：把发短信、日志等副作用踢出UserService
v6 最重要的结构变化，是我把 UserService 方法里的“旁路操作”全部通过 Spring 事件机制踢了出去。以注册为例，注册后要发欢迎短信、要写审计日志、要给运营系统推送新用户数据。这些操作在 v5 之前全写在 register 方法里，一个注册接口要串行等短信服务响应，短信供应商一抖动，用户注册就跟着失败。
改造后的做法是发布一个领域事件：
public class UserRegisteredEvent extends ApplicationEvent { private final Long userId; private final String mobile; public UserRegisteredEvent(Long userId, String mobile) { super(userId); this.userId = userId; this.mobile = mobile; } // getter 省略 }监听方用@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)配合@Async，保证两点：只有事务提交成功后才执行监听逻辑，避免注册失败却发了短信的尴尬；监听逻辑在独立线程中异步执行，不阻塞注册请求的返回。
@Component @RequiredArgsConstructor public class UserRegisteredListener { private final SmsSender smsSender; private final AuditLogRepository auditLogRepository; @Async @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT) public void onUserRegistered(UserRegisteredEvent event) { smsSender.sendWelcome(event.getMobile()); auditLogRepository.record("USER_REGISTERED", event.getUserId()); } }这么改完以后，UserService 的代码变得非常干净：只做校验、加密、落库、发事件四件事。副作用执行失败不会影响主流程，而且可以随时新增监听器来扩展新需求，完全不用动 UserService 本身。这就是开闭原则在代码结构上的真实体现：对扩展开放，对修改关闭。
5. 版本6的测试布防与线上问题复盘
5.1 单元测试：把Service当成黑盒来测
v6 的 UserService 能持续迭代不返工，很大程度上归功于测试防护网。我把单元测试的书写原则定为：mock 掉 Repository、Redis、PasswordEncoder 这些外部依赖，只验证业务分支逻辑。
拿注册方法举例，最核心的测试用例有四个：用户名已存在时抛UserNameAlreadyExistsException；用户名不存在时成功创建用户并调用密码加密；数据库唯一索引冲突时被转换为业务异常；注册成功后确实发布了UserRegisteredEvent。
@ExtendWith(MockitoExtension.class) class UserServiceImplTest { @Mock private UserRepository userRepository; @Mock private PasswordEncoder passwordEncoder; @InjectMocks private UserServiceImpl userService; @Test void should_throw_when_username_already_exists() { when(userRepository.existsByUsername("jack")).thenReturn(true); RegisterCommand command = RegisterCommand.builder() .username("jack") .password("12345678") .mobile("13800000000") .build(); assertThrows(UserNameAlreadyExistsException.class, () -> userService.register(command)); } }这类测试的价值在于：任何一个分支逻辑被改坏，测试立刻红灯。比如有人不小心把existsByUsername删了，或者把唯一索引冲突的捕获改成了直接透出异常，测试都会拦下来。测试用例不需要多，但必须覆盖每个 return、每个 throw 和每个边界判断。
5.2 集成测试：H2还是Testcontainers
单元测试通过不代表真的能跑通，因为 JPA、数据库方言、Redis 交互这些只有集成测试才能暴露。v6 我同时维护了两种集成测试：一种用 H2 内存库跑 JPA 读写，跑得飞快，适合 CI 里每次合并前快速验证；另一种用 Testcontainers 起真实的 MySQL 和 Redis，跑完整的注册-登录-缓存链路，适合发布前在本地或者流水线的 nightly 任务里跑。
H2 有个坑需要注意：它的方言和真实 MySQL 有差异，比如唯一索引冲突时抛出的异常类型可能不同。我在 H2 测试里遇到过existsByUsername返回 false、insert 却报错的情况，排查下来发现是大小写和排序规则的差异。所以我的建议是：H2 测试用来验证逻辑结构，但涉及唯一约束、锁、事务回滚这类数据库强相关的行为，必须用 Testcontainers 覆盖一遍，否则测试环境的一片绿会给线上埋雷。
5.3 三个真实事故复盘
最后把 v5 到 v6 之间线上的三个事故翻出来复盘，这些案例比任何理论都更能说明为什么 Service 层必须做成现在这个样子。
第一个事故：并发用户注册，existsByUsername检查通过后两条线程同时 insert，数据库报了主键冲突，500 错误直接返回给用户，前端提示“系统异常，请稍后重试”。用户一脸懵，我们排查半天才发现是并发窗口问题。修复就是我在注册链路里加的唯一索引兜底和DataIntegrityViolationException捕获。
第二个事故：一场运营活动带来大量新用户注册，同时老用户密集修改资料，导致用户信息缓存大面积失效，瞬间流量全部打到数据库，连接数爆掉，服务雪崩。复盘后我加了互斥重建逻辑，用分布式锁把同一 userId 的缓存重建串行化，同时用 TTL 和空值缓存兜底，后续再遇到类似流量高峰，数据库都能稳稳扛住。
第三个事故最有教育意义：有人在注册方法的事务里调用了一个发优惠券的外部 HTTP 接口，接口响应慢，数据库事务一直开着，连接池被占满，最终拖垮了所有依赖数据库的接口。修复方案就是把这种外部调用挪到事务外，发布事件异步处理。这起事故之后我定了一条规定：@Transactional方法体内禁止一切网络 IO 调用，包括 HTTP、Redis 批量操作，必须全部移到事务外或者用事件异步化。
现在回头看，这三个事故分别对应了并发控制、缓存保护和事务边界三个方向，恰好就是 v6 改动最大的三块。说句实在话，我现在最感谢的不是某个优雅的设计模式，而是这些事故逼出来的防御性思考。
最后再说个个人体会：第六版上线至今，我给自己定了一条规矩——改动 UserService 任何方法之前，先想清楚这行代码会被谁调用、失败会造成什么影响，再把对应测试跑一遍。Service 层没有所谓的最后一版，只要业务在变，它就得跟着演进，但每一次演进都应该带着上一版的事故记忆，而不是推倒重来。如果你手头也有一个写了很久的 Service 类，不妨先花两天时间把它的调用方、依赖和异常路径梳理一遍，再决定改哪里，这大概率比直接动手重写更值钱。
