# [026][数据模块]基于 MyBatis Plus 的企业级数据访问框架设计与实现

本项目代码:https://gitee.com/yunjiao-source/tutorials4j

## 摘要

在微服务与多租户 SaaS 架构日益普及的背景下，数据访问层需要统一解决分页、乐观锁、防 SQL 攻击、多租户隔离、审计字段自动填充等通用问题。本文介绍一套基于 MyBatis Plus 进行二次封装的轻量级框架，通过自动配置、拦截器链顺序控制、扩展点设计等机制，实现了可插拔、可配置的企业级数据访问能力。文章将详细分析其核心设计、关键组件实现以及配置方式，为类似场景下的框架封装提供参考。

## 1. 背景与目标

MyBatis Plus 作为 MyBatis 的强大增强工具，已经提供了分页、乐观锁、多租户等内置拦截器。但在实际企业应用中，仍面临以下挑战：

- **拦截器执行顺序**：不同拦截器（如租户、分页、乐观锁）有严格的顺序要求，顺序错误会导致 SQL 变形或逻辑失效。
- **可配置性**：不同模块可能需要动态开启/关闭某些拦截器（例如某些表不需要租户过滤）。
- **统一审计**：创建人、创建时间、修改人、修改时间等字段需要自动填充，避免业务代码重复。
- **扩展友好**：允许业务方自定义拦截器，并保证与框架内置拦截器协同工作。

本文分析的框架正是为了解决上述问题而设计，它以 Spring Boot AutoConfiguration 为基础，利用 `@ConditionalOnProperty` 控制拦截器开关，通过 `Ordered` 接口统一管理顺序，并提供钩子方法允许业务方注入自定义拦截器。

## 2. 整体架构

框架由以下几个核心模块组成：

- **自动配置模块**：`DataMybatisPlusConfiguration` 作为 Spring Boot 自动配置入口，按条件装配各个组件。
- **拦截器链模块**：定义 `MybatisPlusInterceptorCustomizer` 接口，各功能（分页、乐观锁、防攻击、租户）分别实现，并通过常量 `MybatisPlusConsts` 统一顺序。
- **租户模块**：`DefaultTenantLineInterceptorCustomizer` + `DefaultTenantLineHandler`，从 `TenantContextHolder` 动态获取租户 ID。
- **审计模块**：`AuditMetaObjectHandler` 实现 `MetaObjectHandler`，自动注入用户与时间信息。
- **标识符生成器**：`DefaultIdentifierGenerator` 替换 MyBatis Plus 默认的雪花算法实现。

下图展示了组件依赖关系：

```
DataMybatisPlusConfiguration
    │
    ├── 创建 MybatisPlusInterceptor（组合所有自定义器）
    ├── 条件化注册 PaginationInnerInterceptorCustomizer
    ├── 条件化注册 OptimisticLockerInterceptorCustomizer
    ├── 条件化注册 BlockAttackInterceptorCustomizer
    ├── 无条件注册 DefaultIdentifierGeneratorCustomizer
    ├── 条件化注册 AuditMetaObjectHandler
    └── （租户模块独立配置）DefaultTenantLineInterceptorCustomizer
```

## 3. 拦截器链设计：顺序与扩展

### 3.1 顺序常量定义

在 `MybatisPlusConsts` 中定义了严格的递增顺序：

```java
int INTERCEPTOR_ORDER_DEFAULT = 1;          // 预留
int INTERCEPTOR_ORDER_TENANT = 2;           // 租户先执行
int INTERCEPTOR_ORDER_PAGINATION = 3;       // 分页其次
int INTERCEPTOR_ORDER_OPTIMISTIC_LOCKER = 4;// 乐观锁
int INTERCEPTOR_ORDER_BLOCK_ATTACK = 5;     // 防攻击最后
```

> **为什么租户最先执行？**  
> 租户拦截器需要在 SQL 生成后第一时间注入租户条件，避免后续分页或乐观锁计算干扰租户字段。

### 3.2 扩展点接口

`MybatisPlusInterceptorCustomizer` 继承 `Ordered`，允许每个自定义器声明自己的顺序：

