MyBatis通用Mapper跨模块复用：构建可插拔的统一数据访问层-java教程-PHP中文网

MyBatis通用Mapper跨模块复用：构建可插拔的统一数据访问层

本文详解如何在多模块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 无法识别继承链中的“未标注”父接口。

修正步骤如下：

重构包结构（强制隔离）

Spring Boot Actuator Analyzer

分析Spring Boot Actuator端点的安全性、健康检查、指标暴露及生产配置——审计信息、健康状态和自定义端点。

下载

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  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
}</scheduledtask>

此时，ScheduledTaskService 保持不变，仅需在不同模块中注入对应实现即可——真正实现“一套接口，多套实现”。