Mockito单元测试实战：高频用例与避坑指南

单元测试写到一定阶段几乎所有人都会撞上同一堵墙依赖太多、状态太乱、真实对象根本构造不出来。数据库连接、外部接口、随机数、时间戳、文件系统这些东西一旦掺进被测代码测试就从“验证逻辑”变成了“搭建环境”。Mockito 这类测试替身框架就是在这个场景下被反复拿出来的工具而“Mockito 超全用例文档”这个标题本质上指向的是一件事——把日常写单测时能遇到的各类打桩、验证、参数匹配、行为模拟场景整理成一份可以直接抄、可以对照排查的用例集。我这些年带过不少刚接触单元测试的同学发现一个共性Mockito 的 API 就那么几个mock、when、verify、thenReturn看一遍文档半小时就能“会用”但真正写起来十有八九会卡在几个地方——静态方法怎么打桩、void方法怎么验证、泛型返回值怎么处理、连续调用怎么模拟不同结果、ArgumentCaptor什么时候该用。这些问题在官方文档里往往一笔带过得靠踩坑才能记住。所以这篇内容我打算按“用例”的思路来组织把每个高频场景拆成可复现的最小片段讲清楚它解决什么问题、为什么这么写、写的时候容易错在哪。适合谁看如果你已经能写基本的 JUnit 测试但对 Mockito 的掌握还停留在“会 mock 一个接口”的阶段那这篇基本能覆盖你接下来半年会遇到的绝大多数场景。如果你已经用得比较熟也可以把它当成一份速查手册尤其是参数匹配器和验证模式那几块细节多忘得也快。下面我按设计思路、核心用例、实操流程、问题排查四个大块展开中间会穿插大量可直接复制的代码片段和我自己踩过的坑。1. 整体设计与用例组织思路1.1 为什么按“用例”而不是按“API”来组织大多数 Mockito 的入门材料是按 API 罗列先讲mock()再讲when()再讲verify()。这种组织方式对查文档友好但对实际写测试不友好。因为真实写测试时你的思维起点不是“我要用哪个 API”而是“我这个场景该怎么模拟”。比如“我要让某个方法第一次返回成功、第二次抛异常”你脑子里想的是场景不是thenReturn().thenThrow()这个链式调用。按用例组织的好处是每个条目都是一个完整的问题-方案对。读者遇到问题时能直接按场景检索而不是先翻译成 API 名再去查。这也是我把标题定成“用例文档”而不是“API 手册”的原因。整份内容的组织逻辑是先按被测对象的类型分普通方法、void 方法、静态方法、泛型方法再按操作意图分打桩返回值、模拟异常、验证调用、捕获参数、模拟连续行为。这个二维结构基本能覆盖日常九成以上的场景。另一个考量是版本兼容。Mockito 从 2.x 到 5.x 变化不小尤其是静态方法打桩早期需要配合 PowerMock后来官方在 3.4.0 引入了mockStatic用法完全不同。用例文档必须标注清楚每个写法适用的版本区间否则读者复制过去直接编译失败。我在每个关键用例里都会注明版本要求这一点比 API 罗列式文档更重要。1.2 测试替身的分层mock、spy、stub 到底怎么选在动手写用例之前有个概念必须先理清否则后面全是糊涂账。Mockito 里常见的替身有三类mock、spy、stub严格说 stub 是一种行为不是对象类型但日常口语里常混用。很多同学分不清 mock 和 spy导致该用 spy 的地方用了 mock结果被测对象的真实逻辑根本没跑。mock创建的是一个完全空的对象所有方法默认返回“空值”——对象返回null基本类型返回默认值int是 0boolean是 false集合返回空集合。它不保留任何真实实现。适合模拟那些你完全不关心内部逻辑、只需要它“配合演出”的依赖比如一个远程服务客户端。spy则是基于一个真实对象创建的包装默认调用真实方法只有你显式打桩的方法才会被替换。适合你想保留大部分真实行为、只对个别方法做干预的场景。这里有个经典坑用spy时如果写成doReturn().when(spy).method()和when(spy.method()).thenReturn()效果不同后者会真实调用一次方法如果方法里有副作用或抛异常测试就直接挂了。这个细节我在第 4 部分会专门展开。至于 stub它指的是“预设返回值”这个动作本身。when(...).thenReturn(...)就是在做 stub。理解这三者的关系后面的用例才不会用错对象类型。1.3 用例覆盖的边界与取舍“超全”这个词容易让人误解好像要把所有 API 都覆盖一遍。实际上 Mockito 有些能力我刻意没纳入重点比如对final类的 mock需要额外配置 inline mock maker、对构造函数的 mock依赖mockConstruction场景较窄且容易让测试变脆。这些能力不是没用而是滥用会掩盖设计问题——一个类如果到处需要 mock 构造函数往往说明它该重构了。我重点覆盖的是那些“高频且容易写错”的场景参数匹配器的混用规则、void方法的验证、连续调用的行为序列、ArgumentCaptor的捕获时机、Answer接口做动态返回。这些是实际项目里出现频率最高、也最容易出 bug 的地方。取舍的标准很简单如果一个用例在真实项目里一个月都遇不到一次就不值得占篇幅如果一个用例每周都要写、每次都要查就必须写透。2. 核心用例拆解与关键细节2.1 基础打桩返回值、异常与默认行为最基础的用例是给方法预设返回值。假设有个订单查询服务依赖一个远程客户端public interface OrderClient { Order queryById(Long id); ListOrder queryByUser(Long userId); }打桩写法是when(orderClient.queryById(1L)).thenReturn(order)。这里第一个容易忽略的点是参数匹配。上面这种写法用的是“相等匹配”即实际调用时参数必须equals传入的值。如果被测代码传的是new Long(1)或者从别处解析出来的1L只要equals成立就能匹配上。但如果参数是对象且没重写equals就会匹配失败返回null然后被测代码 NPE排查半天才发现是打桩没生效。模拟异常用thenThrow注意抛出的异常类型必须和方法签名兼容受检异常要么方法声明了要么用RuntimeException子类。连续行为用链式调用when(orderClient.queryById(anyLong())) .thenReturn(order1) .thenReturn(order2) .thenThrow(new RuntimeException(timeout));这段的意思是第一次调用返回 order1第二次返回 order2第三次抛异常之后一直抛异常。这个用例在测试重试逻辑时特别有用。但要注意如果被测代码只调用了一次后面预设的行为不会触发也不会有任何提示——Mockito 默认不校验“所有 stub 都被用到”需要开启严格模式MockitoJUnitRunner.StrictStubs或ExtendWith(MockitoExtension.class)默认就是严格模式才会报UnnecessaryStubbingException。提示严格模式下未被使用的 stub 会直接让测试失败。这在团队协作时是好事能清理无用打桩但迁移老代码时会一次性爆出一堆失败建议新项目默认开启老项目逐步迁移。2.2 void 方法的打桩与验证void方法没有返回值所以不能用when(...).thenReturn(...)。打桩要用doThrow、doNothing、doAnswer这一族doThrow(new IllegalStateException(locked)) .when(orderClient).cancel(anyLong());这里有个语法上的坑doThrow(...).when(mock).method()里when后面跟的是 mock 对象不是方法调用。这和when(mock.method())的顺序正好相反新手经常写混。记住一个口诀有返回值的用 when 开头void 的用 do 开头。验证void方法是否被调用和普通方法一样用verifyverify(orderClient, times(1)).cancel(1L); verify(orderClient, never()).cancel(anyLong());void方法还有个高频场景是“回调式”接口比如void process(Order order, Callback callback)被测代码在方法内部调用callback.onSuccess(...)。这时候要用doAnswer来模拟回调触发doAnswer(invocation - { Callback cb invocation.getArgument(1); cb.onSuccess(ok); return null; }).when(orderClient).process(any(), any());invocation.getArgument(index)按位置取参数索引从 0 开始。这个用例在测试异步回调、事件监听时几乎是标配但要注意doAnswer里如果抛异常会原样传给调用方别在里面写会失败的断言。2.3 参数匹配器any、eq 与混用规则参数匹配器是 Mockito 里最容易出错的一块。核心规则只有一条如果用了匹配器所有参数都必须用匹配器。下面这种写法是错的// 错误第一个参数用了匹配器第二个用了具体值 when(orderClient.query(anyLong(), PAID)).thenReturn(order);正确写法是when(orderClient.query(anyLong(), eq(PAID)))。eq把具体值包装成匹配器。这条规则违反了会抛InvalidUseOfMatchersException报错信息还算清楚但新手往往看不懂“2 matchers expected, 1 recorded”是什么意思。常用匹配器我整理成一张表方便对照匹配器作用典型场景any()匹配任意对象包括 null不关心参数内容anyLong()/anyInt()匹配对应基本类型避免装箱拆箱问题eq(value)相等匹配可与其他匹配器混用部分参数固定isNull()/notNull()空值判断校验可选参数argThat(predicate)自定义条件复杂对象的部分字段校验contains(x)字符串包含日志、消息内容匹配argThat值得单独说它接受一个ArgumentMatcher可以做任意条件判断。比如只关心订单金额大于 100 的调用when(orderClient.query(argThat(o - o.getAmount() 100))).thenReturn(order);但argThat里如果写复杂逻辑失败时的报错信息会很模糊只告诉你“参数不匹配”不告诉你具体哪个字段不对。所以我的经验是能用eq就别用argThat非要用的话在ArgumentMatcher的toString()里返回可读描述方便排查。2.4 验证模式times、atLeast、inOrder 与超时验证verify的默认行为是“恰好一次”等价于times(1)。常用变体times(n)恰好 n 次never()0 次等价于times(0)atLeast(n)/atMost(n)至少/至多 n 次atLeastOnce()至少一次only()该方法是被验证对象上唯一被调用的方法only()用得少但很有用它能确保你没有漏验证其他调用。比如你只想确认cancel被调了、且没有其他方法被调用verify(mock, only()).cancel(...)。顺序验证用InOrderInOrder inOrder inOrder(orderClient, inventoryClient); inOrder.verify(orderClient).queryById(1L); inOrder.verify(inventoryClient).deduct(1L);这个用例在测试“先查订单再扣库存”这类流程时很关键。但要注意InOrder只校验你显式 verify 的那些调用之间的相对顺序没 verify 的调用不参与排序也不代表它们不存在。超时验证用verify(mock, timeout(1000)).method()适合测试异步调用。但timeout本质是轮询等待不是真正的异步感知在高并发测试里可能不稳定。我的建议是能用Awaitility这类专门的等待库就别用timeout后者只适合简单场景。2.5 ArgumentCaptor捕获参数做深度断言有时候你不满足于“方法被调用了”还想检查传进去的参数内容。这时候用ArgumentCaptorArgumentCaptorOrder captor ArgumentCaptor.forClass(Order.class); verify(orderClient).save(captor.capture()); Order saved captor.getValue(); assertEquals(PAID, saved.getStatus());captor.capture()在 verify 时占位调用结束后用getValue()取最后一次捕获的值getAllValues()取所有值。这里有个时机问题capture()必须在verify调用里使用不能在when里用。另外如果方法被调用了多次而你只关心最后一次用getValue()关心全部就用getAllValues()。ArgumentCaptor和argThat的区别值得说清楚argThat是在打桩/验证时做条件匹配匹配不上直接失败ArgumentCaptor是先把参数抓出来测试代码自己决定怎么断言。前者适合“我只要符合条件的调用”后者适合“我要检查参数的具体内容”。实际项目里涉及复杂对象的字段校验ArgumentCaptor更灵活报错信息也更清楚。2.6 静态方法与构造器的模拟静态方法打桩是 Mockito 3.4.0 之后才官方支持的写法是mockStatictry (MockedStaticIdGenerator mocked mockStatic(IdGenerator.class)) { mocked.when(IdGenerator::next).thenReturn(fixed-id); // 被测代码调用 IdGenerator.next() 会返回 fixed-id }注意mockStatic返回的是MockedStatic必须用 try-with-resources 关闭否则打桩会泄漏到其他测试造成莫名其妙的失败。这是静态打桩最大的坑我见过不止一次因为忘了关闭导致整个测试类随机挂。构造器模拟用mockConstruction同样需要关闭try (MockedConstructionConnection mocked mockConstruction(Connection.class, (mock, context) - when(mock.isOpen()).thenReturn(true))) { // new Connection() 返回的是 mock }这两个能力都很强但我的态度是能不用就不用。静态方法和构造器难测往往说明代码结构有问题比如工具类到处new、单例满天飞。真要用优先考虑重构实在改不动再用这两个 API 兜底。3. 实操流程与完整用例落地3.1 环境准备与依赖配置先给一份可直接用的依赖配置。以 Maven 为例核心是mockito-core和mockito-junit-jupiterJUnit 5 集成dependency groupIdorg.mockito/groupId artifactIdmockito-core/artifactId version5.11.0/version scopetest/scope /dependency dependency groupIdorg.mockito/groupId artifactIdmockito-junit-jupiter/artifactId version5.11.0/version scopetest/scope /dependency版本选择上5.x 需要 Java 11 及以上如果项目还在 Java 8用 4.11.0 这个最后的 4.x 版本。静态打桩在 3.4.0 引入mockConstruction在 3.5.0 引入用之前确认版本。JUnit 5 环境下用ExtendWith(MockitoExtension.class)JUnit 4 用RunWith(MockitoJUnitRunner.class)别混用。一个完整的测试类骨架长这样ExtendWith(MockitoExtension.class) class OrderServiceTest { Mock private OrderClient orderClient; Mock private InventoryClient inventoryClient; InjectMocks private OrderService orderService; Test void should_deduct_inventory_when_order_paid() { when(orderClient.queryById(1L)).thenReturn(paidOrder()); when(inventoryClient.deduct(anyLong())).thenReturn(true); orderService.pay(1L); verify(inventoryClient).deduct(1L); } }InjectMocks会自动把Mock标注的依赖注入到被测对象里注入方式按构造器、setter、字段的顺序尝试。这里有个坑如果被测类有多个构造器InjectMocks可能选错导致依赖注入不进去、字段为 null。排查方法是看测试报的 NPE 位置如果 NPE 出现在被测类内部对依赖的调用上八成是注入失败。稳妥做法是显式用构造器注入或者干脆手动new被测对象。3.2 一个完整业务场景的用例串联光看零散用例不够我把它们串成一个完整场景下单支付流程。被测类OrderService.pay(orderId)的逻辑是——查订单、校验状态、扣库存、更新订单状态、发通知。依赖三个外部服务。第一步准备测试数据和打桩Order order new Order(); order.setId(1L); order.setStatus(CREATED); order.setAmount(new BigDecimal(99.00)); when(orderClient.queryById(1L)).thenReturn(order); when(inventoryClient.deduct(1L)).thenReturn(true);第二步执行被测方法并验证核心调用orderService.pay(1L); verify(orderClient).queryById(1L); verify(inventoryClient).deduct(1L); verify(orderClient).updateStatus(1L, PAID);第三步用ArgumentCaptor检查通知内容ArgumentCaptorNotification captor ArgumentCaptor.forClass(Notification.class); verify(notifyClient).send(captor.capture()); Notification sent captor.getValue(); assertEquals(PAID, sent.getType()); assertEquals(1L, sent.getOrderId());第四步补充异常路径用例——库存不足时不应更新状态when(inventoryClient.deduct(1L)).thenReturn(false); assertThrows(InsufficientStockException.class, () - orderService.pay(1L)); verify(orderClient, never()).updateStatus(anyLong(), anyString());这一套下来正常路径、参数内容、异常路径都覆盖了。我特别想强调第四步里的never()验证——很多人只测正常路径不测“不该发生的事有没有发生”结果代码里一个漏掉的return就能让状态被错误更新测试却全绿。验证“没有发生”和验证“发生了”同等重要这是写单测时最容易被忽略的一条经验。3.3 连续调用与状态变化的模拟有些场景下同一个方法连续调用要返回不同结果模拟“状态变化”。比如一个库存查询接口第一次返回有货、第二次返回无货when(inventoryClient.query(1L)) .thenReturn(new Stock(10)) .thenReturn(new Stock(0));如果被测代码是循环调用还可以用thenAnswer做动态返回根据调用次数或参数计算AtomicInteger counter new AtomicInteger(0); when(inventoryClient.query(anyLong())) .thenAnswer(inv - new Stock(counter.getAndDecrement()));thenAnswer的invocation参数能拿到方法名、参数、甚至 mock 对象本身灵活性最高。但要注意Answer里不要写有副作用的复杂逻辑否则测试本身变得难懂。我的原则是能用thenReturn链式解决就别上thenAnswer后者是“最后手段”。还有一个高频场景是模拟“第一次抛异常、第二次成功”用来测重试when(remoteClient.call(anyString())) .thenThrow(new RuntimeException(network)) .thenReturn(ok);配合被测代码的重试逻辑能验证重试次数和最终结果。这里要注意如果被测代码捕获异常后没有重试测试会直接失败这恰恰是测试的价值——它逼你确认重试逻辑真的存在。3.4 泛型返回值与集合类型的处理泛型方法打桩时类型推断偶尔会出问题。比如public interface RepositoryT { ListT findAll(); R R convert(Object source, ClassR type); }对findAll()打桩when(repo.findAll()).thenReturn(list)一般没问题因为ListT能推断出来。但对泛型方法convert打桩时如果返回值类型不明确编译器可能推断成Object导致thenReturn类型不匹配。解决办法是显式指定类型参数when(repo.Stringconvert(any(), eq(String.class))).thenReturn(result);集合类型还有个常见坑thenReturn(Collections.emptyList())返回的是不可变空列表如果被测代码往里add会抛UnsupportedOperationException。要返回可变列表就用new ArrayList()。这个坑很隐蔽因为打桩本身没问题报错发生在被测代码里容易误判成业务 bug。4. 常见问题与排查技巧实录4.1 打桩不生效的五大原因打桩不生效是最高频的问题表现是被测代码拿到null或默认值然后 NPE。我按出现频率排了个序现象原因解决返回 null参数不匹配对象未重写 equals用any()或argThat放宽匹配返回 nullmock 对象和被测对象用的不是同一个实例检查InjectMocks是否注入成功抛InvalidUseOfMatchersException匹配器和具体值混用全部参数改用匹配器抛UnnecessaryStubbingException严格模式下 stub 未被使用删除无用 stub 或放宽严格模式静态打桩无效未关闭MockedStatic或版本过低用 try-with-resources确认版本 ≥ 3.4.0第一条“对象未重写 equals”特别值得展开。假设queryById(OrderQuery q)的参数是个自定义对象你没重写equals那when(client.query(new OrderQuery(1L)))打桩后被测代码传一个“内容相同但引用不同”的对象equals用的是Object默认实现引用比较匹配失败。这种问题排查起来很费劲因为代码看起来完全正确。我的建议是打桩时优先用any()或argThat别依赖具体对象的equals除非你确认它重写了且逻辑正确。4.2 verify 失败与调用次数不符的排查verify失败通常报Wanted but not invoked或TooManyActualInvocations。前者是方法压根没被调后者是调用次数超了。排查思路先看是不是 mock 对象不对。如果被测类内部自己new了一个依赖而不是用注入的 mock那 verify 的 mock 和实际调用的对象是两个实例自然对不上。这种情况要么改造成依赖注入要么用mockConstruction不推荐优先改代码。再看是不是调用被吞了。比如被测代码在 try-catch 里调用了方法但异常被捕获后没继续执行或者方法在某个条件分支里根本没走到。这时候可以在被测代码里临时加日志或者用verify(mock, atLeast(0)).method()先确认“至少被尝试调用过”再逐步收紧。还有一种情况是异步调用。被测方法内部起了个线程去调依赖主线程 verify 时子线程还没跑完自然 verify 失败。解决办法是用timeout()或Awaitility等待或者干脆把异步逻辑抽出来单独测。4.3 spy 的经典陷阱与正确姿势spy的坑我在 1.2 提过这里展开。假设有个类public class Calculator { public int add(int a, int b) { return a b; } public int doubleIt(int a) { return add(a, a); } }用 spy 打桩addCalculator spy spy(new Calculator()); when(spy.add(1, 1)).thenReturn(100);这行代码执行时when(spy.add(1, 1))会真实调用add(1, 1)返回 2然后when拿到这个返回值 2 去做匹配。如果add里有副作用比如计数、写日志副作用已经发生了。更糟的是如果add抛异常这行直接挂。正确姿势是用doReturndoReturn(100).when(spy).add(1, 1);doReturn不会触发真实调用直接替换行为。所以记住一条铁律spy 打桩一律用doReturn/doThrow/doAnswer不要用when(...).thenReturn(...)。这条规则能帮你避开 spy 九成的坑。4.4 测试隔离与静态打桩泄漏静态打桩泄漏是个隐蔽但破坏力极强的问题。mockStatic打开后如果不关闭打桩会一直生效影响后续所有测试。表现是“单独跑这个测试类通过一起跑就随机失败”而且失败位置飘忽不定极难排查。根因是MockedStatic是线程绑定的必须显式close()。用 try-with-resources 是最稳的写法try (MockedStaticClock mocked mockStatic(Clock.class)) { mocked.when(Clock::systemDefaultZone).thenReturn(fixedClock); // 测试逻辑 } // 出了这个块打桩自动失效如果测试方法里有多处静态打桩注意嵌套顺序内层先关。另外mockStatic和mockConstruction都不要在BeforeEach里打开、在AfterEach里关闭因为一旦BeforeEach抛异常AfterEach可能不执行导致泄漏。老老实实用 try-with-resources 包在测试方法内部。4.5 严格模式下的取舍Mockito 5.x 默认开启严格模式Strictness.STRICT_STUBS好处是能发现无用打桩和参数不匹配坏处是迁移老代码时一次性爆一堆UnnecessaryStubbingException。我的处理策略分三步第一步新写的测试类保持严格模式这是质量保障。第二步老测试类如果失败太多先用MockitoSettings(strictness Strictness.LENIENT)在类级别放宽让测试先跑起来。第三步逐个清理无用 stub清理完再移除 lenient 注解。别一上来就全局 lenient那样等于放弃了严格模式的所有好处。还有一种情况是参数匹配器导致的“假失败”。严格模式下如果 stub 用了any()但实际调用参数不匹配会报PotentialStubbingProblem。这时候要么收紧匹配器要么确认这个 stub 确实该放宽。我的经验是PotentialStubbingProblem十有八九是真问题——要么打桩参数写错了要么被测代码传参和预期不符值得逐个查。4.6 性能与可维护性的平衡最后聊个容易被忽略的点mock 用多了测试会变慢、变脆。一个测试类里几十个Mock、上百行打桩跑起来慢不说改一处业务逻辑要改十几处测试。我的经验是优先 mock 外部边界网络、数据库、文件系统内部协作对象尽量用真实实现。一个类如果依赖五六个服务先想想是不是职责太重了。测试的可维护性和代码的可维护性是同一件事的两面——测试难写往往说明设计有问题而不是测试工具不好用。另外别为了追求覆盖率写“为了 mock 而 mock”的测试。一个方法如果只是简单转发调用测它被调用了没多大意义真正该测的是它转发时的参数转换、异常处理、边界条件。用例文档给的是工具用法但工具用在哪、用多少得靠对业务的理解来判断。我在实际项目里踩过最深的坑是早期为了“测试全覆盖”给每个依赖都打了桩结果一个简单的业务改动要同步改二十几个测试文件维护成本远超收益。后来调整策略只 mock 真正的外部依赖内部逻辑尽量走真实路径测试数量少了三分之一bug 发现率反而没降。这个体会可能比任何 API 用法都值钱——工具是死的判断力是活的。