```java
@FunctionalInterface
public interface MybatisPlusInterceptorCustomizer extends Ordered {
    void custom(MybatisPlusInterceptor interceptor);
    default int getOrder() { return Ordered.LOWEST_PRECEDENCE; }
}
```

在自动配置中，所有实现了该接口的 Bean 都会被注入到 `MybatisPlusInterceptor`：

```java
@Bean
@ConditionalOnMissingBean
MybatisPlusInterceptor mybatisPlusInterceptor(ObjectProvider<MybatisPlusInterceptorCustomizer> customizers) {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    customizers.orderedStream().forEach(customizer -> customizer.custom(interceptor));
    return interceptor;
}
```

业务方只需实现该接口，并重写 `getOrder()` 返回合适的值，即可将自己的拦截器插入到框架链的正确位置。

### 3.3 内置自定义器实现

每个内置功能对应一个 `XxxInterceptorCustomizer`，例如分页：

```java
public class PaginationInnerInterceptorCustomizer implements MybatisPlusInterceptorCustomizer {
    private final DbType dbType;
    @Override
    public void custom(MybatisPlusInterceptor interceptor) {
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(dbType));
    }
    @Override
    public int getOrder() {
        return MybatisPlusConsts.INTERCEPTOR_ORDER_PAGINATION;
    }
}
```

乐观锁、防攻击的实现模式完全一致，均通过 `getOrder()` 返回对应常量。

## 4. 多租户隔离实现

租户模块独立于核心数据模块，通过 `DefaultTenantLineInterceptorCustomizer` 注入 `TenantLineInnerInterceptor`。其关键点：

- **租户 ID 动态获取**：`DefaultTenantLineHandler.getTenantId()` 返回 `TenantContextHolder.get()` 的值。`TenantContextHolder` 通常是基于 `ThreadLocal` 维护当前请求的租户编号，在网关或拦截器中设置。
- **忽略特定表**：通过配置 `tenant.mybatis-plus.ignore-table` 指定不需要租户过滤的表名（如系统配置表、字典表）。
- **顺序控制**：租户拦截器的顺序为 `INTERCEPTOR_ORDER_TENANT = 2`，确保它早于分页和乐观锁执行。

```java
public class DefaultTenantLineHandler implements TenantLineHandler {
    private final Set<String> ignoreTables;
    @Override
    public Expression getTenantId() {
        return new StringValue(TenantContextHolder.get());
    }
    @Override
    public boolean ignoreTable(String tableName) {
        return ignoreTables.contains(tableName);
    }
}
```

该设计使得业务 Mapper 无需感知租户字段，所有查询自动追加 `tenant_id = ?` 条件，更新/删除也会自动带上租户条件，有效避免了跨租户数据泄露。

## 5. 审计字段自动填充

框架提供了 `AuditMetaObjectHandler` 实现 `MetaObjectHandler`，用于自动填充 `createTime`、`updateTime`、`createBy`、`updateBy` 等字段。该类通常从 `SecurityContextHolder` 或 `RequestContextHolder` 中获取当前登录用户，填充对应属性。

由于用户信息的获取方式因项目而异，框架仅提供抽象示例，业务方可继承该类或直接实现 `MetaObjectHandler` 并标记 `@Primary` 覆盖。

## 6. 标识符生成器配置

MyBatis Plus 默认使用 `DefaultIdentifierGenerator`（雪花算法），但部分老项目可能由于时钟回拨或 workerId 分配问题需要自定义。框架通过 `MybatisPlusPropertiesCustomizer` 替换了标识符生成器：

```java
@Bean
MybatisPlusPropertiesCustomizer defaultIdentifierGeneratorMybatisPlusPropertiesCustomizer() {
    return plusProperties -> plusProperties.getGlobalConfig()
            .setIdentifierGenerator(new DefaultIdentifierGenerator());
}
```

若无需替换，业务方可自行注入同类型 Bean 覆盖。

## 7. 配置与开关控制

所有拦截器均通过 `@ConditionalOnProperty` 实现开关，配置前缀为 `tutorials4j.data.mybatis-plus`（由 `PropertiesConsts` 定义），例如：

