本文详解如何在多模块spring boot项目中设计并落地一个兼容mybatis与jpa的通用repository抽象层，通过正确包扫描、接口分层与条件注入，实现scheduledtaskrepository等核心dao能力在不同持久化技术栈（mybatis/mybatis-plus/hibernate）间的无缝复用。
本文详解如何在多模块spring boot项目中设计并落地一个兼容mybatis与jpa的通用repository抽象层，通过正确包扫描、接口分层与条件注入，实现scheduledtaskrepository等核心dao能力在不同持久化技术栈（mybatis/mybatis-plus/hibernate）间的无缝复用。
在微服务或模块化单体架构中，将数据访问逻辑下沉至公共模块（common module）是提升代码复用性与维护一致性的关键实践。但当该模块需同时支撑使用 MyBatis 的子模块和使用 Spring Data JPA 的子模块时，直接暴露 @Mapper 接口极易引发“Invalid bound statement”异常——正如你遇到的 BindingException: Invalid bound statement (not found)。根本原因在于：MyBatis 的 Mapper 接口必须被 MapperScannerConfigurer 或 @MapperScan 显式扫描注册，而 compileOnly 依赖 + 错误的包路径会导致扫描失效，且 @Mapper 注解无法跨模块自动生效。
✅ 正确架构设计：三层分离原则
为确保可复用性与技术中立性，应严格遵循以下分层：
| 层级 | 职责 | 示例 |
|---|---|---|
| API 层（api 或 repository 包） | 定义纯业务契约接口，不包含任何框架注解，面向所有持久化技术 | ScheduledTaskRepository（无 @Mapper、@Repository） |
| 实现层（impl.mybatis 等子包） | 提供具体框架实现，仅在此层添加 @Mapper | MybatisScheduledTaskRepository extends ScheduledTaskRepository |
| 配置层（AutoConfiguration） | 条件化启用实现，避免污染非MyBatis模块 | @ConditionalOnBean(MybatisAutoConfiguration.class) |
⚠️ 关键错误警示：@Mapper 绝不能出现在公共 API 接口中（如 ScheduledTaskRepository），否则 JPA 模块引入该 jar 后会因找不到 MyBatis 扫描器而编译/运行失败。
✅ 实战配置：解决 Invalid bound statement 异常
你已定位到问题核心：scheduledTaskRepository 字段被注入了 MapperProxy，但其 mapperInterface 是顶层接口 ScheduledTaskRepository，而非实际被扫描的 MybatisScheduledTaskRepository。这是因为 MyBatis 无法识别继承链中的“未标注”父接口。
修正步骤如下：
-
重构包结构（强制隔离）
ru.test.app.common.scheduling.repository # ← API 接口（无注解） └── impl └── mybatis # ← MyBatis 实现（含 @Mapper） └── MybatisScheduledTaskRepository.java -
移除父接口上的 @Mapper，仅保留在实现类
// ✅ 正确：仅实现类加 @Mapper @Mapper // ← 移至此处！ public interface MybatisScheduledTaskRepository extends ScheduledTaskRepository { @Select("SELECT * FROM scheduled_tasks WHERE state = #{state} AND type = #{type} AND run_count < #{maxRunCount}") List<ScheduledTask> getTasksByStateAndType( @Param("state") ScheduledTaskState state, @Param("type") ScheduledTaskType type, @Param("maxRunCount") int maxRunCount); // ... 其他方法 } -
在主应用启动类显式扫描实现包
@SpringBootApplication @MapperScan("ru.test.app.common.scheduling.repository.impl.mybatis") // ← 关键！ public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } } -
修正 Gradle 依赖（compileOnly → api / implementation）
compileOnly 仅提供编译时类路径，不传递运行时依赖，导致测试时 MyBatis 扫描器不可用：// ❌ 错误：compileOnly 使 mybatis-spring-boot-starter 不参与 runtime classpath compileOnly 'org.mybatis.spring.boot:mybatis-spring-boot-starter:2.1.3' // ✅ 正确：使用 api 或 implementation（推荐 api，便于下游传递） api 'org.mybatis.spring.boot:mybatis-spring-boot-starter:2.1.3'
-
（可选）增强条件注入可靠性 若需更健壮的自动装配，可在 ScheduledTaskService 中使用 @Qualifier 明确指定实现：
@Service @RequiredArgsConstructor public class ScheduledTaskService { private final @Qualifier("mybatisScheduledTaskRepository") ScheduledTaskRepository repository; // ... }
✅ 多持久化技术兼容方案（JPA 模块如何接入？）
为让 JPA 模块也能复用同一 ScheduledTaskRepository，需为其提供独立实现：
// 在 JPA 模块中定义（无需引入 MyBatis 依赖）
@Repository
public class JpaScheduledTaskRepository implements ScheduledTaskRepository {
private final ScheduledTaskJpaRepository jpaRepository;
@Override
public List<ScheduledTask> getTasksByStateAndType(ScheduledTaskState state, ScheduledTaskType type, int maxRunCount) {
return jpaRepository.findByStateAndTypeAndRunCountLessThan(state, type, maxRunCount);
}
// ... 其他方法委托给 Spring Data JPA
}此时，ScheduledTaskService 保持不变，仅需在不同模块中注入对应实现即可——真正实现“一套接口，多套实现”。
✅ 总结：跨模块通用 Mapper 的黄金法则
- 接口纯净：Repository 接口是业务契约，零框架侵入；
- 实现隔离：@Mapper / @Repository 仅存在于具体实现包，且包路径明确、可扫描；
- 依赖显式：mybatis-spring-boot-starter 必须作为 api 或 runtime 依赖传递；
- 扫描精准：@MapperScan 指向实现类所在包，而非 API 接口包；
- 条件可控：通过 @ConditionalOnBean 或 Profile 控制实现类的加载时机。
遵循以上规范，你不仅能彻底解决 Invalid bound statement 异常，更能构建出高内聚、低耦合、可演进的模块化数据访问架构——让通用 Mapper 成为团队协作的基石，而非集成陷阱。
