运行时出现java.lang.NoClassDefFoundError: reactivemongo/api/bson/SafeBSONWriter如何排查

• 依赖版本冲突排查：首先检查新增API服务模块的完整依赖树，确认所有ReactiveMongo相关依赖的版本完全一致。SafeBSONWriter是ReactiveMongo 1.x版本的内部API，如果有多个不同版本的ReactiveMongo依赖被加载，低版本不存在该类、或高版本调整了类的可见性/路径，都会触发运行时类加载失败。重点排查传递依赖：新增的API服务引入的第三方库是否自带了不同版本的ReactiveMongo，覆盖了原有服务的依赖版本。可以用sbt的dependencyTree指令、或Maven的dependency:tree指令筛选所有ReactiveMongo相关的依赖做校验。
• 打包/部署配置排查：集成测试使用测试专用的classpath，而API服务运行时使用的是打包后的依赖或运行时classpath，需要确认ReactiveMongo相关依赖没有被标记为provided范围，避免打包时遗漏对应的jar包。如果使用sbt-assembly等合并打包工具，还要检查排除规则、合并策略是否错误删除了ReactiveMongo的类文件。
• 类加载器隔离排查：如果使用Play、Akka HTTP等自带类加载器隔离的框架，或是服务部署在有容器隔离的环境中，需要确认Simple类隐式BSONHandler所在的模块，和调用ReactiveMongo API的模块使用的是同一个类加载器，否则就算依赖中存在对应类，跨类加载器访问也会报NoClassDefFoundError。
• 宏生成代码兼容性校验：你使用的Macros.using[MacroOptions.ReadDefaultValues].handler[Simple]会在编译阶段生成序列化逻辑，生成的代码会依赖编译时所用ReactiveMongo版本的内部API。如果编译Simple类时用的ReactiveMongo版本，和API服务运行时加载的版本不一致，宏生成代码引用的SafeBSONWriter在运行时版本中不存在，就会触发该错误。建议将ReactiveMongo的版本统一放到父模块的依赖管理中管控，保证所有模块编译、运行时使用的版本完全对齐。

内容的提问来源于stack exchange，提问作者Roman Kazanovskyi