```yaml
tutorials4j:
  data:
    mybatis-plus:
      db-type: mysql                     # 数据库类型，用于分页方言
      interceptors:
        pagination: true                 # 开启分页（默认 true）
        optimistic-locker: true          # 开启乐观锁（默认 true）
        block-attack: true               # 开启防全表删除/更新（默认 true）
```

租户模块独立配置：

```yaml
tutorials4j:
  tenant:
    mybatis-plus:
      ignore-table:                      # 忽略租户过滤的表
        - sys_config
        - sys_dict
```

业务方若需要完全自定义 `MybatisPlusInterceptor`，可以直接提供该类型的 Bean，框架会由于 `@ConditionalOnMissingBean` 而跳过默认创建。

## 8. 典型使用场景与扩展示例

### 场景一：新增一个数据权限拦截器

需求：根据用户角色自动追加 `dept_id` 条件。  
实现：

```java
public class DataScopeInterceptorCustomizer implements MybatisPlusInterceptorCustomizer {
    @Override
    public void custom(MybatisPlusInterceptor interceptor) {
        interceptor.addInnerInterceptor(new DataScopeInnerInterceptor());
    }
    @Override
    public int getOrder() {
        // 放在租户之后、分页之前
        return MybatisPlusConsts.INTERCEPTOR_ORDER_TENANT + 1;
    }
}
```

Spring 会自动发现该 Bean，并按 `orderedStream()` 顺序加入拦截器链。

### 场景二：关闭防攻击拦截器并替换为自定义实现

配置 `tutorials4j.data.mybatis-plus.interceptors.block-attack=false`，然后自己实现 `MybatisPlusInterceptorCustomizer` 并注册。

## 9. 总结

本文分析了一套基于 MyBatis Plus 的企业级数据访问框架，其核心设计思想包括：

- **自动化配置**：利用 Spring Boot 条件装配，按需加载组件。
- **顺序可控的拦截器链**：通过 `Ordered` 接口和常量定义，保证分页、租户、乐观锁等拦截器的正确执行顺序。
- **扩展点开放**：`MybatisPlusInterceptorCustomizer` 允许业务方无侵入地添加自定义拦截器。
- **多租户与审计标准化**：通过 `TenantLineHandler` 和 `MetaObjectHandler` 封装通用逻辑。

该框架已经在多个生产项目中验证，有效降低了数据访问层的重复代码量，并提升了多租户场景下的安全性与维护性。开发者在阅读本文后，可参照类似模式对自己的 MyBatis Plus 应用进行规范化封装。

---

**作者注**：实际使用中，还需谨慎处理租户 ID 的传递（如 Feign 调用、异步线程），以及审计字段的时区、用户信息上下文问题。框架中预留了 `TenantContextHolder` 与 `AuditMetaObjectHandler` 的扩展点，可根据具体环境实现。


本项目代码:https://gitee.com/yunjiao-source/tutorials4j

[026][数据模块]基于 MyBatis Plus 的企业级数据访问框架设计与实现

在微服务与多租户 SaaS 架构日益普及的背景下，数据访问层需要统一解决分页、乐观锁、防 SQL 攻击、多租户隔离、审计字段自动填充等通用问题。本文介绍一套基于 MyBatis Plus 进行二次封装的轻量级框架，通过自动配置、拦截器链顺序控制、扩展点设计等机制，实现了可插拔、可配置的企业级数据访问能力。文章将详细分析其核心设计、关键组件实现以及配置方式，为类似场景下的框架封装提供参考。

数据库

后端

开发工具

本文介绍基于MyBatisPlus的企业级数据访问框架设计，通过二次封装实现分页、乐观锁、多租户隔离、审计字段自动填充等功能。框架采用SpringBoot自动配置，通过拦截器链顺序控制与扩展点设计，提供可插拔、可配置的数据访问能力，有效解决企业应用中SQL变形、租户隔离等常见问题，为微服务架构提供统一数据访问解决方案。

数据泄露

代码解释

SaaS

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

[026][数据模块]基于 MyBatis Plus 的企业级数据访问框架设计与实现-腾讯云开发者社区-腾讯云

[026][数据模块]基于 MyBatis Plus 的企业级数据访问框架设计与实现

[026][数据模块]基于 MyBatis Plus 的企业级数据访问框架设计与实现

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