星海日和

MySQL安装与使用

Mon, 31 Aug 2026 09:39:22 GMT

MySQL 8.4.11 Windows 安装与使用教程

适用于 Windows 10 / 11，包含 MySQL Server 8.4.11 LTS 安装、初始化配置、服务管理、Navicat Premium 17 连接以及 PowerShell 基础操作。

开始前

本教程使用以下环境：

项目	本教程环境
操作系统	Windows 10 / Windows 11（64 位）
数据库	MySQL Community Server 8.4.11 LTS
安装包	`mysql-8.4.11-winx64.msi`
图形化管理工具	Navicat Premium 17
MySQL 服务名	`MySQL84`
默认连接端口	`3306`

如果已经拿到配套“资料”文件夹，其中包含 Navicat17 文件夹和 mysql-8.4.11-winx64.msi，可以直接开始安装，不必重复下载。

配套资料文件夹

本教程只介绍安装、初始化、连接和基础使用，不包含 MySQL 卸载。示例中 root 密码使用 123456，仅用于课堂演示；实际使用时应设置更安全的密码。

Navicat Premium 为商业软件，请使用官方试用版、正版授权或学校 / 组织提供的合法授权。

下载地址

安装 MySQL Server

下载 MSI 安装包

打开 MySQL Community Server 官方下载页面：

Select Version：选择 8.4.11 LTS
Select Operating System：选择 Microsoft Windows
下载类型：选择 Windows (x86, 64-bit), MSI Installer

本教程使用的安装包为：

mysql-8.4.11-winx64.msi

大小约 130 MB。这里建议使用 MSI Installer，而不是 ZIP Archive，因为 MSI 可以直接通过图形化安装向导完成安装，并包含后续需要使用的 MySQL Configurator。

MySQL Community Server 下载页面

点击 Download 后，Oracle 页面可能要求登录账号。安装 Community Server 不要求必须注册，可以点击：

No thanks, just start my download.

直接开始下载。

跳过 Oracle 账号登录

MySQL MSI 安装包下载中

运行安装程序

双击 mysql-8.4.11-winx64.msi。如果 Windows 弹出“用户账户控制”提示，选择“是”。

进入 MySQL Server 8.4 Setup Wizard 后点击 Next。

MySQL Server 安装向导

在 End-User License Agreement 页面勾选：

I accept the terms in the License Agreement

然后点击 Next。

接受许可协议

选择 Typical 安装

在 Choose Setup Type 页面可以看到 Typical、Custom 和 Complete 三种安装方式。

用于课程学习和常规开发时，选择 Typical 即可。该模式会安装常用的 MySQL Server 组件，后续可以直接通过 Navicat、Java、Python 等程序连接。

选择 Typical 安装

进入 Ready to install MySQL Server 8.4 页面后点击 Install。

准备安装 MySQL Server

安装完成后，保持 Run MySQL Configurator 处于勾选状态，然后点击 Finish。

安装完成并启动 MySQL Configurator

接下来会自动进入 MySQL 的首次初始化配置。

初始化 MySQL

安装完成并不代表 MySQL 已经可以直接使用。第一次安装后，还需要在 MySQL Configurator 中完成数据目录、端口、root 密码、Windows 服务和文件权限等配置。

进入 Configurator

在 Welcome to the MySQL Server Configurator 页面点击 Next。

MySQL Server Configurator 欢迎页

数据目录

Data Directory 用于保存 MySQL 的数据库数据文件。默认目录通常为：

C:\ProgramData\MySQL\MySQL Server 8.4\

普通学习和开发环境保持默认即可，然后点击 Next。

MySQL 数据目录

网络与端口

进入 Type and Networking 后，按以下方式配置：

配置项	建议值
Config Type	`Development Computer`
TCP/IP	开启
Port	`3306`
X Protocol Port	`33060`
Named Pipe	不开启
Shared Memory	不开启

MySQL 网络与端口设置

Open Windows Firewall ports for network access 用于把 MySQL 端口加入 Windows 防火墙规则。

只在本机使用 Navicat、Java 或 Python 连接：可以取消勾选。
需要其他计算机通过网络访问本机 MySQL：根据实际网络环境和安全要求配置防火墙。

后面连接 MySQL 时主要会用到下面三个参数：

参数	值
Host	`localhost` 或 `127.0.0.1`
Port	`3306`
User	`root`

设置 root 密码

在 Accounts and Roles 页面设置 root 管理员账户密码。

本教程示例填写：

在 MySQL Root Password 和 Repeat Password 中输入相同密码即可。下方 Add User 可以创建普通账户，本教程暂不额外创建用户。

123456 仅用于演示。真实项目中不要使用这种弱密码。

设置 root 密码

配置 Windows 服务

在 Windows Service 页面保持以下设置：

勾选 Configure MySQL Server as a Windows Service
Windows Service Name：MySQL84
勾选 Start the MySQL Server at System Startup
服务运行账户选择 Standard System Account

这样 MySQL 会作为 Windows 服务运行，并在系统启动时自动启动。

配置 MySQL84 Windows 服务

文件权限与示例数据库

在 Server File Permissions 页面保持默认第一项，使 MySQL 数据目录只向服务账户和管理员组提供完整访问权限。

MySQL 数据目录文件权限

接下来会询问是否创建 Sakila 和 World 示例数据库。本教程后面会自己创建 test_db 和 student 表，因此这两项都不勾选，直接点击 Next。

不安装示例数据库

应用配置

进入 Apply Configuration 页面后点击 Execute。

开始应用 MySQL 配置

Configurator 会自动完成配置文件写入、Windows 服务配置、数据库初始化、文件权限设置、服务启动和安全配置等操作。

执行结束后，确认各项左侧均出现绿色对勾，并看到：

The configuration for MySQL Server 8.4.11 was successful.

MySQL 配置执行成功

如果出现红色错误标记，先打开 Log 页签查看具体报错信息。

最后点击 Next，进入 Configuration Complete 页面，再点击 Finish。

MySQL 初始化配置完成

至此，MySQL Server 8.4.11 已完成安装和初始化。

管理 MySQL84 服务

MySQL Server 在 Windows 中以服务形式运行，本教程的服务名称是 MySQL84。Navicat、终端以及其他程序要连接数据库，首先必须保证该服务正在运行。

在 Windows 服务中查看状态

按 Win + R，输入：

services.msc

按 Enter 打开“服务”管理器，在列表中找到 MySQL84。

正常情况下：

状态：正在运行
启动类型：自动

Windows 服务中的 MySQL84

如果状态为空，说明服务已经停止。右键 MySQL84 后可以选择“启动”“停止”或“重新启动”。

Navicat 突然无法连接 MySQL 时，优先检查 MySQL84 是否正在运行。

使用终端管理服务

也可以用管理员权限打开 CMD、PowerShell 或 Windows Terminal，然后执行：

net start MySQL84
net stop MySQL84

需要重新启动时，可以依次执行：

net stop MySQL84
net start MySQL84

如果出现“拒绝访问”或权限不足，请确认终端是否以管理员身份运行。

使用 Navicat 连接 MySQL

安装并打开 Navicat

配套资料中已经提供 Navicat17 文件夹。如果需要自行安装，可以使用前面给出的安装参考。

Navicat Premium 17 安装参考

Navicat Premium 为商业软件，请使用官方试用、正版授权或学校 / 组织提供的合法许可。

安装完成后打开 Navicat Premium 17。左侧“我的连接”用于管理数据库连接，顶部工具栏可以进行查询、表、视图、函数、用户和备份等操作。

Navicat Premium 17 主界面

新建 MySQL 连接

点击左上角“连接”，选择 MySQL，然后点击“下一步”。

选择 MySQL 连接类型

在“新建连接（MySQL）”窗口中填写：

参数	示例值
连接名称	`MySQL84`
主机	`localhost`
端口	`3306`
用户名	`root`
密码	安装时设置的 root 密码

本教程示例密码为 123456。

填写完成后先点击“测试连接”。连接成功后，再点击“确定”保存。

Navicat MySQL 连接参数

如果测试连接失败，依次检查：

MySQL84 服务是否正在运行
端口是否为 3306
用户名是否为 root
root 密码是否正确

查看系统数据库

保存连接后，在左侧双击 MySQL84。

连接成功后一般可以看到：

information_schema
mysql
performance_schema
sys

这些属于 MySQL 自身的系统数据库，初学阶段不建议随意修改。

MySQL 系统数据库

创建数据库并练习 SQL

接下来通过 Navicat 创建一个 test_db 数据库，再创建 student 表并完成插入和查询。

创建 test_db

在左侧 MySQL84 连接上右键，选择“新建数据库”。

新建数据库

数据库名称填写：

test_db

字符集选择：

utf8mb4

utf8mb4 可以完整保存 Unicode 字符，适合中文、英文及其他字符。排序规则保持默认即可。

创建 test_db 数据库

创建 student 表

选中 test_db，点击“新建查询”，执行：

CREATE TABLE student (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(50),
    age INT,
    score DECIMAL(5,2)
);

这张表包含 id、name、age 和 score 四个字段，其中 id 是自增主键。

编写 CREATE TABLE 语句

点击“运行”。如果下方显示“成功 1、错误 0”或 OK，说明表已经创建成功。

student 表创建成功

插入测试数据

继续执行：

INSERT INTO student (name, age, score)
VALUES
('张三', 20, 88.5),
('李四', 21, 92.0);

如果结果显示：

Affected rows: 2

说明两条数据插入成功。

向 student 表插入数据

查询数据

执行：

SELECT * FROM student;

结果区域会显示 id、name、age、score 等字段和对应记录。

查询 student 表

截图中张三和李四出现了重复记录，是因为 INSERT 语句被执行了两次，不影响本教程对查询操作的说明。

使用 PowerShell 操作 MySQL

Navicat 属于图形化管理工具，MySQL 也可以直接通过命令行客户端操作。掌握基本终端操作后，在没有图形界面的环境中也可以管理数据库。

进入 MySQL bin 目录

MySQL 8.4 默认安装目录通常为：

C:\Program Files\MySQL\MySQL Server 8.4\bin

打开 PowerShell 或 Windows Terminal，执行：

cd "C:\Program Files\MySQL\MySQL Server 8.4\bin"

登录 MySQL

在 PowerShell 中运行当前目录下的 MySQL 客户端：

.\mysql -u root -p

按 Enter 后出现 Enter password:，输入安装时设置的 root 密码。

输入密码时终端通常不会显示字符，这是正常现象。登录成功后会出现：

mysql>

可以先查看当前服务器中的数据库：

SHOW DATABASES;

PowerShell 登录 MySQL

查看 test_db 和 student

继续执行：

USE test_db;
SHOW TABLES;
DESC student;
SELECT * FROM student;

这些命令分别表示：

命令	作用
`USE test_db;`	切换到 `test_db` 数据库
`SHOW TABLES;`	查看当前数据库中的表
`DESC student;`	查看 `student` 表结构
`SELECT * FROM student;`	查询 `student` 表全部数据

终端查看 student 表结构和数据

Navicat 和命令行连接的是同一个 MySQL Server，因此在 Navicat 中创建的数据库、表和数据，也可以直接在命令行中查询。

常见问题

Navicat 无法连接 MySQL

先检查 MySQL84 服务是否正在运行。

按 Win + R，输入 services.msc；或者用管理员终端执行：

net start MySQL84

如果服务本身没有启动，Navicat 无法正常连接。

Access denied for user root

通常是用户名或密码不正确。

检查以下内容：

用户名是否为 root
输入的密码是否与 Configurator 中设置的一致
Navicat 是否保存了旧密码

如果 Navicat 保存的是旧密码，编辑连接后重新输入即可。

3306 端口连接失败

确认 Navicat 使用的端口和 MySQL Configurator 中设置的端口一致，本教程为 3306。

如果本机已有其他程序占用 3306，MySQL 服务可能无法正常启动，需要检查端口占用情况或重新配置 MySQL 端口。

PowerShell 提示 mysql 不是可识别的命令

这通常说明 MySQL 的 bin 目录没有加入系统 Path。

不修改环境变量也可以直接使用，先进入 MySQL 的 bin 目录：

cd "C:\Program Files\MySQL\MySQL Server 8.4\bin"
.\mysql -u root -p

test_db 或 student 没有显示

在 Navicat 左侧连接或数据库上右键选择“刷新”，或者重新打开 MySQL84 连接。

也可以在终端中依次检查：

SHOW DATABASES;
USE test_db;
SHOW TABLES;

完成后的基础操作流程

完成以上步骤后，应该已经能够：

在 Windows 10 / 11 上安装并初始化 MySQL Community Server 8.4.11 LTS
理解 MySQL84 Windows 服务的作用，并能够启动或停止服务
使用 Navicat Premium 17 连接本机 MySQL
创建数据库和数据表
使用 INSERT 写入数据
使用 SELECT 查询数据
使用 PowerShell 登录 MySQL 并执行基础 SQL 命令

日常练习时，可以把整个流程记成：

启动 MySQL84 → 登录 MySQL → 选择 / 创建数据库 → 创建表 → 插入数据 → 查询数据

完成这些基础操作后，就可以继续学习 SQL、数据库设计，以及 Java / Python 项目连接 MySQL。

华夏云智能监控服务管理平台

Fri, 07 Aug 2026 05:51:06 GMT

image-20260807140141105

github.com

GitHub - qzh200/hyxy_demo

Contribute to qzh200/hyxy_demo development by creating an account on GitHub.

https://github.com/qzh200/hyxy_demo

SpringSecurity

Mon, 03 Aug 2026 02:03:20 GMT

SpringSecurity6 企业级安全框架

Spring Security 基础

什么是 Spring Security

Spring Security 是 Spring 生态中的安全框架，主要用于处理 Servlet 应用和响应式应用中的身份认证、访问授权及常见安全防护。

与 Apache Shiro 相比，Spring Security 与 Spring Boot、Spring MVC、OAuth 2.0 等组件的集成更紧密，扩展点也更丰富。框架能力较多，因此学习时应先掌握过滤器链、认证对象和授权规则等核心概念。

认证与授权

企业应用通常需要解决两个核心问题：

身份认证（Authentication）：确认当前访问者是谁，以及其身份是否合法。
访问授权（Authorization）：确认已经通过认证的用户是否有权访问某项资源或执行某个操作。

以在线教育平台为例：

用户类型	允许执行的操作
学生	查看课程
教师	发布课程
管理员	删除用户

认证解决“你是谁”，授权解决“你能做什么”。

Spring Security 的主要能力

Spring Security 的常见能力包括：

用户名密码认证、证书认证、一次性令牌认证等身份认证机制。
URL 级别与方法级别的访问授权。
密码编码与校验。
会话管理、固定会话攻击防护和并发会话控制。
CSRF 防护、安全响应头等 Web 安全能力。
OAuth 2.0 客户端、资源服务器和 OpenID Connect 集成。

XSS 主要需要通过输出编码、内容安全策略和前端安全开发规范进行防护。Spring Security 可以配置部分安全响应头，但不能替代业务层面的 XSS 防护。

CSRF

CSRF 是跨站请求伪造。攻击者诱导已经登录合法站点的用户访问恶意页面，浏览器可能自动携带合法站点的 Cookie，从而使合法站点误以为请求由用户本人发起。

XSS

XSS 是跨站脚本攻击。攻击者设法将恶意脚本注入网页，其他用户访问页面时，浏览器执行该脚本，可能造成信息窃取、身份冒用或页面篡改。

Session 模式与 Token 模式

Spring Security 同时支持有状态和无状态认证。前后端分离并不意味着只能使用 Token，但在分布式 API 中，使用 Bearer Token 的无状态方案较为常见。

对比项	Session 有状态认证	Token 无状态认证
状态位置	服务端保存会话，客户端通常保存会话 Cookie	服务端通常不保存登录会话，客户端携带访问令牌
集群部署	需要会话复制、共享存储或粘性会话	各节点可独立验证令牌
浏览器自动携带	Cookie 通常由浏览器自动携带	`Authorization` 请求头通常由客户端代码主动添加
注销与撤销	服务端删除会话即可立即失效	需要短有效期、黑名单或令牌版本等机制
典型场景	服务端渲染网站、同源 Web 应用	前后端分离 API、微服务资源服务器

将 Token 存入 localStorage 会增加 Token 被 XSS 窃取的风险。生产系统应根据威胁模型选择内存、受保护 Cookie 或其他存储方案。若使用浏览器自动携带的 Cookie，仍需评估并配置 CSRF 防护。

核心架构

image-001

Spring Security 的 Servlet 安全能力建立在过滤器链之上。请求进入业务控制器之前，会先经过 Spring Security 选择的 SecurityFilterChain。

常见核心组件如下：

组件	作用
`SecurityFilterChain`	声明当前请求需要执行的安全过滤器
`FilterChainProxy`	根据请求匹配并执行相应的 `SecurityFilterChain`
`Authentication`	表示认证请求或当前已认证主体
`AuthenticationManager`	定义认证入口
`AuthenticationProvider`	执行某一种具体认证方式
`UserDetailsService`	按用户名加载用户信息
`PasswordEncoder`	编码密码并校验密码
`SecurityContext`	保存当前请求关联的 `Authentication`
`SecurityContextHolder`	提供访问 `SecurityContext` 的统一入口

面试题：Spring Security 的主要作用是什么？

Spring Security 主要解决应用中的身份认证和访问授权问题，并提供密码编码、会话管理、CSRF 防护、安全响应头以及 OAuth 2.0 集成等安全能力。

Spring Boot 3 整合 Spring Security

环境要求

本课程示例使用以下环境：

Spring Boot 3.3+
Java 17+
Spring Security 6
Maven
Vue 3

引入依赖

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
</dependencies>

编写第一个接口

@RestController
@RequestMapping("/user")
public class UserController {

    @GetMapping("/hello")
    public String hello() {
        return "hello security";
    }
}

启动项目后访问 http://localhost:8080/user/hello。在没有自定义安全配置时，Spring Boot 会为 Web 应用启用默认安全配置，并显示登录页面。

image-002

默认用户

当项目中没有自定义 UserDetailsService、AuthenticationProvider 等认证配置时，Spring Boot 通常会创建默认用户：

username: user
password: 启动时随机生成

随机密码会输出到控制台。

image-003

自定义默认用户名和密码

spring:
  security:
    user:
      name: admin
      password: 123456

该配置适合入门演示，不适合生产环境。生产系统应从数据库、LDAP 或外部身份服务加载用户，并使用 PasswordEncoder 保存密码摘要。

默认登录页面的形成过程

在默认配置下，可将启动和访问过程概括为：

Spring Boot 启动
→ 加载 Spring Security 自动配置
→ 创建安全过滤器链
→ 请求被过滤器链拦截
→ 发现请求尚未认证
→ 进入登录流程或返回认证响应

面试题：为什么 Spring Security 不只使用 Controller 拦截请求？

Spring Security 的 Servlet 支持建立在 Filter 机制之上。过滤器位于 DispatcherServlet 和控制器之前，可以在请求进入业务层之前完成认证、授权和安全上下文管理。

典型顺序可以简化为：

Servlet Filter → DispatcherServlet → HandlerInterceptor → Controller

Spring Security 核心原理

学习目标

完成本章后，应能够：

理解 Spring Security 的整体请求流程。
掌握 SecurityFilterChain 的工作机制。
理解 Authentication 的两种主要用途。
掌握 AuthenticationManager 与 AuthenticationProvider 的关系。
理解 SecurityContext 与 SecurityContextHolder 的职责。
分析用户名密码认证的主要执行步骤。

基于 Filter 的安全处理

在传统 Spring MVC 应用中，请求流程可以简化为：

客户端请求
→ Servlet Filter
→ DispatcherServlet
→ HandlerInterceptor
→ Controller
→ Service
→ DAO
→ Database

Spring Security 选择过滤器作为 Servlet 安全入口，使认证和授权可以在业务代码执行前完成。

例如，用户请求 GET /api/user/delete/1 时，安全过滤器链会先判断用户是否已经认证以及是否具有删除权限。校验失败时，请求不会进入目标控制器。

SecurityFilterChain

SecurityFilterChain 表示一组用于处理安全任务的过滤器。一个应用可以声明多个安全过滤器链，每条链负责不同的请求范围。

image-004

DelegatingFilterProxy 与 FilterChainProxy

Spring Security 的 Servlet 请求转发关系可以概括为：

DelegatingFilterProxy
→ FilterChainProxy
→ 匹配到的 SecurityFilterChain
→ 链内的 Security Filter

image-005

DelegatingFilterProxy 注册在 Servlet 容器中，负责把过滤工作委托给 Spring 容器管理的 Filter Bean。
FilterChainProxy 是 Spring Security 的核心入口，会根据当前请求匹配合适的 SecurityFilterChain。
被选中的 SecurityFilterChain 按顺序执行其中的安全过滤器。

过滤器的具体组成取决于配置。常见过滤器包括：

SecurityContextHolderFilter：加载并管理安全上下文。
CsrfFilter：启用 CSRF 时校验 CSRF Token。
UsernamePasswordAuthenticationFilter：启用表单登录时处理用户名密码登录请求。
BearerTokenAuthenticationFilter：配置 OAuth 2.0 资源服务器时处理 Bearer Token。
AnonymousAuthenticationFilter：为匿名请求提供匿名 Authentication。
ExceptionTranslationFilter：把认证和授权异常转换为相应处理流程。
AuthorizationFilter：执行请求级授权判断。

部分旧版架构图中会出现 FilterSecurityInterceptor。在 Spring Security 6 的常用配置中，请求授权通常由 AuthorizationFilter 完成。实际过滤器列表应以项目启动日志或调试输出为准。

Authentication 认证模型

image-006

Authentication 的作用

Authentication 有两种主要用途：

作为待认证凭证提交给 AuthenticationManager。
表示当前已经通过认证的主体，并保存到 SecurityContext 中。

接口中的常用方法如下：

public interface Authentication extends Principal, Serializable {
    Object getPrincipal();

    Object getCredentials();

    Collection<? extends GrantedAuthority> getAuthorities();

    boolean isAuthenticated();
}

方法	作用
`getPrincipal()`	返回主体，用户名密码认证成功后通常为 `UserDetails`
`getCredentials()`	返回凭证，通常为密码；认证成功后可能被清除
`getAuthorities()`	返回角色、权限或作用域集合
`isAuthenticated()`	表示当前对象是否已经通过认证

认证前后的状态

登录前创建的 UsernamePasswordAuthenticationToken 通常只包含用户名和密码，并处于未认证状态：

UsernamePasswordAuthenticationToken
├── principal: admin
├── credentials: 123456
├── authorities: []
└── authenticated: false

认证成功后返回的新对象通常包含用户详情和权限，并处于已认证状态：

UsernamePasswordAuthenticationToken
├── principal: UserDetails
├── credentials: null
├── authorities: [ROLE_ADMIN, permission:query]
└── authenticated: true

不要通过不安全方式把任意未验证对象直接标记为已认证状态。

AuthenticationManager 与 AuthenticationProvider

AuthenticationManager 定义统一认证入口：

Authentication authenticate(Authentication authentication)
        throws AuthenticationException;

ProviderManager 是最常见的 AuthenticationManager 实现。它会依次询问多个 AuthenticationProvider，由支持当前 Authentication 类型的 Provider 执行认证。

典型用户名密码认证流程如下：

Authentication
→ AuthenticationManager
→ ProviderManager
→ DaoAuthenticationProvider
→ UserDetailsService
→ PasswordEncoder

不同认证方式可以使用不同 Provider。例如：

DaoAuthenticationProvider 处理数据库用户名密码认证。
OAuth 2.0 资源服务器中的 JwtAuthenticationProvider 处理 JWT Bearer Token。
自定义 AuthenticationProvider 可以处理短信验证码等业务凭证。

UserDetailsService

Spring Security 不知道用户保存在哪里，因此通过 UserDetailsService 抽象用户查询过程。

public interface UserDetailsService {
    UserDetails loadUserByUsername(String username)
            throws UsernameNotFoundException;
}

用户信息可以来自 MySQL、Redis、LDAP 或其他用户中心。

下面是一个简化示例：

@Service
@RequiredArgsConstructor
public class UserService implements UserDetailsService {

    private final UserMapper userMapper;

    @Override
    public UserDetails loadUserByUsername(String username) {
        User user = userMapper.findByUsername(username);
        if (user == null) {
            throw new UsernameNotFoundException("账号不存在");
        }

        return org.springframework.security.core.userdetails.User
                .withUsername(user.getUsername())
                .password(user.getPassword())
                .roles("USER")
                .build();
    }
}

SecurityContext 与 SecurityContextHolder

SecurityContext 保存当前认证对象，SecurityContextHolder 提供对当前安全上下文的访问入口。

Authentication authentication = SecurityContextHolder
        .getContext()
        .getAuthentication();

在 Servlet 应用中，SecurityContextHolder 默认使用 ThreadLocal 策略，使同一请求线程中的代码可以读取当前用户。

ThreadLocal 只是默认策略，并不表示一个请求在所有情况下都始终使用同一线程。异步任务、线程池和响应式编程需要使用相应的上下文传播机制。

面试题：SecurityContext 为什么默认使用 ThreadLocal？

默认 Servlet 请求通常在线程中处理。使用 ThreadLocal 可以让同一线程中的代码直接获取当前认证信息，避免层层传递参数，并隔离不同请求线程的安全上下文。Spring Security 会在请求结束后清理上下文，避免线程复用造成身份泄露。

用户名密码登录流程

启用表单登录时，典型流程如下：

POST /login
→ UsernamePasswordAuthenticationFilter
→ 创建未认证 UsernamePasswordAuthenticationToken
→ AuthenticationManager
→ ProviderManager
→ DaoAuthenticationProvider
→ UserDetailsService 查询用户
→ PasswordEncoder 校验密码
→ 返回已认证 Authentication
→ 保存到 SecurityContext
→ 执行认证成功处理

本课程后续使用自定义 LoginController 调用 AuthenticationManager。这种情况下，登录请求不会经过 UsernamePasswordAuthenticationFilter，控制器负责生成 JWT；后续请求则由自定义 JWT 过滤器解析令牌并建立当前请求的 SecurityContext。

本章总结

组件	作用
`SecurityFilterChain`	定义请求需要执行的安全过滤器
`FilterChainProxy`	匹配并执行安全过滤器链
`Authentication`	表示认证请求或当前认证主体
`AuthenticationManager`	提供统一认证入口
`ProviderManager`	调度多个 `AuthenticationProvider`
`AuthenticationProvider`	执行具体认证逻辑
`UserDetailsService`	加载用户信息
`PasswordEncoder`	编码并校验密码
`SecurityContext`	保存当前认证对象
`SecurityContextHolder`	访问当前安全上下文

面试题：Authentication 与 UserDetails 有什么区别？

UserDetails 描述从用户数据源加载出的账号信息，例如用户名、密码摘要、账号状态和权限。

Authentication 既可以表示待认证凭证，也可以表示已经通过认证的当前主体。认证成功后，其 principal 通常是一个 UserDetails 实例。

前后端分离身份认证

image-007

本章采用以下方案：

用户名密码登录
→ AuthenticationManager 校验
→ 服务端签发 JWT
→ 客户端使用 Authorization 请求头携带 JWT
→ JWT 过滤器验签并建立 SecurityContext
→ Spring Security 执行访问授权

数据库表结构

下面的示例保留用户、角色、权限和菜单关系。角色表增加稳定的英文 role_key，用于生成 ROLE_ADMIN、ROLE_USER 等权限标识。

DROP TABLE IF EXISTS `t_menu_role`;
DROP TABLE IF EXISTS `t_role_permission`;
DROP TABLE IF EXISTS `t_menu`;
DROP TABLE IF EXISTS `t_permission`;
DROP TABLE IF EXISTS `t_user`;
DROP TABLE IF EXISTS `t_role`;

CREATE TABLE `t_menu` (
    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
    `name` VARCHAR(255) DEFAULT NULL COMMENT '菜单名称',
    `icon` VARCHAR(255) DEFAULT NULL COMMENT '菜单图标',
    `url` VARCHAR(255) DEFAULT NULL COMMENT '菜单 URL',
    `pid` BIGINT DEFAULT NULL COMMENT '父菜单 ID',
    `remark` VARCHAR(255) DEFAULT NULL COMMENT '备注',
    `level` INT DEFAULT NULL COMMENT '菜单层级',
    `is_link` TINYINT DEFAULT 0 COMMENT '是否可跳转',
    PRIMARY KEY (`id`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4;

CREATE TABLE `t_role` (
    `id` BIGINT NOT NULL AUTO_INCREMENT,
    `role_name` VARCHAR(255) NOT NULL,
    `role_key` VARCHAR(64) NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_role_key` (`role_key`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4;

CREATE TABLE `t_permission` (
    `id` BIGINT NOT NULL AUTO_INCREMENT,
    `permission_name` VARCHAR(255) NOT NULL,
    `permission_key` VARCHAR(255) NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_permission_key` (`permission_key`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4;

CREATE TABLE `t_user` (
    `id` BIGINT NOT NULL AUTO_INCREMENT,
    `username` VARCHAR(255) NOT NULL,
    `password` VARCHAR(255) NOT NULL,
    `role_id` BIGINT NOT NULL,
    `nickname` VARCHAR(255) DEFAULT NULL,
    `email` VARCHAR(255) DEFAULT NULL,
    `phone` VARCHAR(255) DEFAULT NULL,
    `freeze` TINYINT DEFAULT 0,
    `dept_id` BIGINT DEFAULT NULL,
    `remark` VARCHAR(255) DEFAULT NULL,
    `insert_time` DATETIME DEFAULT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_username` (`username`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4;

CREATE TABLE `t_role_permission` (
    `id` BIGINT NOT NULL AUTO_INCREMENT,
    `role_id` BIGINT NOT NULL,
    `permission_id` BIGINT NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_role_permission` (`role_id`, `permission_id`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4;

CREATE TABLE `t_menu_role` (
    `id` BIGINT NOT NULL AUTO_INCREMENT,
    `menu_id` BIGINT NOT NULL,
    `role_id` BIGINT NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_menu_role` (`menu_id`, `role_id`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4;

START TRANSACTION;

INSERT INTO `t_role` (`id`, `role_name`, `role_key`) VALUES
    (1, '系统管理员', 'ADMIN'),
    (2, '普通用户', 'USER');

INSERT INTO `t_permission` (`id`, `permission_name`, `permission_key`) VALUES
    (1, '查询', 'permission:query'),
    (2, '新增', 'permission:insert'),
    (3, '修改', 'permission:update'),
    (4, '删除', 'permission:delete');

INSERT INTO `t_role_permission` (`id`, `role_id`, `permission_id`) VALUES
    (50, 1, 1),
    (51, 1, 2),
    (52, 1, 3),
    (53, 1, 4),
    (61, 2, 1);

INSERT INTO `t_menu` (`id`, `name`, `icon`, `url`, `pid`, `remark`, `level`, `is_link`) VALUES
    (1, '系统设置', 'layui-icon-fire', NULL, -1, '', 1, 0),
    (2, '分类管理', 'layui-icon-name', 'category/list', 1, '', 2, 1),
    (3, '商品管理', 'layui-icon-service', NULL, -1, '', 1, 0),
    (4, '商品列表', 'layui-icon-rate', 'asset-info/list', 3, '', 2, 1);

INSERT INTO `t_menu_role` (`id`, `menu_id`, `role_id`) VALUES
    (1, 1, 1),
    (2, 2, 1),
    (3, 3, 1),
    (4, 4, 1),
    (5, 3, 2),
    (6, 4, 2);

INSERT INTO `t_user`
    (`id`, `username`, `password`, `role_id`, `nickname`, `insert_time`)
VALUES
    (1, 'admin',
     '$2a$10$t9BSP6hInmZm5RJocXVMdOLXzVXh4wgiBaYrM6iUslsrb.5z.eYce',
     1, '超级管理员', '2021-05-26 14:41:06'),
    (2, 'normal',
     '$2a$10$Mv1ruD0gHy9Uq73SbfH80ep1McuJNZiJCjM3BpxAJVr9pt34iwWlS',
     2, '普通用户', NULL);

COMMIT;

后端依赖

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>

    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
        <version>3.5.6</version>
    </dependency>

    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>

    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-api</artifactId>
        <version>0.12.5</version>
    </dependency>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-impl</artifactId>
        <version>0.12.5</version>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-jackson</artifactId>
        <version>0.12.5</version>
        <scope>runtime</scope>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

同一项目中的 JJWT 模块应使用相同版本。

前端请求拦截器

登录成功后，前端保存访问令牌，并在后续请求的 Authorization 请求头中携带 Bearer Token。

import axios from 'axios'

const service = axios.create({
  baseURL: 'http://localhost:8080',
  timeout: 5000
})

service.interceptors.request.use(
  config => {
    const token = localStorage.getItem('token')
    if (token) {
      config.headers.Authorization = `Bearer ${token}`
    }
    return config
  },
  error => Promise.reject(error)
)

service.interceptors.response.use(
  response => response.data,
  error => {
    const status = error.response?.status

    if (status === 401) {
      localStorage.removeItem('token')
      window.location.href = '/login'
    }

    return Promise.reject(error)
  }
)

export default service

HTTP 状态码应与业务响应体中的业务码分开处理：

401 Unauthorized 表示未认证、Token 无效或 Token 已过期。
403 Forbidden 表示已经认证，但没有访问权限。

Security 核心配置

import jakarta.servlet.http.HttpServletResponse;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.MediaType;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.authentication.configuration.AuthenticationConfiguration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;

import java.nio.charset.StandardCharsets;
import java.util.List;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    private static final String[] WHITE_LIST = {
            "/login",
            "/doc.html",
            "/webjars/**",
            "/favicon.ico",
            "/druid/**",
            "/public/**"
    };

    @Bean
    public SecurityFilterChain securityFilterChain(
            HttpSecurity http,
            JwtAuthenticationFilter jwtAuthenticationFilter) throws Exception {
        http
                .csrf(AbstractHttpConfigurer::disable)
                .cors(Customizer.withDefaults())
                .formLogin(AbstractHttpConfigurer::disable)
                .httpBasic(AbstractHttpConfigurer::disable)
                .sessionManagement(session -> session
                        .sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .exceptionHandling(exceptions -> exceptions
                        .authenticationEntryPoint((request, response, exception) -> {
                            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
                            response.setCharacterEncoding(StandardCharsets.UTF_8.name());
                            response.setContentType(MediaType.APPLICATION_JSON_VALUE);
                            response.getWriter().write(
                                    "{\"code\":401,\"msg\":\"未登录或令牌无效\"}"
                            );
                        })
                        .accessDeniedHandler((request, response, exception) -> {
                            response.setStatus(HttpServletResponse.SC_FORBIDDEN);
                            response.setCharacterEncoding(StandardCharsets.UTF_8.name());
                            response.setContentType(MediaType.APPLICATION_JSON_VALUE);
                            response.getWriter().write(
                                    "{\"code\":403,\"msg\":\"没有访问权限\"}"
                            );
                        }))
                .authorizeHttpRequests(authorize -> authorize
                        .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()
                        .requestMatchers(WHITE_LIST).permitAll()
                        .anyRequest().authenticated())
                .addFilterBefore(
                        jwtAuthenticationFilter,
                        UsernamePasswordAuthenticationFilter.class
                );

        return http.build();
    }

    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration configuration = new CorsConfiguration();
        configuration.setAllowedOrigins(List.of("http://localhost:5173"));
        configuration.setAllowedMethods(List.of(
                "GET", "POST", "PUT", "DELETE", "OPTIONS"
        ));
        configuration.setAllowedHeaders(List.of(
                HttpHeaders.AUTHORIZATION,
                HttpHeaders.CONTENT_TYPE
        ));
        configuration.setExposedHeaders(List.of(HttpHeaders.AUTHORIZATION));
        configuration.setAllowCredentials(false);

        UrlBasedCorsConfigurationSource source =
                new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", configuration);
        return source;
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }

    @Bean
    public AuthenticationManager authenticationManager(
            AuthenticationConfiguration configuration) throws Exception {
        return configuration.getAuthenticationManager();
    }
}

本示例的 Token 只通过 Authorization 请求头传递，且服务端不依赖浏览器 Cookie，因此关闭 CSRF。若改为 Cookie 自动携带凭证，应重新评估并启用合适的 CSRF 防护。

@EnableWebSecurity 用于导入 Spring Security 的 Servlet Web 安全配置。真正的请求规则由 SecurityFilterChain Bean 定义；Spring Boot Starter 负责相关自动配置和基础集成。

生产环境中的 CORS 允许源必须配置为真实前端域名，不应无条件放行任意来源。

生成实体与 Mapper

可使用 MyBatis Plus 逆向工程生成 User、Role、Permission、Menu 及其 Mapper。生成后仍需检查字段类型、表关联查询和空值处理，不能直接把逆向工程结果视为完整业务代码。

实现 UserDetails

import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.UserDetails;

import java.util.Collection;
import java.util.List;
import java.util.stream.Stream;

public class UserItem implements UserDetails {

    private final User user;
    private final List<String> permissions;
    private final List<GrantedAuthority> authorities;

    public UserItem(User user, String roleKey, List<String> permissions) {
        this.user = user;
        this.permissions = List.copyOf(permissions);
        this.authorities = Stream.concat(
                        Stream.of(new SimpleGrantedAuthority("ROLE_" + roleKey)),
                        permissions.stream().map(SimpleGrantedAuthority::new)
                )
                .map(GrantedAuthority.class::cast)
                .toList();
    }

    public User getUser() {
        return user;
    }

    public List<String> getPermissions() {
        return permissions;
    }

    @Override
    public Collection<? extends GrantedAuthority> getAuthorities() {
        return authorities;
    }

    @Override
    public String getPassword() {
        return user.getPassword();
    }

    @Override
    public String getUsername() {
        return user.getUsername();
    }

    @Override
    public boolean isAccountNonExpired() {
        return true;
    }

    @Override
    public boolean isAccountNonLocked() {
        return user.getFreeze() == null || user.getFreeze() == 0;
    }

    @Override
    public boolean isCredentialsNonExpired() {
        return true;
    }

    @Override
    public boolean isEnabled() {
        return true;
    }
}

hasRole('ADMIN') 会自动检查 ROLE_ADMIN，因此数据库中的稳定角色标识应保存为 ADMIN，构造权限时再添加 ROLE_ 前缀。

实现 UserDetailsService

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import lombok.RequiredArgsConstructor;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
@RequiredArgsConstructor
public class UserDetailsServiceImpl implements UserDetailsService {

    private final UserMapper userMapper;
    private final RoleMapper roleMapper;
    private final PermissionMapper permissionMapper;

    @Override
    public UserDetails loadUserByUsername(String username) {
        User user = userMapper.selectOne(
                new LambdaQueryWrapper<User>()
                        .eq(User::getUsername, username)
                        .last("LIMIT 1")
        );

        if (user == null) {
            throw new UsernameNotFoundException("账号不存在");
        }

        Role role = roleMapper.selectById(user.getRoleId());
        if (role == null) {
            throw new UsernameNotFoundException("账号未配置有效角色");
        }

        List<String> permissions = permissionMapper
                .selectPermissionListByRoleId(user.getRoleId())
                .stream()
                .map(Permission::getPermissionKey)
                .toList();

        return new UserItem(user, role.getRoleKey(), permissions);
    }
}

BCrypt 密码编码

BCryptPasswordEncoder 使用带随机盐的自适应单向哈希算法。相同明文每次编码得到的结果通常不同，但都可以通过 matches() 完成校验。

@Test
void shouldEncodeAndMatchPassword() {
    PasswordEncoder encoder = new BCryptPasswordEncoder();

    String encodedPassword = encoder.encode("123456");
    boolean matched = encoder.matches("123456", encodedPassword);

    System.out.println(encodedPassword);
    System.out.println(matched);
}

密码摘要不能被“解密”回明文。登录时应使用 matches(rawPassword, encodedPassword) 校验，而不是再次编码后比较字符串。

统一响应对象

public record Result<T>(int code, T data, String msg, long count) {

    public static <T> Result<T> ok(T data, String msg) {
        return new Result<>(200, data, msg, 0);
    }

    public static Result<Void> ok(String msg) {
        return new Result<>(200, null, msg, 0);
    }

    public static Result<Void> fail(int code, String msg) {
        return new Result<>(code, null, msg, 0);
    }

    public static Result<Void> fail(String msg) {
        return fail(500, msg);
    }
}

业务响应码应与 HTTP 状态码保持清晰语义。实际项目可使用 ResponseEntity 或全局异常处理器统一设置 HTTP 状态。

JWT 认证过滤器

自定义登录接口只负责签发 Token。后续每个受保护请求还需要解析 Token，并把认证结果放入当前请求的 SecurityContext。

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.JwtException;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpHeaders;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.context.SecurityContext;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.util.List;

@Component
@RequiredArgsConstructor
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private static final String BEARER_PREFIX = "Bearer ";

    private final JwtUtil jwtUtil;

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain) throws ServletException, IOException {
        String authorization = request.getHeader(HttpHeaders.AUTHORIZATION);

        if (authorization == null || !authorization.startsWith(BEARER_PREFIX)) {
            filterChain.doFilter(request, response);
            return;
        }

        String token = authorization.substring(BEARER_PREFIX.length()).trim();

        try {
            Claims claims = jwtUtil.parseToken(token);

            if (SecurityContextHolder.getContext().getAuthentication() == null) {
                List<?> values = claims.get("permissions", List.class);
                List<GrantedAuthority> authorities = values == null
                        ? List.of()
                        : values.stream()
                                .filter(String.class::isInstance)
                                .map(String.class::cast)
                                .map(SimpleGrantedAuthority::new)
                                .map(GrantedAuthority.class::cast)
                                .toList();

                UsernamePasswordAuthenticationToken authentication =
                        UsernamePasswordAuthenticationToken.authenticated(
                                claims.getSubject(),
                                null,
                                authorities
                        );

                SecurityContext context =
                        SecurityContextHolder.createEmptyContext();
                context.setAuthentication(authentication);
                SecurityContextHolder.setContext(context);
            }

            filterChain.doFilter(request, response);
        } catch (JwtException | IllegalArgumentException exception) {
            SecurityContextHolder.clearContext();
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.setContentType("application/json;charset=UTF-8");
            response.getWriter().write(
                    "{\"code\":401,\"msg\":\"令牌无效或已过期\"}"
            );
        }
    }
}

该示例直接使用 JWT 中的权限，优点是无需每次查询数据库，缺点是权限变更不会立即影响旧 Token。生产系统可以采用短时效 Token、令牌版本号、黑名单，或每次请求重新查询关键权限。

自定义登录接口

import lombok.RequiredArgsConstructor;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.BadCredentialsException;
import org.springframework.security.authentication.LockedException;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

@RestController
@RequiredArgsConstructor
public class LoginController {

    private final AuthenticationManager authenticationManager;
    private final MenuService menuService;
    private final JwtUtil jwtUtil;

    @PostMapping("/login")
    public Result<Map<String, Object>> login(
            @RequestBody LoginRequest request) {
        Authentication authentication = authenticationManager.authenticate(
                UsernamePasswordAuthenticationToken.unauthenticated(
                        request.username(),
                        request.password()
                )
        );

        UserItem userItem = (UserItem) authentication.getPrincipal();
        User user = userItem.getUser();

        List<String> authorities = authentication.getAuthorities()
                .stream()
                .map(GrantedAuthority::getAuthority)
                .toList();

        String token = jwtUtil.createToken(
                user.getId(),
                user.getUsername(),
                user.getRoleId(),
                authorities
        );

        List<Menu> menuList = menuService.listByRoleId(user.getRoleId());

        Map<String, Object> data = new HashMap<>();
        data.put("token", token);
        data.put("user", user);
        data.put("menuList", menuList);
        data.put("authorities", authorities);

        return Result.ok(data, "登录成功");
    }

    public record LoginRequest(String username, String password) {
    }
}

认证异常建议交给全局异常处理器统一转换：

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.authentication.BadCredentialsException;
import org.springframework.security.authentication.LockedException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BadCredentialsException.class)
    public ResponseEntity<Result<Void>> handleBadCredentials() {
        return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
                .body(Result.fail(401, "用户名或密码错误"));
    }

    @ExceptionHandler(LockedException.class)
    public ResponseEntity<Result<Void>> handleLocked() {
        return ResponseEntity.status(HttpStatus.FORBIDDEN)
                .body(Result.fail(403, "账号已被冻结"));
    }
}

不要把密码、密码摘要等敏感字段直接放入登录响应。可以创建专用用户响应对象，只返回前端实际需要的字段。

接口测试

登录成功后，响应中返回 Token、用户基本信息、菜单和权限集合。后续请求应在请求头中携带：

Authorization: Bearer <token>

image-008

权限控制实战

开启方法级授权

Spring Security 6 使用 @EnableMethodSecurity 开启方法级授权。

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;

@SpringBootApplication
@EnableMethodSecurity
public class SecurityApplication {

    public static void main(String[] args) {
        SpringApplication.run(SecurityApplication.class, args);
    }
}

spring-boot-starter-security 不会默认开启方法级授权，因此需要显式添加 @EnableMethodSecurity。

使用 `@PreAuthorize`

import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PermissionController {

    @PreAuthorize("hasRole('ADMIN')")
    @GetMapping("/admin")
    public String admin() {
        return "管理员接口访问成功";
    }

    @PreAuthorize("hasAuthority('permission:query')")
    @GetMapping("/user/list")
    public String userList() {
        return "用户列表接口访问成功";
    }

    @PreAuthorize("hasAnyRole('ADMIN', 'USER')")
    @GetMapping("/common")
    public String common() {
        return "通用接口访问成功";
    }
}

常用表达式如下：

表达式	含义
`hasRole('ADMIN')`	是否具有 `ROLE_ADMIN`
`hasAnyRole('ADMIN', 'USER')`	是否具有任一指定角色
`hasAuthority('permission:query')`	是否具有指定权限
`hasAnyAuthority('a', 'b')`	是否具有任一指定权限
`isAuthenticated()`	当前用户是否已经认证

面试题：@PreAuthorize 的执行原理是什么？

启用方法安全后，Spring Security 基于 Spring AOP 为受保护的 Spring Bean 创建代理。方法调用前，AuthorizationManagerBeforeMethodInterceptor 读取 @PreAuthorize 的 SpEL 表达式，并结合当前 Authentication 进行授权判断。

校验通过后才会调用目标方法；校验失败时会抛出 AccessDeniedException。在 HTTP 请求链中，该异常通常被转换为 403 Forbidden 响应。

关键注意事项

认证成功不等于拥有所有权限，认证和授权必须分别配置。
401 表示未通过认证，403 表示已经认证但权限不足。
JWT 过滤器必须先验证签名和有效期，再创建已认证的 Authentication。
不要信任客户端直接提交的角色或权限。
不要在 Token 或响应体中返回密码、密码摘要和密钥。
CORS、CSRF、XSS 属于不同安全问题，不能相互替代。
生产系统应使用 HTTPS，并配置合理的 Token 有效期、刷新和撤销机制。
方法级授权适合保护 Service 层关键操作，不能只依赖前端按钮是否显示。

JWT

Mon, 03 Aug 2026 01:56:11 GMT

JWT

JWT 概述

JWT（JSON Web Token）是一种紧凑、URL 安全的声明传输格式，常用于在不同系统之间传递身份与授权相关信息。

JWT 本身是一种令牌格式，并不等同于登录协议或单点登录方案。它可以作为认证、授权和单点登录流程中的一种令牌载体。

JWT 是否保密取决于具体封装方式。常见的三段式 JWT 属于 JWS，仅提供签名或消息认证码保护，载荷内容仍可被读取；只有使用 JWE 时，载荷才会被加密。

JWT 的常见应用场景

身份认证

用户登录成功后，服务端签发 JWT。客户端在后续请求中携带该令牌，服务端通过校验签名、有效期、签发者和受众等信息判断令牌是否可信。
访问授权

JWT 可以携带用户标识、角色、权限或作用域等声明。服务端完成令牌校验后，再根据这些声明判断当前用户是否可以访问目标资源。
系统间信息交换

发送方可以对 JWT 进行签名，使接收方能够验证数据是否被篡改以及令牌是否由可信签发方生成。若业务还要求内容保密，应使用 JWE 或其他加密通道。
单点登录

在统一身份认证体系中，认证中心可以签发 JWT，各业务系统根据约定验证令牌。JWT 只是单点登录方案中的一个组成部分，完整方案还需要处理令牌签发、刷新、吊销和信任关系。

JWT 的特点

优点

格式紧凑：适合放在 HTTP 请求头中传输。
跨语言：JWT 是标准化格式，各主流语言均有相应实现。
便于分布式验证：资源服务器可以在本地验证签名，减少对集中式会话存储的依赖。
支持声明扩展：除标准声明外，还可以添加业务自定义声明。

局限

已签发令牌不易立即撤销：通常需要缩短有效期、维护黑名单或使用令牌版本号等机制。
载荷可能泄露信息：JWS 的载荷只是 Base64URL 编码，并未加密。
令牌体积可能较大：声明过多时，每次请求都会增加网络开销。
权限可能过期：若把权限直接写入长时效令牌，数据库权限变更不会立即反映到旧令牌中。

JWT 的结构

常见的签名 JWT 由三部分组成，并使用英文句点连接：

Header.Payload.Signature

image-001

Header

Header 是一个 JSON 对象，通常包含以下字段：

typ：令牌类型，通常为 JWT。
alg：签名或消息认证码算法，例如 HS256、RS256。

示例：

{
  "typ": "JWT",
  "alg": "HS256"
}

Header 会经过 Base64URL 编码，形成令牌的第一部分。

Payload

Payload 用于存放声明（Claim）。JWT 规范定义了七个注册声明名称，这些字段均为可选字段。

声明	英文名称	作用
`iss`	Issuer	标识令牌签发者
`sub`	Subject	标识令牌主题，通常代表用户或主体
`aud`	Audience	标识令牌预期接收方
`exp`	Expiration Time	标识令牌过期时间
`nbf`	Not Before	标识令牌在何时之前不可用
`iat`	Issued At	标识令牌签发时间
`jti`	JWT ID	标识令牌的唯一编号

除注册声明外，还可以添加业务自定义声明：

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true
}

不要在未加密的 JWT Payload 中存放密码、银行卡号、身份证号、密钥等敏感信息。任何获得令牌的人都可以解码并读取 Header 和 Payload。

Signature

Signature 用于校验 Header 和 Payload 是否被篡改，并验证令牌是否由持有相应密钥的一方签发。

以 HS256 为例，签名计算过程可以表示为：

HMACSHA256(
    base64UrlEncode(header) + "." + base64UrlEncode(payload),
    secret
)

使用 HMAC 时，签发方与验证方共享同一个密钥；使用 RSA 或 ECDSA 时，签发方使用私钥签名，验证方使用公钥验签。

签名只能保证完整性和来源可信度，不能隐藏 Payload 内容。

Base64URL

Base64URL 是适合 URL 和 HTTP 头部传输的 Base64 变体。

与普通 Base64 相比，它主要进行以下处理：

将 + 替换为 -。
将 / 替换为 _。
省略末尾的 = 填充字符。

Base64URL 是编码方式，不是加密算法。

使用 JJWT 封装工具类

下面示例基于 JJWT 0.12.x。配置项中的密钥使用 Base64 编码，并且解码后至少应满足所选 HMAC 算法的密钥长度要求。

配置示例

jwt:
  secret: ${JWT_SECRET}
  expire-ms: 86400000

JWT_SECRET 不应直接提交到代码仓库，可通过环境变量或密钥管理服务注入。

JWT 工具类

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.io.Decoders;
import io.jsonwebtoken.security.Keys;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import javax.crypto.SecretKey;
import java.util.Date;
import java.util.List;

@Component
public class JwtUtil {

    private final SecretKey key;
    private final long expireMs;

    public JwtUtil(
            @Value("${jwt.secret}") String secret,
            @Value("${jwt.expire-ms}") long expireMs) {
        byte[] keyBytes = Decoders.BASE64.decode(secret);
        this.key = Keys.hmacShaKeyFor(keyBytes);
        this.expireMs = expireMs;
    }

    public String createToken(
            Long userId,
            String username,
            Long roleId,
            List<String> permissions) {
        Date now = new Date();
        Date expiration = new Date(now.getTime() + expireMs);

        return Jwts.builder()
                .subject(username)
                .claim("userId", userId)
                .claim("roleId", roleId)
                .claim("permissions", permissions)
                .issuedAt(now)
                .expiration(expiration)
                .signWith(key)
                .compact();
    }

    public Claims parseToken(String token) {
        return Jwts.parser()
                .verifyWith(key)
                .build()
                .parseSignedClaims(token)
                .getPayload();
    }

    public boolean isExpired(Claims claims) {
        Date expiration = claims.getExpiration();
        return expiration != null && expiration.before(new Date());
    }
}

signWith(key) 会根据密钥类型和长度选择兼容的签名算法。若系统要求固定算法，应在签发和验证两端统一配置，并限制只接受预期算法。

Claims 对象

Claims 表示 JWT 中的声明集合。它继承了 Map<String, Object> 的键值存取能力，同时提供了读取标准声明的专用方法。

常用方法如下：

String subject = claims.getSubject();
Date issuedAt = claims.getIssuedAt();
Date expiration = claims.getExpiration();
String issuer = claims.getIssuer();

读取自定义声明时，可以指定目标类型：

Long userId = claims.get("userId", Long.class);
Long roleId = claims.get("roleId", Long.class);

对于泛型集合，由于 Java 类型擦除，直接读取时通常只能得到原始 List。可以在业务层逐项转换，或使用自定义反序列化方案。

@SuppressWarnings("unchecked")
List<String> permissions = claims.get("permissions", List.class);

测试令牌的创建与解析

下面的测试在同一个测试方法中创建并解析令牌，避免使用已经过期或被换行破坏的硬编码令牌。

import io.jsonwebtoken.Claims;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

import java.util.List;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;

@SpringBootTest
class JwtUtilTests {

    @Autowired
    private JwtUtil jwtUtil;

    @Test
    void shouldCreateAndParseToken() {
        List<String> permissions = List.of(
                "permission:query",
                "permission:insert",
                "permission:update",
                "permission:delete",
                "permission:check"
        );

        String token = jwtUtil.createToken(130L, "tom", 3L, permissions);
        Claims claims = jwtUtil.parseToken(token);

        assertEquals("tom", claims.getSubject());
        assertEquals(130L, claims.get("userId", Long.class));
        assertEquals(3L, claims.get("roleId", Long.class));
        assertFalse(jwtUtil.isExpired(claims));

        @SuppressWarnings("unchecked")
        List<String> parsedPermissions = claims.get("permissions", List.class);
        assertEquals(permissions, parsedPermissions);
    }
}

使用注意事项

服务端必须验证签名，不能只解码 Payload。
应校验 exp，并根据业务需要校验 iss、aud、nbf 等声明。
不要接受客户端自行指定的任意算法，应限制允许的算法和令牌类型。
HMAC 密钥必须足够长且随机，不能使用简单口令代替密钥。
访问令牌应设置较短有效期；需要长期登录时，应配合刷新令牌机制。
全程使用 HTTPS，避免令牌在传输过程中被窃取。
客户端存储方案应根据威胁模型选择，并重点防范 XSS、CSRF 和令牌泄露。

Coze 平台架构、典型应用案例及优势与适用场景

Sat, 01 Aug 2026 11:59:38 GMT

Coze 平台架构、典型应用案例及优势与适用场景

Coze 平台架构

两种平台形态

Coze 官网版（云端版）

Coze 官网版属于官方托管的在线服务。用户通过浏览器访问平台，直接使用官方提供的模型、应用能力、在线运行环境和相关服务，不需要自行安装程序或维护服务器。

官网版的主要特点包括：

注册后即可在线使用；
平台环境由官方统一维护；
适合快速体验、课程教学和原型验证；
可以直接使用官网提供的功能与生态资源；
无需自行处理系统升级、基础设施和日常运维；
实际可用功能、资源额度和发布能力以官网当前版本为准。

Coze 官网当前将自身描述为面向职场任务的 AI 产品，并提供 AI 应用、工作产物生成、长期任务以及相关开发能力。

Coze Studio（开源版）

Coze Studio 是 Coze 平台核心引擎的开源版本。开发者可以将其部署到本地计算机、实验室服务器或企业内网中，构建自主可控的 AI Agent 开发平台。

开源版的主要特点包括：

支持私有化部署；
数据和运行环境可由部署方管理；
可以接入自有模型和业务服务；
支持根据源代码进行功能修改；
适合教学研究、企业内网和二次开发；
需要具备一定的部署、配置和运维能力。

Coze Studio 官方说明其提供 Prompt、RAG、Plugin 和 Workflow 等 AI Agent 开发核心技术，并采用可视化方式支持智能体、应用和工作流的开发、调试与部署。

官网版与开源版对比

对比维度	Coze 官网版（云端版）	Coze Studio（开源版）
使用方式	浏览器在线使用	本地或服务器部署
环境维护	官方统一维护	用户自行维护
上手难度	较低，注册后即可使用	较高，需要部署和配置
数据存放	由云端平台按服务规则处理	可由部署方在自有环境中管理
功能获取	直接使用官网当前提供的功能	使用开源功能，并可自行扩展
模型配置	以官网支持范围和平台规则为准	可根据部署环境配置支持的模型
插件与服务	可使用官网生态和在线服务	需配置开源插件或接入自有 API
二次开发	主要通过平台配置和开放接口	可修改源代码并深度定制
运维成本	较低	较高
适用对象	初学者、个人用户、快速验证团队	技术团队、实验室、企业私有化项目
主要优势	开箱即用、使用便捷	自主可控、便于定制
主要限制	受平台功能、额度和服务规则影响	需要自行解决部署、资源和运维问题

两种形态具有相近的 AI Agent 开发理念，但在具体功能、官方生态、资源额度、发布渠道和运行维护方式上可能存在差异，使用时应以对应版本的最新官方说明为准。

平台能力架构

从 AI 应用构建过程来看，Coze 可以划分为五个相互协作的能力层。

flowchart TB
    A[用户与业务系统]

    B[应用与交互层<br/>智能体 Agent / AI 应用 App / 对话界面 / API]
    C[智能与编排层<br/>大语言模型 / 提示词 / 工作流]
    D[能力扩展层<br/>插件 / 工具 / 第三方 API]
    E[知识与数据层<br/>知识库 / 数据库 / 长期记忆]
    F[开发与发布支撑<br/>可视化工作台 / 调试 / 发布 / 管理]

    A --> B
    B --> C
    C --> D
    C --> E
    F -.支撑.-> B
    F -.支撑.-> C
    F -.支撑.-> D
    F -.支撑.-> E

应用与交互层

应用与交互层直接面向最终用户，负责承接用户需求并展示 AI 处理结果。

该层主要包括：

智能体 Agent：以自然语言对话为主要交互方式，可以理解任务、选择工具并返回结果；
AI 应用 App：围绕特定业务需求构建，通常具有明确的输入、输出和可视化界面；
对话界面：用户与智能体进行问答和任务交互的入口；
API 与 SDK：用于将 Coze 的智能体或工作流接入网站、管理系统和其他业务软件。

智能体更适合开放式对话和动态任务，AI 应用更适合业务目标明确、流程相对固定的功能场景。

智能与编排层

智能与编排层是平台的核心，负责理解用户意图、组织业务逻辑和生成最终结果。

该层主要包括：

大语言模型；
提示词；
智能体决策逻辑；
工作流。

大语言模型负责理解、推理和生成；提示词规定模型的角色与行为；工作流负责将复杂任务拆分为多个步骤，并按照确定的逻辑依次执行。

能力扩展层

能力扩展层通过插件和工具连接外部世界，使大模型从“只能生成内容”扩展为“能够获取信息和执行操作”。

例如：

调用搜索工具获取实时新闻；
调用天气服务查询天气；
调用地图服务规划路线；
调用图像生成服务制作图片；
调用企业 API 查询订单或客户信息；
调用邮件、日程等服务完成办公任务。

知识与数据层

知识与数据层为智能体提供专业知识、业务数据和长期状态。

主要包括：

知识库：保存企业文档、产品手册、课程资料和行业报告，为智能体提供检索增强生成能力；
数据库：保存结构化业务数据；
长期记忆：记录用户偏好、历史任务和交互信息，使智能体能够在后续会话中继续使用这些信息。

开发与发布支撑

开发与发布能力贯穿整个应用构建过程，主要包括：

可视化工作台；
拖拽式工作流画布；
实时预览和调试；
应用配置和资源管理；
智能体与应用发布；
API 和 SDK 集成。

该层降低了开发门槛，使非专业开发人员也可以参与 AI 应用的设计和迭代。

Coze 平台核心组件

大语言模型

大语言模型是 Coze 平台的智能核心，主要负责：

理解自然语言；
识别用户意图；
生成文本内容；
进行逻辑推理；
判断是否调用插件或工作流；
整合知识库和工具返回的结果。

模型能力会直接影响智能体的理解准确率、回答质量和工具调用稳定性。

智能体 Agent

智能体是能够通过自然语言与用户交互，并根据任务需要调用知识库、插件或工作流的 AI 项目。

一个完整的智能体通常由以下内容组成：

角色和身份；
系统提示词；
大语言模型；
对话上下文；
知识库；
插件和工具；
工作流；
数据库与记忆；
开场白和推荐问题。

智能体不是简单的问答机器人。它可以根据用户目标选择不同能力，完成“理解—决策—执行—反馈”的任务闭环。

AI 应用 App

AI 应用是围绕特定业务需求构建的独立项目，具有较明确的输入、输出和处理逻辑。

典型 AI 应用包括：

AI 搜索；
翻译工具；
报告生成器；
数据格式转换工具；
饮食记录工具；
内容审核工具。

与智能体相比，AI 应用的功能边界通常更加明确，适合提供标准化服务。

提示词 Prompt

提示词用于定义智能体的身份、任务目标、工作步骤、回复风格和行为边界，是控制智能体表现的重要组件。

一份结构清晰的提示词通常包括：

角色定位：智能体是谁；
任务目标：需要完成什么；
工作流程：按照什么步骤处理；
可用资源：可以调用哪些知识库、插件和工作流；
输出规范：语言、格式、长度和结构要求；
行为约束：禁止事项和异常处理方式。

提示词能够约束模型行为，但不能替代程序权限控制、内容审核和安全校验。

工作流 Workflow

工作流用于将复杂任务拆分为多个可执行节点，并通过节点之间的连接组织数据流和执行顺序。

常见节点包括：

大语言模型节点；
插件节点；
知识库检索节点；
代码节点；
条件判断节点；
循环节点；
数据处理节点；
输入和输出节点。

工作流适合执行流程明确、步骤较多、稳定性要求较高的任务，例如行业报告生成、订单处理、数据分析和内容审核。

插件与工具

工具是完成某一具体操作的能力，例如查询天气；插件则是一个或多个相关工具组成的能力集合。

插件的主要作用是：

获取大模型知识范围之外的实时信息；
调用第三方服务；
连接企业内部业务系统；
执行查询、计算、生成和通知等操作。

官方说明指出，插件工具能够扩展大语言模型的能力，使其连接外部世界。

知识库与 RAG

知识库用于保存企业内部资料、课程文件、产品手册、行业文档和网页内容。

当用户提出问题时，系统可以先从知识库中检索相关内容，再将检索结果交给大语言模型生成回答。这种“先检索、再生成”的方式属于 RAG，即检索增强生成。

知识库的主要价值包括：

补充模型不了解的企业私有知识；
提高专业领域回答的准确性；
减少无依据回答；
让智能体依据指定资料回答问题；
降低用户查找大量文档的时间成本。

RAG 能够降低模型幻觉，但不能完全消除错误，重要内容仍需要依据引用和人工复核。

数据库与长期记忆

数据库用于保存结构化信息，长期记忆用于保存用户偏好、历史交互和任务状态。

例如，阅读助手可以记录：

书名；
阅读页码；
阅读时间；
用户笔记；
兴趣偏好。

当用户再次对话时，智能体可以查询历史数据并继续提供服务，从而由一次性问答工具转变为长期个人助手。

调试与发布

Coze 提供可视化预览和调试能力。开发者可以在发布前测试：

提示词是否清晰；
回答风格是否符合要求；
插件能否正常调用；
工作流是否按照预期执行；
知识库检索结果是否准确；
异常情况是否得到合理处理。

测试完成后，可将智能体或应用发布并供用户使用，也可以通过 API 或 SDK 接入现有系统。

核心组件协作关系

核心组件	主要作用	典型协作对象
大语言模型	理解、推理、生成和决策	提示词、智能体、工作流
智能体	接收用户任务并组织执行	模型、知识库、插件、工作流、记忆
AI 应用	封装特定业务功能	模型、工作流、API
提示词	规定角色、任务和输出边界	模型、智能体
工作流	编排多步骤业务流程	模型、插件、知识库、代码
插件与工具	获取实时信息或执行外部操作	智能体、工作流、第三方系统
知识库	提供私有知识和检索依据	智能体、模型
数据库与记忆	保存业务数据和长期状态	智能体、用户、应用
API 与 SDK	将平台能力接入其他系统	网站、企业系统、移动应用

Coze 平台典型应用案例

夸夸机器人

业务需求

通过对话识别用户表达中的积极信息，并以幽默、真诚和正向的语言进行赞美。

使用组件

智能体；
大语言模型；
系统提示词；
开场白和推荐问题；
可选搜索插件。

实现效果

通过提示词设定“夸夸大师”的角色、语言风格和回答边界，使机器人始终提供积极反馈。该案例适合用于展示智能体创建、提示词编写、调试和发布等基础能力。

智能客服

业务需求

企业需要持续处理大量重复咨询，例如产品功能、售后规则、订单状态和常见故障。

使用组件

智能体；
企业知识库；
搜索或订单查询插件；
工作流；
API 与 SDK。

实现效果

智能客服可以全天候回答常见问题。当问题涉及企业制度或产品参数时，从知识库检索答案；涉及订单状态时，调用业务系统 API；遇到复杂问题时，可通过工作流转交人工客服。

企业知识问答助手

业务需求

企业员工需要从员工手册、产品文档、项目资料和规章制度中快速查找信息。

使用组件

智能体；
知识库；
RAG；
权限控制；
对话界面。

实现效果

企业将内部文档导入知识库，员工可以直接提问“差旅费报销标准是什么”或“产品 A 的核心参数有哪些”。智能体检索相关资料后生成答案，减少人工查找文件和重复咨询的成本。

AI 新闻播音员

业务需求

用户希望定期获取特定领域的最新新闻，并将多个信息源整理成简洁摘要。

使用组件

智能体；
新闻搜索插件；
工作流；
大语言模型；
定时任务或外部触发能力。

实现效果

系统调用新闻搜索插件获取实时资讯，通过工作流进行筛选、去重和分类，再由大语言模型生成播报稿。该案例体现了插件、工作流和文本生成能力的结合。

行业研究报告生成

业务需求

传统行业研究报告需要经历资料搜索、数据整理、大纲设计、内容撰写和格式检查等多个步骤，耗时较长。

使用组件

工作流；
搜索插件；
知识库；
大语言模型；
条件判断和代码节点；
文档输出工具。

实现效果

工作流可将报告生成划分为：

接收研究主题；
搜集公开资料；
检索内部知识库；
生成报告大纲；
分章节撰写；
检查逻辑和格式；
输出最终报告。

该案例适合展示 Coze 对多步骤、复杂知识工作的自动化能力。

汽车品牌智能销售系统

业务需求

汽车销售人员需要根据用户浏览行为、咨询内容和车型偏好判断购买意向，并提供个性化推荐。

使用组件

智能体；
客户数据库；
企业知识库；
推荐工作流；
CRM 系统插件。

实现效果

系统分析客户咨询关键词、车型偏好和历史行为，形成用户画像，并向销售人员提供推荐车型、沟通重点和参考话术。

电商订单处理自动化

业务需求

非标准化订单常以自然语言描述产品规格，人工整理容易出现遗漏和录入错误。

使用组件

工作流；
大语言模型；
条件判断；
数据处理节点；
订单系统和供应链插件。

实现效果

系统自动读取订单描述，提取材质、尺寸、数量和定制要求，将非结构化文本转化为结构化订单或 BOM 清单，再传递给供应链系统，从而减少人工录入并提高订单处理效率。

个性化阅读助手

业务需求

用户希望长期记录阅读进度、读书笔记和兴趣偏好，并在后续对话中快速恢复历史信息。

使用组件

智能体；
数据库；
长期记忆；
提示词；
推荐工作流。

实现效果

用户输入阅读书目、页码和笔记后，系统将信息保存到数据库。用户下次询问时，智能体可以恢复阅读进度，并根据历史笔记提供内容回顾或延伸阅读建议。

英语外教

业务需求

学习者需要随时进行口语练习、语法纠错和情景对话。

使用组件

智能体；
大语言模型；
角色提示词；
语音工具；
学习记录数据库。

实现效果

智能体模拟英语教师，与用户开展不同场景的英语对话，并根据用户水平调整难度。系统还可以保存常见错误和学习进度，提供个性化练习建议。

内容创作助手

业务需求

运营人员需要快速完成文案构思、内容改写、标题生成和多平台风格转换。

使用组件

AI 应用；
大语言模型；
提示词模板；
工作流；
知识库。

实现效果

用户输入主题、受众和内容要求后，系统按照预设工作流生成大纲、初稿、标题和不同平台版本，并根据品牌知识库保持统一的表达风格。

Coze 平台优势

开发门槛低

Coze 提供可视化开发环境。用户可以通过表单配置、自然语言提示词和拖拽节点完成应用构建，不必从底层编写完整的大模型调用、工具调度和流程控制代码。

这使产品、运营、教师和业务人员也能够参与 AI 应用设计。

工作流编排灵活

工作流能够将复杂任务拆分为多个节点，并支持条件判断、循环、代码处理、模型调用和插件调用。

与单次模型问答相比，工作流具有以下优势：

业务步骤清晰；
输入输出明确；
执行过程可观察；
复杂逻辑可控制；
流程可以重复使用。

插件扩展能力强

大语言模型自身不能直接获取所有实时信息，也不能直接操作企业系统。插件使智能体能够连接搜索、天气、地图、邮件、图像生成以及企业内部 API。

官方开源文档将插件分为官方内置插件、自定义插件和商业版插件等类型。

支持企业专属知识库

知识库使智能体能够基于企业自己的资料回答问题，解决通用模型不了解内部业务知识的问题。

其价值主要体现在：

统一企业知识入口；
减少重复咨询；
提升专业回答准确性；
缩短员工查找资料的时间；
支持产品、制度和技术文档问答。

支持数据库和长期记忆

Coze 可以将对话中的关键信息转化为结构化数据，并在后续任务中重新使用。

这使智能体能够：

记住用户偏好；
跟踪任务进度；
保存历史状态；
提供连续服务；
实现个性化推荐。

支持快速调试和迭代

平台提供实时预览和调试区域。开发者可以在发布前反复测试提示词、插件、知识库和工作流，并根据结果及时修改配置。

这种开发方式缩短了从创意验证到应用上线的周期。

支持多种集成方式

Coze 的智能体和应用可以独立运行，也可以通过 API 和 SDK 接入现有网站、企业管理系统和其他软件。

这使平台既适合快速制作独立 AI 应用，也适合为已有系统增加 AI 能力。

支持私有化部署和二次开发

Coze Studio 是 Coze 核心能力的开源实现，可在本地或企业服务器中部署，并允许开发团队基于源代码进行定制。

该能力适合：

对数据安全要求较高的企业；
需要在内网运行的单位；
需要接入私有系统的项目；
需要修改平台功能的研发团队。

需要注意，私有化部署仍然需要进行账户权限、接口安全、数据隔离和运行环境等方面的安全配置。

Coze 平台使用流程

Coze 官网版（云端版）

创建智能体

登录扣子平台，在主界面找到并点击创建按钮，即可正式开启智能体的个性化搭建流程。

coze.cn

扣子 - AI Agent智能办公平台 - 扣子用AI重塑生产力与工作效率

扣子(Coze)是基于AI Agent的智能办公平台，提供AI写作、PPT生成、网页开发与AI设计等一体化生产力工具，扣子致力于为用户与企业提供高效、安全、便捷的智能办公新体验。

https://www.coze.cn/space

image-20260731212330133

image-20260731212428935

为智能体起一个独特的名字，并简洁描述其功能定位与服务场景，明确其角色价值。

支持系统自动生成风格多样的头像，也可上传品牌 Logo 或个人设计的专属形象，让智能体拥有独一无二的视觉标识。

image-20260731212856892

确认基础信息无误后点击确认，系统将跳转至智能体编排核心页面，接下来即可进行逻辑配置与功能开发。

image-20260731213502911

编写提示词

配置智能体的核心是编写提示词（Prompt），也就是为它定义专属的人设与底层回复逻辑。一个精准、清晰的提示词，能让智能体的行为模式与输出结果更贴合我们的预期，从而高效完成特定任务。

image-20260731213128748

添加知识库

基础模型的原生能力不足以支撑政务查下业务场景的复杂需求，需要为智能体主动添加技能和知识库。

这一步能有效突破模型的知识截止时间与固有能力边界，让智能体具备实时信息获取、工具调用等进阶能力，解决单纯依赖大模型无法完成的实际问题。

这里选择添加知识库

image-20260731213409825

此时我们还没有知识库，需要新创建一个知识库

image-20260731213424043

这里我们选择创建扣子知识库，并选择文本格式，填写相关名称和描述

image-20260731213553673

选择本地文档的导入类型并更改图标，点击创建并导入即可创建一个新的知识库

image-20260731213855779

随后，我们需要上传相关文件，等待解析完成后，点击下一步

image-20260731214105845

这里我们选择默认设置，并下一步

image-20260731214931354

这里可以看到分段预览结果，确认无误后点击下一步

image-20260731215052516

这里会提交给服务器处理，无需等待，点击确认即可

image-20260731215156643

如果有需要可以在这一页添加新的内容，这里我们选择添加到智能体

image-20260731215235143

添加工作流

这里选择添加工作流

image-20260731221716379

因为我们还没有工作流，需要创建一个，这里我们选择创建对话流

image-20260731221751120

这里需要添加对话流的名称和描述

image-20260731221919605

这里通过可视化的操作完成对话流的搭建

先创建知识库检索节点，并用鼠标将开始节点和知识库检索节点连接在一起

image-20260731225651341

点击知识库检索节点，从输入变量中选择开始节点的 USER_INPUT，并配置已有的知识库

image-20260731225719512

image-20260731225844902

添加大模型节点，并将知识库检索节点和知识库检索节点，结束节点连接在一起

image-20260731225746853

大模型节点需要两个输入变量，一个是开始的 USER_INPUT，一个是知识库检索的 outputList

image-20260731225935956

此节点还需要配置系统提示词和用户提示词

系统提示词和用户提示词需要通过 {{}}引用输入变量，例如

用户问题：
{{input1}}

知识库检索结果：
{{input}}

请根据以上知识库检索结果回答用户问题。

image-20260731230124276

结束节点的输出变量选择大模型节点的 output，回答内容添加 {{output}}

image-20260731230403762

点击试运行进行测试

image-20260731230608256

image-20260731230721718

点击右上角发布对话流，并添加到当前智能体中

image-20260731230742354

调试智能体

在右侧的预览与调试区域，像和真人聊天一样与你的机器人对话。通过实际的交互流程，全方位测试它的回答准确度、逻辑连贯性以及是否符合你的业务预期。

image-20260731230929929

发布智能体

完成所有测试与参数配置后，只需点击“发布”按钮，即可将智能体正式部署。系统将自动处理后端配置，让你的智能体在目标渠道上线，开始为用户提供服务。

image-20260731220032268

这里我们选择确认

image-20260731220147129

这里需要选择发布渠道，默认会选择扣子商店，默认即可

image-20260731220240325

等待审核过后，即可发布成功，发布成功后即可在作品社区中搜索到

image-20260731220355426

image-20260731231646282

Coze Studio（开源版）

安装环境

首先需要安装 Docker Desktop

docker.com

Docker Desktop: The #1 Containerization Tool for Developers | Docker

Docker Desktop is collaborative containerization software for developers. Get started and download Docker Desktop today on Mac, Windows, or Linux.

https://www.docker.com/products/docker-desktop/

然后从 Github 下载 Coze Studio 的源码

github.com

GitHub - coze-dev/coze-studio: An AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.

An AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation. - coze-dev/coze-studio

https://github.com/coze-dev/coze-studio

image-20260801142653864

全部解压后，在 coze-studio\docker 下打开终端，输入

docker compose up -d

用于启动服务

image-20260801142828297

注册账号，访问 http://localhost:8888/sign 输入用户名、密码点击注册按钮，然后会来到此页面

image-20260801142946562

配置模型

获取向量模型

首先下载 ollama 用于调用本地模型，下载链接为

ollama.com

Download Ollama on Windows

Download Ollama for Windows

https://ollama.com/download/windows

然后打开终端，输入

ollama pull bge-m3:567m-fp16

此命令用于下载本地模型，下载完成后查看：

ollama list

获取语言模型

首先登录阿里云百炼控制台

bailian.console.aliyun.com

大模型服务平台百炼控制台

百炼控制台是阿里云大模型服务平台，提供AI模型训练、部署、推理一站式服务，支持多种大模型框架，助力企业快速构建AI应用。

https://bailian.console.aliyun.com/

然后申请一个 API Key

bailian.console.aliyun.com

大模型服务平台百炼控制台

百炼控制台是阿里云大模型服务平台，提供AI模型训练、部署、推理一站式服务，支持多种大模型框架，助力企业快速构建AI应用。

https://bailian.console.aliyun.com/cn-beijing?tab=model#/api-key

image-20260801141929926

image-20260801142006022

复制密钥和请求地址

image-20260801143218724

访问 Coze Studio 管理后台，下滑选择 Qwen 家族

image-20260801143323026

填写模型显示名称和模型类型，并粘贴密钥和地址，然后点击保存

image-20260801143420100

随后填写如下信息，然后往下滑，点击保存配置

image-20260801143703609

它提示我们重启服务器，我们在 coze-studio\docker 下打开终端，输入

docker compose restart

此时相关服务会重启启动

随后配置过程与云端版类似，但别忘了修改模型

image-20260801145920160

Coze 平台适用场景

教育教学

适合构建：

AI 助教；
英语口语陪练；
课程资料问答助手；
作业辅导助手；
学习计划工具；
教学内容生成应用。

主要使用智能体、知识库、提示词和学习记录数据库。

企业客服

适合构建：

售前咨询机器人；
售后服务助手；
订单查询助手；
产品使用指导；
人工客服辅助系统。

主要使用知识库、业务插件、工作流和 API。

企业知识管理

适合构建：

员工制度问答；
产品文档助手；
技术支持知识库；
项目资料检索；
新员工培训助手。

主要使用知识库、RAG、权限管理和对话界面。

内容创作

适合构建：

文案生成；
标题生成；
内容改写；
报告撰写；
脚本生成；
品牌内容助手。

主要使用大语言模型、提示词、工作流和品牌知识库。

办公自动化

适合构建：

会议内容整理；
邮件生成与分类；
表格数据处理；
报告自动生成；
任务通知；
日常事务助手。

主要使用工作流、插件、代码节点和数据库。

电商与运营

适合构建：

商品描述生成；
用户评论分析；
智能导购；
订单信息提取；
客服自动化；
营销活动内容生成。

主要使用智能体、工作流、商品知识库和电商系统插件。

市场营销与销售

适合构建：

客户画像分析；
销售话术推荐；
市场调研；
竞品信息整理；
线索分类；
营销内容生成。

主要使用数据库、搜索插件、工作流和大语言模型。

个人效率工具

适合构建：

个人助理；
阅读记录助手；
旅行规划；
日程管理；
信息摘要；
个性化学习助手。

主要使用智能体、插件、长期记忆和数据库。

场景选择参考

需求特征	推荐使用的 Coze 能力
需要通过聊天完成任务	智能体
需要固定输入、输出和界面	AI 应用
需要执行多个确定步骤	工作流
需要查询实时信息	插件与工具
需要依据企业内部资料回答	知识库与 RAG
需要记住用户偏好和历史状态	数据库与长期记忆
需要接入现有业务系统	API、SDK、自定义插件
需要本地保存数据或深度定制	Coze Studio 私有化部署
需要快速在线体验和完成原型	Coze 官网版
需要研究开源实现或修改平台功能	Coze Studio
没有部署运维条件	Coze 官网版
需要在企业内网长期运行	Coze Studio

官网版与开源版的选择建议

适合选择 Coze 官网版的情况

第一次学习 Coze，希望快速熟悉核心功能；
用于课堂演示、课程实验和个人练习；
需要尽快制作可运行的原型；
不具备服务器部署和系统运维条件；
希望直接使用官网提供的在线能力和生态资源；
项目暂时不涉及高度敏感的内部数据。

适合选择 Coze Studio 的情况

需要在实验室、学校或企业服务器中部署；
需要控制数据存放位置和运行环境；
需要接入内部数据库、模型或业务系统；
需要修改平台源代码；
需要研究智能体、工作流、RAG 和插件的实现方式；
团队具备 Docker、服务器和软件开发能力。

总结

Coze 的核心价值并不只是提供大语言模型对话，而是把模型、提示词、智能体、工作流、插件、知识库、数据库和发布能力整合为一个完整的低代码 AI 应用开发平台。

从产品能力架构来看：

大语言模型提供理解、推理和生成能力；
智能体负责接收用户目标并组织任务执行；
工作流负责稳定地编排复杂业务逻辑；
插件和工具负责连接外部服务；
知识库为应用提供专业和私有知识；
数据库与长期记忆负责保存业务状态；
可视化工作台、调试和发布能力支撑应用开发全过程。

在使用形态上，Coze 官网版和 Coze Studio 分别满足不同需求：

Coze 官网版侧重开箱即用，适合初学者、课程教学、个人体验和快速原型验证；
Coze Studio侧重私有化和自主扩展，适合技术研究、企业内网部署和深度二次开发。

资料来源

巡云论坛部署文档

Fri, 31 Jul 2026 11:24:33 GMT

巡云论坛部署文档

在 Windows 下打包，发送到服务器上运行

Windows 环境搭建

安装 java

采用 jvms 管理 java 版本，如果已经有 java 8 请忽略

下载 jvms

访问

github.com

Releases · ystyle/jvms

JDK Version Manager (JVMS) for Windows. Contribute to ystyle/jvms development by creating an account on GitHub.

https://github.com/ystyle/jvms/releases

下载最新版本

image-20260731150347748

推荐解压到C:\java

image-20260731151058683

初始化 jvms

在 Windows 设置上搜索编辑系统环境变量

image-20260731151310087

image-20260731151335163

双击 Path

image-20260731151516541

新建这一条记录

image-20260731151532601

然后，打开 powershell ，输入

jvms init

image-20260731151714920

下载 java 8

下载地址为：

https://mirrors.tuna.tsinghua.edu.cn/Adoptium/8/jdk/x64/windows/

mirrors.tuna.tsinghua.edu.cn

image-20260731151911731

image-20260731152034017

image-20260731152049403

image-20260731152105412

image-20260731152127622

image-20260731152205558

image-20260731152420044

image-20260731152457290

image-20260731152801977

启用 java 8

在 powershell 中输入

jvms list

查看本机中由 jvms 管理的 java 版本，然后输入

jvms switch [ 8 前面的数字]

image-20260731153136986

验证安装

在 powershell 输入

java -version

image-20260731154358950

安装 maven

下载

下载链接为

maven.apache.org

Download Apache Maven – Maven

https://maven.apache.org/download.cgi

image-20260731153339688

解压

将压缩包解压到C:\maven

image-20260731153428512

配置

修改配置文件C:\maven\conf\settings.xml

在<mirrors>和 </mirrors> 之间添加

    <mirror>
      <id>aliyun</id>
      <mirrorOf>central</mirrorOf>
      <name>aliyun maven</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>

此配置用于设置 maven 镜像仓库地址

image-20260731153655968

在<settings>和</settings>之间添加

<localRepository>E:\m2</localRepository>

此配置用于设置 maven 本地仓库地址，尽量改成 C 盘以外

image-20260731154128693

在系统环境变量中添加

image-20260731154251729

验证安装

在 powershell 输入

mvn -v

image-20260731154504736

安装 Git

下载

下载链接为

git-scm.com

Git - Install for Windows

https://git-scm.com/install/windows

image-20260731154621281

安装过程中，默认配置就行，一直按下一步，直到安装成功

验证安装

在 powershell 输入

git -v

image-20260731154755495

安装 Docker Desktop

下载

下载地址为

docker.com

Docker Desktop: The #1 Containerization Tool for Developers | Docker

Docker Desktop is collaborative containerization software for developers. Get started and download Docker Desktop today on Mac, Windows, or Linux.

https://www.docker.com/products/docker-desktop/

image-20260731154932093

配置

建议重写 Docker Engine

image-20260731155106237

如果你使用轩辕镜像请将配置修改为

{
  "builder": {
    "gc": {
      "defaultKeepStorage": "30GB",
      "enabled": true
    }
  },
  "experimental": false,
  "insecure-registries": [
    "******.xuanyuan.run"
  ],
  "registry-mirrors": [
    "https://******.xuanyuan.run"
  ]
}

安装 node

使用 nvm 管理 node 版本

下载 nvm

下载链接为

nvm.uihtm.com

开始下载nvm - nvm中文官网

nvm内容管理框架

https://nvm.uihtm.com/doc/download-nvm.html

image-20260731161340244

然后同意协议，默认配置，并安装

配置 nvm

在 powershell 中运行

# 注意结尾有斜杠
nvm node_mirror https://npmmirror.com/mirrors/node/ 
nvm npm_mirror https://npmmirror.com/mirrors/npm/

此配置用于设置国内镜像源

安装 node

在 powershell 中运行

# 输出安装版本
nvm -v
# 安装 node 22
nvm install 22
# 使用 node 22
nvm use 22

配置 node

在 powershell 中运行

npm config set registry https://registry.npmmirror.com

此配置用于设置国内镜像源

程序打包并拷贝

启动 mysql

在 D 盘打开 powershell 并运行

git clone https://gitee.com/qinzihang2006/blog.git

image-20260731155632133

在D:\blog下运行

docker compose up mysql

在出现

image-20260731160035489

时，就可以退出了，它会在后台运行

修改配置文件

将D:\blog\bbs-web-admin\.env.production中的VITE_API_URL的值改为服务器真实的 ip 地址

将D:\blog\bbs-web-mobile\.env.production 中的VITE_API_URL的值改为服务器真实的 ip 地址

将D:\blog\bbs-web-pc\.env.production中的VITE_API_URL的值改为服务器真实的 ip 地址

在D:\blog\src\main\resources\crossOrigin.properties中添加跨域请求的地址，例如http://10.1.100.104

安装依赖

在D:\blog下运行mvn install，下载后端相关依赖

在D:\blog\bbs-web-mobile下运行npm install，下载 mobile 端依赖

在D:\blog\bbs-web-admin下运行npm install，下载 admin 端依赖

在D:\blog\bbs-web-pc下运行npm install，下载 web 端依赖

测试运行

在D:\blog下运行mvn spring-boot:run，如果出现类似于

16:28:47 INFO  cms.Application - Started Application in 5.304 seconds (JVM running for 5.962)

并且无报错信息，默认可以运行

在D:\blog\bbs-web-mobile下运行npm run dev如果出现类似于

  vite v2.9.15 dev server running at:

  > Local: http://localhost:3000/admin/
  > Network: use `--host` to expose

  ready in 579ms.

并且无报错信息，默认可以运行

admin 端和 pc 端同理

打包

在D:\blog下运行mvn clean package

实际上 mvn install 命令就包含了打包

在D:\blog\bbs-web-mobile下运行npm run build

在D:\blog\bbs-web-admin下运行npm run build

在D:\blog\bbs-web-pc下运行npm run build

上传

这里以 Ubuntu 24.04 为例

将 D:\blog\target\bbs-pro-6.9.jar 拷贝到服务器的~下

将 D:\blog\bbs-web-pc\dist拷贝到服务器的~/bbs-web-pc下

将 D:\blog\bbs-web-mobile\dist拷贝到服务器的~/bbs-web-mobile下

将 D:\blog\bbs-web-admin\dist拷贝到服务器的~/bbs-web-admin下

将 D:\blog\docker-compose.yml拷贝到服务器的~下

将 D:\blog\nginx.conf拷贝到服务器的~下

将 D:\blog\bbs-pro.sql拷贝到服务器的~下

image-20260731182223230

服务器环境搭建

安装 Docker

参考

developer.aliyun.com

docker-ce镜像_docker-ce下载地址_docker-ce安装教程-阿里巴巴开源镜像站

阿里巴巴开源镜像站为您提供免费的docker-ce下载地址及docker-ce安装教程，docker-ce镜像简介：docker ce阿里巴巴开源镜像站

https://developer.aliyun.com/mirror/docker-ce

自动安装脚本为

curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun

添加用户组

sudo groupadd docker
sudo usermod -aG docker $USER

配置

推荐使用轩辕镜像修改 docker 的配置

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

运行

在 ~ 下运行

sudo docker compose up -d

修改论坛配置

访问 http://ip地址:8085/admin/login

用户名：admin

密码：1234567

image-20260731190533587

语法支持

GitHub Flavored Markdown (GFM)
- 表格
- 任务列表
- 删除线
- 自动链接

Mermaid 图表

支持在 Markdown 中使用 Mermaid 语法绘制流程图、时序图、架构图等。

```mermaid
flowchart LR
    A[构建时脚本] --> B[JSON 数据文件] --> C[运行时工具函数]
```

flowchart LR
    A[构建时脚本] --> B[JSON 数据文件] --> C[运行时工具函数]

支持的图表类型：

flowchart / graph - 流程图
sequenceDiagram - 时序图
classDiagram - 类图
stateDiagram - 状态图
erDiagram - ER 图
gantt - 甘特图
pie - 饼图
mindmap - 思维导图

图表会自动跟随深色/浅色主题切换。更多语法参考 Mermaid 官方文档。

Infographic 信息图

支持使用 @antv/infographic 在 Markdown 中绘制精美的信息图表，适合展示流程、对比、层级、统计等数据。

使用方式：在代码块中使用 infographic 标记，第一行指定模板名称，然后使用类似 YAML 的语法定义数据：

```infographic
infographic list-grid-badge-card
data
  title 技术栈
  desc 我的常用技术栈
  items
    - label TypeScript
      desc 类型安全的 JavaScript
      icon mdi/language-typescript
    - label React
      desc 用户界面库
      icon mdi/react
    - label Astro
      desc 现代化静态站点生成器
      icon mdi/rocket-launch
```

infographic list-grid-badge-card
data
  title 技术栈
  desc 我的常用技术栈
  items
    - label TypeScript
      desc 类型安全的 JavaScript
      icon mdi/language-typescript
    - label React
      desc 用户界面库
      icon mdi/react
    - label Astro
      desc 现代化静态站点生成器
      icon mdi/rocket-launch

可用模板类型：

列表类 (list-*)：展示信息列表
- list-grid-badge-card - 卡片网格布局
- list-grid-candy-card-lite - 糖果风格卡片
- list-row-horizontal-icon-arrow - 水平图标箭头列表
流程/顺序类 (sequence-*)：展示步骤、流程或阶段
- sequence-zigzag-steps-underline-text - 之字形步骤
- sequence-circular-simple - 圆形流程
- sequence-roadmap-vertical-simple - 垂直路线图
- sequence-pyramid-simple - 金字塔结构
对比类 (compare-*)：二元或多元对比
- compare-binary-horizontal-simple-fold - 水平二元对比
- compare-swot - SWOT 分析
- compare-hierarchy-left-right-circle-node-pill-badge - 层级左右对比
层级类 (hierarchy-*)：展示树形结构
- hierarchy-tree-tech-style-capsule-item - 科技风格树形图
- hierarchy-tree-curved-line-rounded-rect-node - 曲线连接树形图
图表类 (chart-*)：数据可视化
- chart-column-simple - 柱状图
- chart-bar-plain-text - 条形图
- chart-pie-plain-text - 饼图
- chart-line-plain-text - 折线图
其他
- quadrant-* - 象限分析图
- relation-* - 关系图

数据字段说明：

title - 标题（可选）
desc - 描述文本（可选）
items - 条目数组，每个条目可包含：
- label - 主标签文本
- value - 数值（用于图表类模板）
- desc - 描述文本
- icon - 图标名称（格式：mdi/icon-name）
- children - 子条目（用于层级结构）

主题定制：

可以在数据后添加 theme 块自定义颜色：

```infographic
infographic sequence-pyramid-simple
data
  items
    - label 基础层
    - label 中间层
    - label 顶层
theme
  palette
    - #3b82f6
    - #8b5cf6
    - #f97316
```

信息图会自动跟随深色/浅色主题切换，并使用项目的寒蝉全圆体字体渲染。更多模板和语法参考 Infographic 官方文档。

代码高亮

基于 Shiki
支持双主题（深色/浅色）
支持语言标注
行号显示

示例：

```javascript
function hello() {
  console.log("Hello, world!");
}
```

function hello() {
  console.log("Hello, world!");
}

标题自动链接

所有标题自动生成可点击的锚点链接。

链接自动嵌入

独行的特殊链接会自动转换为嵌入组件：

Twitter/X 链接：自动嵌入 Tweet 组件
CodePen 链接：自动嵌入交互式 CodePen 演示
其他链接：显示 OG 预览卡片（包含标题、描述、图片等）

示例：

<!-- 独行链接会被嵌入 -->

https://x.com/vercel_dev/status/1997059920936775706

https://codepen.io/botteu/pen/YPKBrJX/

https://github.com/vercel/react-tweet

反爬严格，获取不到元信息的链接

https://zhuanlan.zhihu.com/p/1900483903984243480

<!-- 段落中的链接保持不变 -->

这是一个 [普通链接](https://example.com)，不会被嵌入。

See the Pen YPKBrJX by botteu (@botteu) on CodePen.

github.com

GitHub - vercel/react-tweet: Embed tweets in your React application.

Embed tweets in your React application. Contribute to vercel/react-tweet development by creating an account on GitHub.

https://github.com/vercel/react-tweet

反爬严格，获取不到元信息的链接

https://zhuanlan.zhihu.com/p/1900483903984243480

zhuanlan.zhihu.com

这是一个普通链接，不会被嵌入。

Shoka 兼容 Markdown 语法

astro-koharu 从 Hexo Shoka 主题迁移了一套丰富的 Markdown 扩展语法，所有功能均可通过 config/site.yaml 的 content 配置项独立开关。

文字特效（`enableShokaEffects`）

支持多种行内文字装饰效果：

语法	效果	说明
`++文字++`	下划线	`<ins>` 标签
`++文字++{.wavy}`	波浪下划线	支持 `.wavy` 修饰符
`++文字++{.dot}`	着重点	支持 `.dot` 修饰符
`++文字++{.primary}`	彩色下划线	支持 `.primary` `.success` `.warning` `.danger` `.info`
`==文字==`	高亮	`<mark>` 标签
`~文字~`	下标	`<sub>` 标签，如 H₂O
`^文字^`	上标	`<sup>` 标签，如 E=mc²

示例效果：

这是下划线文字波浪下划线着重点标记

主色调成功警告危险信息

这是高亮文字

H₂O 是水的化学式，E = mc² 是质能方程

颜色文字与特殊样式（`enableShokaAttrs`）

使用 文字 语法为文字添加颜色和样式：

[红色]{.red} [粉色]{.pink} [橙色]{.orange} [黄色]{.yellow}
[绿色]{.green} [水色]{.aqua} [蓝色]{.blue} [紫色]{.purple} [灰色]{.grey}

[这段文字会有彩虹渐变效果]{.rainbow}

[Ctrl]{.kbd} + [C]{.kbd} 复制，[Ctrl]{.kbd} + [V]{.kbd} 粘贴

[默认]{.label .default} [主要]{.label .primary} [信息]{.label .info}
[成功]{.label .success} [警告]{.label .warning} [危险]{.label .danger}

示例效果：

红色粉色橙色黄色绿色水色蓝色紫色灰色

这段文字会有彩虹渐变效果

Ctrl + C 复制，Ctrl + V 粘贴

默认主要信息成功警告危险

隐藏文字 / Spoiler（`enableShokaSpoiler`）

这里有一段!!隐藏文字，点击显示!!

这里有一段!!模糊文字，鼠标悬停显示!!{.blur}

示例效果：

这里有一段隐藏文字，点击显示

这里有一段模糊文字，鼠标悬停显示

默认模式：点击后粒子消散动画揭示文字（基于 spoilerjs Web Component）
.blur 模式：鼠标悬停时模糊消失

注音标注 / Ruby（`enableShokaRuby`）

为 CJK 文字添加注音，适用于日语假名、汉语拼音等：

{漢字^かんじ}的注音示例

{取り返す^とりかえす}是日语中"取回"的意思

示例效果：

{漢字^{かんじ}的注音示例。{取り返す}とりかえす}是日语中"取回"的意思。

渲染为 HTML <ruby> 标签，浏览器原生支持。

提醒块 / Note Blocks（`enableShokaContainers`）

使用 ::: 语法创建不同样式的提醒块：

:::default
这是默认提醒块
:::

:::primary
这是主要提醒块，用于重要提示
:::

:::info
这是信息提醒块
:::

:::success
这是成功提醒块
:::

:::warning
这是警告提醒块
:::

:::danger
这是危险提醒块
:::

:::info no-icon
这是没有图标的信息块
:::

示例效果：

这是信息提醒块，用于提供额外信息

这是警告提醒块，请注意

这是危险提醒块，务必谨慎

支持的样式：default、primary、info、success、warning、danger。添加 no-icon 可隐藏图标。提醒块内部支持嵌套 Markdown 语法。

折叠块 / Collapse（`enableShokaContainers`）

使用 +++ 语法创建可折叠内容（渲染为 <details> + <summary>）：

+++primary 点击展开详细内容
折叠的内容，支持 **Markdown** 格式化。

- 列表项 1
- 列表项 2
+++

+++warning 注意事项
需要注意的内容
+++

+++danger 危险操作
请确保你知道自己在做什么！
+++

示例效果：

点击展开详细内容

折叠的内容，支持 Markdown 格式化。

列表项 1
列表项 2

注意事项

需要注意的内容

支持的样式：primary、info、success、warning、danger。

标签卡 / Tabs（`enableShokaContainers`）

使用 ;;; 语法创建标签页切换，同一组 ID 的标签卡会自动组合：

;;;mygroup JavaScript
```js
console.log('Hello, World!');
```
;;;

;;;mygroup Python
```python
print('Hello, World!')
```
;;;

;;;mygroup Rust
```rust
fn main() {
    println!("Hello, World!");
}
```
;;;

示例效果：

JavaScript Python Rust

console.log('Hello, World!');

print('Hello, World!')

fn main() {
    println!("Hello, World!");
}

;;;groupId 标签名 定义一个标签页，同一 groupId 的标签自动组合
第一个标签默认激活
标签内支持任意 Markdown 内容

友链卡片（`enableShokaHexoTags`）

使用 {% links %} 标签在文章中插入友链卡片网格：

{% links %}
- site: 博客名称
  url: https://example.com
  owner: 站长昵称
  desc: 站点描述
  image: https://example.com/avatar.png
  color: '#ed788b'
- site: 另一个博客
  url: https://example2.com
  owner: Alice
  desc: 一个热爱技术的博客
  image: https://api.dicebear.com/7.x/avataaars/svg?seed=Alice
  color: '#BEDCFF'
{% endlinks %}

示例效果：

卡片数据使用 YAML 格式，支持 site、url、owner、desc、image、color 字段。

音频播放器（`enableShokaHexoTags`）

使用 {% media audio %} 标签嵌入音频播放器，支持网易云音乐、QQ 音乐等平台（通过 Meting API 解析）。

默认使用 https://163.hyc.moe/ 作为 Meting API，可在 config/site.yaml 的 bgm.metingApi 中自定义，推荐自部署以获得更稳定的服务。

{% media audio %}
- name: 歌曲名称
  url: https://music.163.com/#/song?id=3339210292
{% endmedia %}

示例效果：

支持歌单模式，可配置多个分组：

{% media audio %}
- title: 歌单名称 1
  list:
    - https://music.163.com/#/playlist?id=8676645748
- title: 歌单名称 2
  list:
    - https://music.163.com/#/playlist?id=17606384886
{% endmedia %}

视频播放器（`enableShokaHexoTags`）

使用 {% media video %} 标签嵌入视频播放器：

{% media video %}
- name: 视频 1
  url: https://example.com/video1.mp4
- name: 视频 2
  url: https://example.com/video2.mp4
{% endmedia %}

多个视频时自动显示播放列表。

练习题系统（`enableQuiz`）

支持四种交互式题型，适合教程和学习笔记。需在文章 frontmatter 中设置 quiz: true。

单选题：

- 下列哪个是 JavaScript 的基本数据类型？{.quiz}
  - Object{.options}
  - Array{.options}
  - Symbol{.correct}
  - Function{.options}

> 解析：Symbol 是 ES6 引入的基本数据类型。

示例效果：

下列哪个是 JavaScript 的基本数据类型？
- Object
- Array
- Symbol
- Function

解析：Symbol 是 ES6 引入的基本数据类型，而 Object、Array、Function 都是引用类型。

选项标记为正确答案，{.options} 为干扰项

多选题：

- 以下哪些是 CSS 布局方式？{.quiz .multi}
  - Flexbox{.correct}
  - jQuery{.options}
  - Grid{.correct}
  - Float{.correct}

> 解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。

示例效果：

以下哪些是 CSS 布局方式？
- Flexbox
- jQuery
- Grid
- Float

解析：Flexbox、Grid 和 Float 都是 CSS 布局方式。jQuery 是一个 JavaScript 库。

添加 .multi 标记启用多选模式

判断题：

- `const` 声明的变量不能重新赋值，但可以修改其属性。{.quiz .true}

> 解析：`const` 只保证变量绑定不可变。

- HTML 是一种编程语言。{.quiz}

> 解析：HTML 是标记语言，不是编程语言。

示例效果：

const 声明的变量不能重新赋值，但可以修改其属性。

解析：const 只保证变量绑定不可变，如果变量指向一个对象，其属性仍然可以修改。

HTML 是一种编程语言。

解析：HTML（超文本标记语言）是一种标记语言，不是编程语言。

添加 .true 表示陈述正确，不添加 .true 则表示错误

填空题：

- CSS 中，[Flexbox]{.gap} 适合一维布局，[Grid]{.gap} 适合二维布局。{.quiz .fill}

> 常见错误：[Float]{.mistake}

示例效果：

CSS 中，Flexbox 适合一维布局，Grid 适合二维布局。

常见错误：Float

[答案] 标记正确答案（支持多个空）
[错误答案] 标记常见错误（首次答错时提示）
> 引用块内容为解析说明

数学公式（`enableMath`）

基于 KaTeX 渲染数学公式。需在文章 frontmatter 中设置 math: true：

行内公式：$E = mc^2$

块级公式：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

示例效果：

行内公式：E=mc2E = mc^2E=mc2

块级公式：

∑n=1∞1n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}n=1∑∞n21=6π2

代码块增强（`enableCodeMeta`）

代码块支持额外的元数据标注：

```js title="hello.js" url="https://example.com" linkText="查看源码" mark:1,3
const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);
```

```bash command:("$":1-3)
npm install astro
npm run dev
npm run build
```

元数据	说明
`title="文件名"`	显示代码块标题
`url="链接"`	添加外部源码链接
`linkText="文字"`	自定义链接文字（默认为 URL）
`mark:1,3`	高亮指定行
`command:("$":1-3)`	标记 shell 命令行（显示 `$` 前缀）

示例效果：

const greeting = 'Hello';
const name = 'World';
console.log(`${greeting}, ${name}!`);

npm install astro
npm run dev
npm run build

Shoka 功能配置总览：

所有 Shoka 兼容功能均可在 config/site.yaml 的 content 部分独立开关：

content:
  # Shoka 兼容功能（默认全部启用，设为 false 可关闭）
  enableShokaContainers: true   # :::提醒块 ;;;标签卡 +++折叠块
  enableShokaAttrs: true        # text 属性语法
  enableShokaEffects: true      # ++下划线++ ==高亮== ~下标~ ^上标^
  enableShokaSpoiler: true      # !!隐藏文字!!
  enableShokaRuby: true         # {文字^注音} 注音标注
  enableShokaHexoTags: true     # {% links %} {% media %} Hexo 标签
  enableMath: true              # $数学公式$ KaTeX 渲染
  enableCodeMeta: true          # 代码块增强 (title, mark, command)
  enableQuiz: true              # 练习题交互功能
  enableEncryptedBlock: true    # :::encrypted{password="..."} 加密内容块

内容加密（`enableEncryptedBlock`）

博客支持两种加密方式，满足不同的内容保护需求：

1. 加密块 —— 文章局部加密

在文章中使用 :::encrypted{password="..."} 语法包裹需要加密的内容：

这部分内容公开可见。

:::encrypted{password="demo"}
这段内容需要输入密码 "demo" 才能查看。

支持完整的 Markdown 语法，包括代码块、列表、图片等。
:::

这部分也是公开的。

加密块适合在一篇文章中部分隐藏敏感内容（如答案、剧透、私密笔记），其余内容正常展示。需要在 config/site.yaml 中启用 enableEncryptedBlock: true。

2. 加密文章 —— 整篇文章加密

在文章的 frontmatter 中添加 password 字段即可加密整篇文章：

---
title: 我的私密文章
date: 2026-01-01
password: mySecretPassword
categories:
  - 笔记
---

这里的所有内容都会被加密...

加密文章会显示一个全屏的解锁界面，输入正确密码后才能查看内容。解锁后代码高亮、目录导航、Mermaid 图表等增强功能会自动重新初始化。

安全模型说明：

加密功能使用 AES-256-GCM 算法，安全模型如下：

构建时加密：密码仅在 pnpm build 时用于加密，生成的 HTML 中不包含密码明文
客户端解密：读者在浏览器中输入密码后，通过 Web Crypto API 在本地解密，密码不会发送到任何服务器
密钥派生：使用 PBKDF2（100,000 次迭代）从密码派生加密密钥，提高暴力破解成本
搜索排除：加密内容自动添加 data-pagefind-ignore，不会被 Pagefind 搜索索引

⚠️ 注意：此加密设计的主要目的是防止搜索引擎和爬虫索引加密内容，而非抵御针对性攻击。密文和盐值嵌入在公开的 HTML 中，理论上可被离线暴力破解。请使用强密码，不要用于保护高度敏感的信息。

加密文章的特殊行为：

方面	行为
RSS 订阅	标题前加 🔒 前缀，内容替换为"此文章已加密"提示
SEO / meta	description 使用 frontmatter 中的 `description`（若未设置则显示通用加密提示）
搜索索引	加密内容不会被 Pagefind 索引
目录导航	解锁前不显示，解锁后自动重建
AI 摘要	基于加密前的原文生成（构建时可访问明文）

其他增强

自动目录生成
阅读时间计算
外部链接自动添加 target="_blank"

项目前端开发环境搭建

Fri, 31 Jul 2026 00:55:39 GMT

项目前端开发环境搭建

工具简介

Node.js

Node.js 是一个开源、跨平台的 JavaScript 运行时环境。它基于 Chrome 使用的 V8 引擎，使 JavaScript 可以在浏览器之外的运行环境中执行。

Node.js 不仅能用于开发 Web 服务端程序，还可用于构建前端工程化工具、命令行工具、自动化脚本等。现代前端项目通常依赖 Node.js 来运行构建工具、安装依赖和启动开发服务器。

V8 会使用即时编译等编译技术执行 JavaScript。相较于传统逐行解释的脚本语言执行方式，这类优化能够提升代码的运行速度，并帮助团队降低重复搭建工具链带来的开发成本。

npm

npm 是 Node.js 生态中常用的包管理器。安装 Node.js 时通常会同时安装 npm，因此一般不需要单独安装。

npm 既连接用于在线提供开源 Node.js 软件包的注册表，也提供命令行工具，用于完成以下工作：

根据 package.json 安装和管理项目依赖。
通过 package-lock.json 锁定依赖解析结果，提高不同环境中的安装一致性。
执行 package.json 中定义的脚本，例如 npm run dev。
发布和维护 npm 软件包。

Yarn、pnpm 和 cnpm 都与 npm 生态有关，但它们的定位并不完全相同。Yarn 和 pnpm 是可选的包管理器，cnpm 是兼容 npm 使用方式的客户端。它们不应被简单理解为“npm 的国内镜像”。一个项目应尽量统一包管理器，并提交对应的锁文件，避免混用后产生依赖差异。

NVM for Windows

NVM for Windows 是 Windows 平台上的 Node.js 版本管理工具，可在同一台计算机上安装和切换多个 Node.js 版本。

主要用途包括：

安装、卸载和查看不同版本的 Node.js。
根据项目要求切换 Node.js 版本。
设置当前生效的 Node.js 版本。
降低多个项目对不同 Node.js 版本的兼容成本。

注意：Windows 使用的是 NVM for Windows，它与 macOS、Linux 上常见的 nvm 不是同一个项目，安装方式和部分命令存在差异。

安装方案说明

推荐使用 NVM for Windows 统一安装和管理 Node.js，不建议先安装独立版 Node.js，再安装 NVM for Windows。两套安装同时存在时，可能因环境变量或安装目录冲突，导致 nvm use 切换后 node -v 仍显示旧版本。

本项目使用的 Node.js 版本为 22.17.0。课程截图中还演示了 14.20.0，该版本仅用于需要兼容旧项目时的版本切换练习，不应作为当前项目的默认版本。

清理旧环境

已经安装过 Node.js 或 NVM for Windows 时，建议先清理旧环境；全新电脑可跳过本节。

第一步：关闭相关程序

关闭正在使用 Node.js 的终端、IDE、开发服务器和其他相关进程，避免文件被占用。

第二步：记录当前环境

打开命令提示符，执行以下命令：

node -v
npm -v
where node
where npm

where 命令可以帮助确认系统实际调用的是哪个目录中的可执行文件。

Node.js 和 npm 版本检查

第三步：卸载旧版 Node.js

在 Windows 的“设置”或“控制面板”中卸载独立安装的 Node.js，然后检查原安装目录是否仍有残留。

如果后续准备使用 NVM for Windows，尤其要确认原来的 Node.js 实体目录没有占用 NVM 的符号链接位置。删除目录前应先确认其中没有需要保留的配置或文件。

第四步：卸载旧版 NVM for Windows

需要重新安装 NVM for Windows 时，可通过 Windows 的应用卸载功能进行卸载。卸载后检查 NVM_HOME、NVM_SYMLINK 和 PATH 中是否仍保留失效配置。

不要直接删除不熟悉的环境变量。应先确认变量指向旧的 NVM 安装目录，再进行清理。

第五步：处理 npm 残留

可先使用以下命令查看 npm 的缓存和全局安装目录：

npm config get cache
npm config get prefix

确认不再需要旧环境后，再清理对应目录。用户目录中的 .npmrc 可能包含镜像、代理或私有仓库配置，删除前应先备份。

安装 NVM for Windows

第一步：运行安装程序

运行团队或课程提供的 NVM for Windows 安装程序。安装过程中建议使用默认目录；修改目录时，应避免路径包含特殊字符，并确保符号链接目录不存在同名实体文件夹。

如果安装程序询问是否接管已有 Node.js，推荐先退出安装，按照前文卸载独立版 Node.js 后再重新安装，避免路径冲突。

第二步：重新打开终端

安装完成后，关闭并重新打开命令提示符或 PowerShell。切换 Node.js 版本时，Windows 通常需要管理员权限，因此建议以管理员身份打开终端。

执行以下命令验证 NVM for Windows：

nvm version

部分旧版本也支持：

nvm -v

NVM for Windows 版本检查

安装和切换 Node.js 版本

安装当前项目版本

执行以下命令安装本项目要求的 Node.js：

nvm install 22.17.0

安装完成后切换到该版本：

nvm use 22.17.0

切换时若 Windows 弹出权限确认窗口，应在确认命令来源无误后允许操作。

切换到 Node.js 22.17.0

验证当前版本

执行以下命令：

nvm current
node -v
npm -v

也可以查看本机已安装的全部 Node.js 版本：

nvm list

旧版本的 NVM for Windows 也可使用：

nvm ls

列表中带星号的版本是当前生效版本。

查看已安装版本和当前版本

旧项目版本切换示例

仅当旧项目明确要求 Node.js 14.20.0 时，再安装该版本：

nvm install 14.20.0

安装 Node.js 14.20.0

安装后可切换并查看版本：

nvm use 14.20.0
nvm list

查看旧项目版本

旧项目处理完成后，应切回当前项目版本：

nvm use 22.17.0

启动前端项目

第一步：进入项目目录

打开命令提示符或 IDE 终端，进入项目的 webui 目录：

cd <项目目录>\webui

第二步：确认 Node.js 版本

node -v
npm -v

当前项目应使用 Node.js 22.17.0。如果版本不正确，执行：

nvm use 22.17.0

第三步：安装项目依赖

首次运行项目或依赖发生变化时，需要先安装依赖。

项目已提交且未修改 package-lock.json 时，可优先使用可重复安装命令：

npm ci

没有 package-lock.json，或需要更新锁文件时，使用：

npm install

不要在同一项目中随意混用 npm、Yarn 和 pnpm，否则可能同时生成多个锁文件并造成依赖版本不一致。

第四步：启动开发服务器

npm run dev

启动成功后，应以终端输出的地址为准。Vite 项目的默认地址通常为：

http://localhost:5173

如果 5173 端口已被占用，开发服务器可能自动选择其他端口，因此不要只根据固定地址判断是否启动成功。

常见问题排查

`nvm use` 执行成功，但 Node.js 版本没有变化

依次检查以下项目：

以管理员身份重新打开终端。
关闭旧终端窗口后再重新验证。
执行 where node，检查是否存在独立版 Node.js 的路径冲突。
执行 nvm debug，查看 NVM for Windows 检测到的问题。
确认 NVM 的符号链接目录没有被同名实体目录占用。

提示找不到 `node` 或 `npm`

先执行：

nvm list
nvm use 22.17.0

然后关闭并重新打开终端。如果仍然失败，应检查 NVM_HOME、NVM_SYMLINK 和 PATH。

`npm install` 或 `npm ci` 失败

重点检查：

当前 Node.js 版本是否满足项目要求。
package.json 与 package-lock.json 是否一致。
是否在正确的 webui 目录中执行命令。
网络、代理、镜像和私有仓库认证配置是否有效。
是否混用了不同包管理器生成的锁文件。

`npm run dev` 提示脚本不存在

打开 package.json，确认 scripts 中是否定义了 dev。npm run dev 只是执行项目声明的脚本，并不是所有前端项目都固定使用这一命令。

Java 异常处理

Thu, 30 Jul 2026 12:22:00 GMT

Java 异常处理

异常处理用于描述、传递和处理程序执行期间出现的异常情况。合理使用异常可以帮助定位错误，并在可恢复的场景下采取补救措施。

异常机制不能替代正常的业务判断，也不能保证程序在任何情况下都继续运行。

一、异常体系

image-001

Java 中所有可以被抛出的对象都继承自 Throwable。它主要分为 Error 和 Exception 两大类。

`Error`

Error 通常表示 JVM 或运行环境中的严重问题，例如 OutOfMemoryError。这类问题往往不是普通业务代码能够恢复的，因此一般不在业务代码中捕获后继续执行。

`Exception`

Exception 表示程序可能处理的异常情况，可以继续分为运行时异常和受检查异常。

运行时异常

RuntimeException 及其子类属于运行时异常。编译器不强制要求捕获或声明，常见类型包括：

NullPointerException
ArrayIndexOutOfBoundsException
ClassCastException
ArithmeticException
IllegalArgumentException

运行时异常通常与参数不合法、对象状态错误或程序逻辑缺陷有关，应优先通过校验和修正代码来避免，而不是依赖大量 catch 隐藏问题。

受检查异常

除 RuntimeException 及其子类之外的 Exception 通常属于受检查异常，例如 IOException。

编译器要求程序采用以下方式之一：

使用 try-catch 捕获。
使用 throws 声明并继续向调用者传播。

“受检查”发生在编译阶段，但异常对象是在程序运行到相关语句时才可能产生。

二、使用 `try-catch-finally`

基本语法

try {
    // 可能出现异常的代码
} catch (SpecificException e) {
    // 处理特定异常
} catch (Exception e) {
    // 处理其他异常
} finally {
    // 通常用于释放资源或执行收尾操作
}

执行规则如下：

try 中没有抛出异常时，不会执行对应的 catch。
try 中抛出异常时，JVM 会从上到下寻找第一个类型匹配的 catch。
较具体的子类异常必须写在较宽泛的父类异常之前，否则后面的分支无法到达。
finally 通常都会执行，但 JVM 被强制终止、进程崩溃或执行 System.exit() 等特殊情况除外。

示例

import java.util.InputMismatchException;
import java.util.Scanner;

public class ExceptionDemo {

    public static void main(String[] args) {
        Scanner scanner = new Scanner(System.in);

        try {
            int i = scanner.nextInt();
            int j = scanner.nextInt();

            int result = i / j;
            System.out.println("相除结果：" + result);

            int[] arr = new int[5];
            System.out.println(arr[i]);
            System.out.println("计算完毕");
        } catch (ArithmeticException e) {
            System.out.println("除数不能为零");
        } catch (ArrayIndexOutOfBoundsException e) {
            System.out.println("数组索引越界");
        } catch (InputMismatchException e) {
            System.out.println("请输入整数");
        } catch (Exception e) {
            System.out.println("程序出现其他异常");
            e.printStackTrace();
        } finally {
            scanner.close();
            System.out.println("输入资源已关闭");
        }

        System.out.println("程序继续执行");
    }
}

在实际项目中，不应只输出模糊提示后忽略异常。通常需要记录异常栈、返回明确错误信息，或将异常转换为当前业务层能够理解的类型。

三、使用 `try-with-resources`

try-with-resources 从 Java 7 开始提供，用于自动关闭资源。资源对象必须实现 AutoCloseable 接口。

传统写法

import java.io.FileInputStream;
import java.io.IOException;

public class ResourceDemo {

    public static void main(String[] args) {
        FileInputStream input = null;

        try {
            input = new FileInputStream("d:/a.txt");
            System.out.println(input.read());
        } catch (IOException e) {
            e.printStackTrace();
        } finally {
            if (input != null) {
                try {
                    input.close();
                } catch (IOException e) {
                    e.printStackTrace();
                }
            }
        }
    }
}

关闭前必须进行空值判断，否则创建资源失败时，finally 中可能再次出现 NullPointerException。

四、使用 `throws` 声明异常

throws 写在方法或构造器声明之后，表示当前方法不在这里捕获该异常，而是允许异常继续向调用者传播。

import java.io.FileInputStream;
import java.io.FileNotFoundException;

public class FileService {

    public FileInputStream openFile(String path) throws FileNotFoundException {
        return new FileInputStream(path);
    }
}

throws 本身并没有处理异常。调用者仍然需要捕获该异常，或者继续使用 throws 向上声明。

方法可以声明多个异常：

public void execute() throws FirstException, SecondException {
    // 方法体
}

若声明了父类异常，通常不必再重复声明它的子类异常。

五、使用 `throw` 抛出异常

throw 用于在方法体中抛出一个具体的异常对象。

public void copy(String sourcePath, String targetPath) {
    if (sourcePath == null || targetPath == null) {
        throw new IllegalArgumentException("源路径和目标路径不能为空");
    }

    // 执行复制操作
}

程序执行到 throw 后，当前代码路径会立即中断，控制权交给能够处理该异常的调用层。

`throw` 与 `throws` 的区别

关键字	使用位置	作用
`throw`	方法体内部	抛出一个具体异常对象
`throws`	方法或构造器声明后	声明可能向调用者传播的异常类型

六、自定义异常

当 JDK 提供的异常类型无法清楚表达业务含义时，可以定义业务异常。

自定义受检查异常

public class InvalidEmailAddressException extends Exception {

    public InvalidEmailAddressException(String message) {
        super(message);
    }
}

public class EmailManager {

    public void sendEmail(
            String recipient,
            String title,
            String content
    ) throws InvalidEmailAddressException {
        if (recipient == null || recipient.isBlank()) {
            throw new InvalidEmailAddressException("收件人地址不能为空");
        }

        System.out.println("发送邮件成功");
    }
}

继承 Exception 后，调用者必须捕获或声明该异常。

自定义运行时异常

若异常表示参数错误、业务规则不满足，且不希望强制每一层代码显式捕获，也可以继承 RuntimeException：

public class InvalidEmailAddressException extends RuntimeException {

    public InvalidEmailAddressException(String message) {
        super(message);
    }
}

选择受检查异常还是运行时异常，应结合调用者是否能够恢复、项目异常处理规范以及框架约定决定。

七、异常处理建议

捕获能够真正处理的异常，不要无意义地捕获后忽略。
优先捕获具体异常，避免直接使用过于宽泛的 Exception。
保留原始异常作为 cause，不要丢失问题根因。
不要把异常用于普通流程控制。
资源优先使用 try-with-resources 管理。
对外返回稳定的错误信息，对内记录完整异常栈和必要上下文。

Java 日期与时间类

Thu, 30 Jul 2026 12:20:36 GMT

Java 日期与时间类

Java 中常见的日期时间 API 可以分为两类：

旧版 API：Date、Calendar、SimpleDateFormat。
Java 8 新 API：LocalDate、LocalDateTime、Instant、DateTimeFormatter 等。

旧版 API 在维护历史代码时仍会遇到，但新项目通常优先使用 java.time 包。

一、时间戳与时区

Unix 时间戳通常表示从 1970-01-01T00:00:00Z 开始经过的时间。Date 使用毫秒精度保存时间点。

北京时间通常采用 UTC+8。时区会影响时间点如何显示为年月日和时分秒，但不会改变时间点本身。

二、`Date` 类

java.util.Date 表示时间轴上的一个时间点，内部核心值是从 Unix 纪元开始计算的毫秒数。它并不是简单地分别保存年、月、日、时、分、秒。

Date 中许多直接操作年月日的方法已经过时，日期计算应使用 Calendar 或更推荐的 java.time API。

构造器

Date now = new Date();

无参构造器创建表示当前时间的对象。

Date date = new Date(1_000_000L);

传入的 long 值表示从 Unix 纪元开始经过的毫秒数。

常用方法

Date date = new Date();

long timestamp = date.getTime();
date.setTime(timestamp + 1_000L);

getTime()：获取毫秒时间戳。
setTime(long time)：修改该对象表示的时间点。

Date 是可变对象，调用 setTime() 会改变原对象。

三、`Calendar` 类

Calendar 是旧版日历计算类，可以根据时区和区域设置处理年月日等字段。

它的构造器通常不直接调用，而是通过 getInstance() 获取实例：

Calendar calendar = Calendar.getInstance();

获取和修改日期字段

Calendar calendar = Calendar.getInstance();
calendar.add(Calendar.DATE, 3);

int year = calendar.get(Calendar.YEAR);
int month = calendar.get(Calendar.MONTH) + 1;
int day = calendar.get(Calendar.DAY_OF_MONTH);

System.out.println(year + "-" + month + "-" + day);

注意：

Calendar.MONTH 从 0 开始，因此显示月份时通常需要加 1。
add() 的参数可以为正数或负数，用于增加或减少时间。
Calendar 也是可变对象。

与 `Date` 相互转换

Calendar calendar = Calendar.getInstance();
Date dateFromCalendar = calendar.getTime();

Date date = new Date(100_000_000L);
Calendar anotherCalendar = Calendar.getInstance();
anotherCalendar.setTime(date);

calendar.getTime()：将 Calendar 当前表示的时间转换为 Date。
calendar.setTime(date)：让 Calendar 使用指定 Date 的时间点。

四、`SimpleDateFormat` 类

SimpleDateFormat 用于在 Date 与字符串之间进行格式化和解析。

常见格式符号如下：

符号	含义	示例
`yyyy`	四位年份	`2026`
`MM`	两位月份	`01`
`dd`	两位日期	`25`
`HH`	`24` 小时制小时	`16`
`mm`	分钟	`30`
`ss`	秒	`45`

格式符号区分大小写。例如，MM 表示月份，mm 表示分钟。

将 `Date` 格式化为字符串

import java.text.SimpleDateFormat;
import java.util.Date;

public class FormatDateDemo {

    public static void main(String[] args) {
        SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
        Date now = new Date();

        String text = formatter.format(now);
        System.out.println(text);
    }
}

将字符串解析为 `Date`

import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;

public class ParseDateDemo {

    public static void main(String[] args) {
        SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd");
        formatter.setLenient(false);

        String text = "2026-01-25";

        try {
            Date date = formatter.parse(text);
            System.out.println(date);
        } catch (ParseException e) {
            System.out.println("日期格式不正确");
        }
    }
}

setLenient(false) 用于关闭宽松解析。例如，在严格模式下，2026-02-30 会解析失败，而不是自动调整到下一个月。

SimpleDateFormat 不是线程安全的，不应把同一个实例作为共享对象供多个线程同时使用。

五、旧版 API 应用

指定日期增加十五天

将 20260122 增加十五天，并按中文日期格式输出：

import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.Date;

public class AddDaysLegacyDemo {

    public static void main(String[] args) {
        String text = "20260122";
        SimpleDateFormat formatter = new SimpleDateFormat("yyyyMMdd");
        formatter.setLenient(false);

        try {
            Date date = formatter.parse(text);

            Calendar calendar = Calendar.getInstance();
            calendar.setTime(date);
            calendar.add(Calendar.DATE, 15);

            formatter.applyPattern("yyyy年MM月dd日");
            System.out.println(formatter.format(calendar.getTime()));
        } catch (ParseException e) {
            System.out.println("日期格式不正确");
        }
    }
}

计算两个时间点的毫秒差

long differenceMillis = endDate.getTime() - startDate.getTime();

直接除以一天的毫秒数只能得到固定时长意义上的天数。如果时间范围跨越夏令时变化，结果可能与日历日期差不同。因此，计算日期之间相差多少天时，更适合使用 LocalDate 和 ChronoUnit.DAYS。

六、Java 8 日期时间 API

java.time API 的类型设计更清晰，并且大多数核心类不可变、线程安全。

`LocalDate`

LocalDate 表示不带时区的日期，例如生日或课程日期。

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;

public class LocalDateDemo {

    public static void main(String[] args) {
        DateTimeFormatter inputFormatter = DateTimeFormatter.ofPattern("yyyyMMdd");
        DateTimeFormatter outputFormatter = DateTimeFormatter.ofPattern("yyyy年MM月dd日");

        LocalDate date = LocalDate.parse("20260122", inputFormatter);
        LocalDate result = date.plusDays(15);

        System.out.println(result.format(outputFormatter));
    }
}

计算日期差

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.temporal.ChronoUnit;

public class DateDifferenceDemo {

    public static void main(String[] args) {
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyyMMdd");

        LocalDate startDate = LocalDate.parse("20260122", formatter);
        LocalDate endDate = LocalDate.parse("20260302", formatter);

        long days = ChronoUnit.DAYS.between(startDate, endDate);
        System.out.println(days);
    }
}

常用类型

类型	适用场景
`LocalDate`	只需要年月日，不需要时区
`LocalTime`	只需要时分秒
`LocalDateTime`	需要日期和时间，但不包含时区
`Instant`	时间轴上的时间点，适合记录时间戳
`ZonedDateTime`	需要明确时区规则的日期时间
`Duration`	表示基于秒和纳秒的时长
`Period`	表示基于年、月、日的日期差
`DateTimeFormatter`	日期时间的格式化和解析

新代码应根据业务含义选择类型，而不是所有时间都使用 Date 或字符串保存。

TCP 三次握手和四次挥手

Thu, 30 Jul 2026 12:19:23 GMT

TCP 三次握手和四次挥手

TCP 是面向连接的传输层协议。通信双方在传输应用数据前，需要通过三次握手建立连接；数据传输结束后，通常通过四个报文段释放双向连接。

TCP 首部中的相关字段

image-001

序列号 `seq`

序列号字段占 32 位。TCP 会对字节流中的数据进行编号，报文段中的序列号通常表示该报文段所携带数据的第一个字节编号。

建立连接时，通信双方会分别选择初始序列号。SYN 和 FIN 即使不携带应用数据，也各自会消耗一个序列号。

确认号 `ack`

确认号字段占 32 位，表示接收方期望收到的下一个字节序号。

例如，若已经正确收到对方序号为 100 到 199 的数据，则确认号通常为 200。

`ACK` 标志位

ACK 占 1 位。当 ACK 为 1 时，确认号字段有效。连接建立后，绝大多数 TCP 报文段都会设置该标志位。

需要区分：

小写的 ack 通常表示确认号字段的值。
大写的 ACK 表示 TCP 首部中的确认标志位。

`SYN` 标志位

SYN 用于建立连接并同步双方的初始序列号。

SYN=1、ACK=0：通常表示连接请求。
SYN=1、ACK=1：通常表示同意建立连接并确认对方的请求。

`FIN` 标志位

FIN 表示发送方已经没有数据需要发送，请求关闭当前方向上的连接。TCP 是全双工协议，因此一个方向关闭后，另一个方向仍然可以继续传输数据。

三次握手

image-002

假设客户端的初始序列号为 x，服务器的初始序列号为 y。

第一次握手：客户端发送 `SYN`

客户端向服务器发送连接请求：

SYN=1, seq=x

发送后，客户端从 CLOSED 进入 SYN-SENT 状态。

第二次握手：服务器发送 `SYN+ACK`

服务器收到客户端的请求后，确认客户端的序列号，并发送自己的初始序列号：

SYN=1, ACK=1, seq=y, ack=x+1

发送后，服务器从 LISTEN 进入 SYN-RECEIVED 状态。

第三次握手：客户端发送 `ACK`

客户端收到服务器的响应后，再发送确认报文：

ACK=1, seq=x+1, ack=y+1

服务器收到该确认后，双方进入 ESTABLISHED 状态，可以传输应用数据。

第三次握手中的纯 ACK 报文如果不携带数据，本身不会额外消耗序列号。

为什么需要三次握手

三次握手主要完成以下工作：

确认双方的发送能力和接收能力基本正常。
同步双方各自的初始序列号。
避免失效的旧连接请求直接导致服务器建立错误连接。
协商 TCP 选项，例如最大报文段长度和窗口扩大因子。

只进行两次交互时，服务器无法确认客户端是否已经收到服务器的初始序列号和连接确认，因此需要第三次确认。

四次挥手

image-003

下面以客户端主动关闭连接为例。假设客户端发送 FIN 时的序列号为 u，服务器当前序列号为 v。

第一次挥手：客户端发送 `FIN`

客户端表示自己已经没有数据需要发送：

FIN=1, ACK=1, seq=u

客户端进入 FIN-WAIT-1 状态。FIN 会消耗一个序列号。

第二次挥手：服务器确认客户端的 `FIN`

服务器收到 FIN 后发送确认：

ACK=1, seq=v, ack=u+1

服务器进入 CLOSE-WAIT 状态，客户端收到确认后进入 FIN-WAIT-2 状态。

此时客户端到服务器方向已经关闭，但服务器到客户端方向仍可继续传输尚未发送完的数据，这种状态称为半关闭。

第三次挥手：服务器发送 `FIN`

服务器完成剩余数据发送后，请求关闭自己的发送方向。假设此时服务器序列号为 w：

FIN=1, ACK=1, seq=w, ack=u+1

服务器进入 LAST-ACK 状态，等待客户端的最终确认。

第四次挥手：客户端确认服务器的 `FIN`

客户端收到服务器的 FIN 后发送确认：

ACK=1, seq=u+1, ack=w+1

客户端进入 TIME-WAIT 状态。服务器收到该确认后进入 CLOSED 状态。

为什么通常需要四次挥手

TCP 的两个传输方向需要分别关闭。主动关闭方发送 FIN 后，被动关闭方可能仍有数据需要发送，因此通常先单独确认对方的 FIN，等剩余数据发送完毕后再发送自己的 FIN。

如果被动关闭方收到 FIN 时已经没有数据需要发送，也可能把 ACK 与自己的 FIN 合并到同一个报文段中。此时网络上看到的报文段数量可能少于四个，但连接释放的逻辑仍然包含两个方向的关闭与确认。

`TIME-WAIT` 状态

主动关闭方通常会在 TIME-WAIT 状态等待 2MSL。MSL 表示报文段在网络中的最大生存时间。

等待的主要原因有两个：

若最后一个 ACK 丢失，被动关闭方会重发 FIN，主动关闭方仍能再次确认。
让当前连接产生的延迟报文在网络中消失，避免影响之后使用相同四元组建立的新连接。

TIME-WAIT 是 TCP 保证可靠关闭的重要机制，并不等同于程序异常。

常见状态汇总

状态	含义
`LISTEN`	服务器监听连接请求
`SYN-SENT`	客户端已发送连接请求
`SYN-RECEIVED`	服务器已收到请求并等待最终确认
`ESTABLISHED`	连接已建立
`FIN-WAIT-1`	主动关闭方已发送 `FIN`，等待确认
`FIN-WAIT-2`	主动关闭方已收到确认，等待对方的 `FIN`
`CLOSE-WAIT`	被动关闭方已确认对方的 `FIN`，等待应用关闭连接
`LAST-ACK`	被动关闭方已发送自己的 `FIN`，等待最终确认
`TIME-WAIT`	主动关闭方等待 `2MSL`
`CLOSED`	连接已关闭

MySQL 查询计划详解

Thu, 30 Jul 2026 12:18:04 GMT

MySQL `EXPLAIN` 查询计划详解

EXPLAIN 用于查看 MySQL 为一条 SQL 语句生成的执行计划。通过执行计划可以分析访问顺序、索引选择、预估扫描行数以及排序、临时表等信息。

`DESC` 与 `EXPLAIN` 的区别

查看表结构

DESC 是 DESCRIBE 的缩写，用于查看表或视图的字段信息。

DESC employee;

DESCRIBE employee;

这两条语句通常会显示字段名、数据类型、是否允许为 NULL、索引类型、默认值和附加信息。

查看 SQL 执行计划

在查询语句前添加 EXPLAIN，可以查看优化器选择的执行计划。

EXPLAIN
SELECT *
FROM employee
WHERE first_name = 'tom';

image-001

MySQL 还支持其他输出格式。例如，树形格式更便于观察执行顺序：

EXPLAIN FORMAT=TREE
SELECT *
FROM employee
WHERE first_name = 'tom';

EXPLAIN ANALYZE 会实际执行 SQL，并返回估算值与实际执行数据。对于更新或删除语句应谨慎使用，避免意外修改数据。

EXPLAIN ANALYZE
SELECT *
FROM employee
WHERE first_name = 'tom';

`EXPLAIN` 常见列

image-002

传统表格格式通常包含以下列：

列名	作用
`id`	查询块编号，可辅助判断查询块之间的执行关系
`select_type`	查询块的类型，例如简单查询、主查询、子查询或派生表
`table`	当前访问的表、别名或内部临时结果
`partitions`	预计访问的分区；未使用分区表时通常为 `NULL`
`type`	表访问方式，是判断索引使用情况的重要指标
`possible_keys`	优化器认为可能使用的索引
`key`	实际选择的索引
`key_len`	预计使用的索引键长度，单位为字节
`ref`	与索引列比较的常量或列
`rows`	优化器估算需要检查的行数
`filtered`	经过当前表条件过滤后预计保留的百分比
`Extra`	排序、临时表、覆盖索引等补充信息

`id`：查询块编号

id 用于标识不同的查询块，但不能简单地把它当作绝对执行顺序。

id 相同的多行通常属于同一个查询块，表的显示顺序反映该连接计划中的访问顺序。
id 不同通常表示存在子查询、派生表或 UNION 等多个查询块。
某些结果行的 id 可能为 NULL，例如 UNION RESULT。

复杂 SQL 的真实执行过程还应结合 FORMAT=TREE 或 EXPLAIN ANALYZE 判断。

`select_type`：查询类型

常见取值如下：

取值	含义
`SIMPLE`	不包含 `UNION` 或子查询的简单查询
`PRIMARY`	最外层查询
`UNION`	`UNION` 中第二个及后续查询块
`DEPENDENT UNION`	依赖外层查询结果的 `UNION` 查询块
`UNION RESULT`	`UNION` 结果集
`SUBQUERY`	不依赖外层查询的子查询
`DEPENDENT SUBQUERY`	依赖外层查询结果的相关子查询
`DERIVED`	`FROM` 子句中的派生表
`MATERIALIZED`	被物化后重复使用的子查询结果

`table`：访问对象

table 一般显示表名或表别名。对于优化器生成的内部结果，可能出现以下形式：

<derivedN>：来自编号为 N 的派生表查询块。
<unionM,N>：来自编号为 M、N 等查询块的 UNION 结果。
<subqueryN>：被物化的子查询结果。

`type`：访问方式

type 描述 MySQL 如何从表中读取数据。下面按通常情况下由精确到宽泛的顺序列出常见类型，但实际性能还受返回行数、数据分布和缓存等因素影响。

类型	说明
`system`	表被视为只有一行，是 `const` 的特例
`const`	通过主键或唯一索引等值匹配，最多返回一行
`eq_ref`	连接时通过主键或非空唯一索引匹配，每个前表组合最多命中一行
`ref`	通过普通索引或唯一索引的非完整前缀进行等值查找，可能返回多行
`fulltext`	使用全文索引
`ref_or_null`	类似 `ref`，同时额外查找 `NULL`
`index_merge`	合并多个索引的扫描结果
`unique_subquery`	某些 `IN` 子查询通过唯一索引查找
`index_subquery`	某些 `IN` 子查询通过非唯一索引查找
`range`	对索引执行范围扫描
`index`	扫描整个索引
`ALL`	扫描整张表

分析时通常需要重点关注 ALL 和 index。不过小表全表扫描不一定是问题，不能只根据 type 单独判断 SQL 是否需要优化。

索引相关列

`possible_keys`

显示优化器认为可能使用的索引。值为 NULL 表示当前查询没有明显可用索引，但这并不等同于 SQL 一定存在性能问题。

`key`

显示优化器最终选择的索引。即使 possible_keys 列出了多个索引，key 通常也只显示实际采用的索引；使用 index_merge 时可能显示多个索引。

`key_len`

显示执行计划预计使用的索引键长度。对于联合索引，可以根据该值辅助判断使用到了哪些索引列。

key_len 是估算的最大长度，不代表实际读取的数据长度。字符集、可空列、变长字段和索引列类型都会影响该值。

`ref`

显示索引查找时用于比较的值。例如：

const：与常量比较。
库名.表名.列名：与另一张表的列比较。
func：与表达式、函数结果或发生类型转换的值比较。

`rows` 与 `filtered`

`rows`

rows 是优化器估算需要检查的行数，并非实际扫描行数。统计信息不准确时，估算结果也可能出现偏差。

`filtered`

filtered 是预计通过当前表条件过滤后保留的数据比例，单位为百分比。

可以用下面的方式粗略估算传递给下一步的行数：

rows × filtered ÷ 100

若需要观察实际执行行数和耗时，应使用 EXPLAIN ANALYZE。

`Extra`：补充信息

Extra 中常见信息如下：

信息	说明
`Using index`	使用覆盖索引即可获得所需列，通常不需要回表
`Using where`	读取数据后还需要根据条件进行过滤
`Using index condition`	使用索引条件下推，在存储引擎层过滤部分记录
`Using filesort`	排序无法直接利用合适的索引，需要额外排序；不一定真的写磁盘文件
`Using temporary`	使用内部临时表保存中间结果，常见于部分分组、去重或排序操作
`Using join buffer`	连接过程使用连接缓冲区，通常需要检查连接条件和索引
`FirstMatch`	半连接优化策略之一，找到首个匹配后停止继续查找
`LooseScan`	半连接优化策略之一，通过索引跳跃扫描减少重复匹配
`Impossible WHERE`	优化器判断查询条件不可能成立

Extra 可以同时出现多项信息。例如：

Using index condition; Using where

基本分析思路

分析执行计划时，可以按以下顺序检查：

确认表的访问顺序是否合理。
检查 type 是否出现大表的 ALL 或不必要的 index 扫描。
对比 possible_keys 与 key，确认索引是否被选中。
结合 key_len 判断联合索引的使用范围。
关注 rows、filtered 和 Extra 中的排序、临时表及连接缓冲信息。
对关键 SQL 使用 EXPLAIN ANALYZE，以实际行数和耗时验证估算结果。

商品管理 Demo

Thu, 30 Jul 2026 12:15:31 GMT

商品管理 Demo

本示例使用 Spring Boot、MyBatis-Plus、MySQL 和 Druid，实现商品与类别的分页关联查询。

一、准备数据库

创建 java2601 数据库，并导入 goods.sql 中的表结构和测试数据。示例至少需要以下两张表：

goods：商品表。
category：商品类别表。

商品表中的 cid 用于关联类别表的 cid。

二、创建 Spring Boot 工程

引入依赖

在 pom.xml 中加入以下依赖。版本号可根据课程项目的 Spring Boot 版本统一管理。

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
        <version>3.5.6</version>
    </dependency>

    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>

    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>druid-spring-boot-3-starter</artifactId>
        <version>1.2.23</version>
    </dependency>

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <optional>true</optional>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

配置数据源和 `MyBatis-Plus`

在 application.yml 中配置数据库连接和 MyBatis-Plus：

spring:
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    druid:
      url: jdbc:mysql://localhost:3306/java2601?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
      username: root
      password: root
      driver-class-name: com.mysql.cj.jdbc.Driver
      initial-size: 2
      min-idle: 3
      max-active: 10
      max-wait: 10000

mybatis-plus:
  mapper-locations: classpath*:/mapper/**/*.xml
  type-aliases-package: com.hyxy.goods.po
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
  global-config:
    db-config:
      id-type: auto
      # table-prefix: tb_
      # logic-delete-field: deleteFlag
      # logic-delete-value: 1
      # logic-not-delete-value: 0

开发环境可以直接写用户名和密码，实际项目应通过环境变量或外部配置管理数据库凭据。

创建目录结构

建议按照控制器、业务层、数据访问层和实体类分包。

image-001

使用逆向工程生成基础代码

可以使用 MyBatis-Plus 代码生成器生成实体类、Mapper、Service 和对应 XML 文件。

image-002

生成后需要检查包名、表名、主键策略以及生成文件的保存位置，不能直接假定所有配置都符合当前项目。

三、扫描 Mapper 接口

在启动类上使用 @MapperScan，统一扫描 Mapper 接口：

package com.hyxy.goods;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@MapperScan("com.hyxy.goods.mapper")
public class GoodsApplication {

    public static void main(String[] args) {
        SpringApplication.run(GoodsApplication.class, args);
    }
}

使用 @MapperScan 后，通常不需要再在每个 Mapper 接口上添加 @Mapper。两种方式选择一种即可。

package com.hyxy.goods.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.hyxy.goods.po.Category;

public interface CategoryMapper extends BaseMapper<Category> {
}

package com.hyxy.goods.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.hyxy.goods.po.Goods;

public interface GoodsMapper extends BaseMapper<Goods> {
}

四、配置分页插件

在 config 包中创建配置类，并注册 MyBatis-Plus 分页拦截器：

package com.hyxy.goods.config;

import com.baomidou.mybatisplus.annotation.DbType;
import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MybatisPlusConfig {

    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}

本课件使用 MyBatis-Plus 3.5.6。若升级到 3.5.9 或更高版本，分页插件相关解析器已拆分为可选依赖，需要按照对应版本的官方说明补充模块。

五、实现商品与类别的关联查询

查询商品时，同时显示所属类别名称。

在商品实体类中添加非表字段

cname 来自关联查询，不是 goods 表中的真实字段，因此需要使用 @TableField(exist = false)：

package com.hyxy.goods.po;

import com.baomidou.mybatisplus.annotation.TableField;
import lombok.Data;

@Data
public class Goods {

    // 省略 goods 表中的其他字段

    @TableField(exist = false)
    private String cname;
}

在 Mapper 接口中声明查询方法

分页参数应放在方法参数列表前面，查询条件使用 @Param 显式命名：

package com.hyxy.goods.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.hyxy.goods.po.Goods;
import org.apache.ibatis.annotations.Param;

public interface GoodsMapper extends BaseMapper<Goods> {

    IPage<Goods> selectJoinCategory(
            Page<Goods> page,
            @Param("gname") String gname,
            @Param("cid") Integer cid
    );
}

编写 Mapper XML

在 resources/mapper 目录下创建 GoodsMapper.xml。namespace 必须与 Mapper 接口的全限定类名一致。

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper
        PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "https://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.hyxy.goods.mapper.GoodsMapper">

    <select id="selectJoinCategory" resultType="Goods">
        SELECT
            g.gid,
            g.gname,
            g.price,
            g.stock,
            g.cid,
            g.sales,
            g.onsale,
            g.createtime,
            c.cname AS cname
        FROM goods AS g
        LEFT JOIN category AS c ON g.cid = c.cid
        <where>
            <if test="gname != null and gname != ''">
                AND g.gname LIKE CONCAT('%', #{gname}, '%')
            </if>
            <if test="cid != null">
                AND g.cid = #{cid}
            </if>
        </where>
        ORDER BY g.gid DESC
    </select>

</mapper>

关联查询中的列应尽量添加表别名，避免两张表存在同名字段时产生歧义。

六、编写测试

使用 Spring Boot 测试类验证分页和关联查询结果：

package com.hyxy.goods;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.hyxy.goods.mapper.GoodsMapper;
import com.hyxy.goods.po.Goods;
import jakarta.annotation.Resource;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
class GoodsApplicationTests {

    @Resource
    private GoodsMapper goodsMapper;

    @Test
    void selectJoinCategory() {
        Page<Goods> page = new Page<>(1, 3);

        IPage<Goods> pageResult = goodsMapper.selectJoinCategory(
                page,
                null,
                null
        );

        pageResult.getRecords().forEach(System.out::println);
        System.out.println("总记录数：" + pageResult.getTotal());
        System.out.println("总页数：" + pageResult.getPages());
    }
}

测试时应确认控制台生成了带分页限制的 SQL，并检查每个商品对象中的 cname 是否正确映射。

七、常见问题

Mapper 方法找不到对应 SQL

检查以下内容：

XML 的 namespace 是否与 Mapper 接口全限定名一致。
<select> 的 id 是否与接口方法名一致。
mapper-locations 是否覆盖 XML 文件所在目录。

分页不生效

确认已经注册 MybatisPlusInterceptor 和 PaginationInnerInterceptor，并保证分页参数位于 Mapper 方法参数列表前面。

类别编号条件报错或查询结果异常

在多表查询中使用 g.cid，不要直接写没有表别名的 cid，否则可能出现字段歧义。

Knife4j 实战

Thu, 30 Jul 2026 11:37:51 GMT

Knife4j 实战

Knife4j 核心认知

什么是 Knife4j

Knife4j 是面向 Java Web 项目的接口文档增强解决方案。它能够读取应用生成的 OpenAPI 文档，并提供更易用的接口展示、在线调试、搜索、排序、离线导出和访问控制等功能。

在 Spring Boot 3 项目中，可以将相关组件理解为以下关系：

OpenAPI 3：描述 RESTful API 的规范。
springdoc-openapi：扫描 Spring Web 接口并生成 OpenAPI 3 文档。
Swagger UI：展示和调试 OpenAPI 文档的通用 Web 界面。
Knife4j：在 OpenAPI 文档基础上提供增强界面和扩展能力。

因此，Knife4j 不是一种新的接口规范，也不等同于 OpenAPI 3。对于 Spring Boot 3 项目，Knife4j 的底层文档生成能力主要由 springdoc-openapi 提供。

Spring Boot 2 与 Spring Boot 3 的主要差异

对比项	Spring Boot 2 常见方案	Spring Boot 3 推荐方案
Java 版本	通常可以使用 JDK 8 或更高版本，具体取决于 Spring Boot 版本	最低需要 JDK 17
Java EE 包名	主要使用 `javax.*`	迁移到 `jakarta.*`
接口文档规范	可以使用 OpenAPI 2 或 OpenAPI 3	推荐使用 OpenAPI 3
常见实现	Springfox 或 springdoc-openapi	springdoc-openapi
Knife4j Starter	根据规范和框架版本选择对应 Starter	使用 Jakarta 版本的 OpenAPI 3 Starter
常用注解	旧项目可能使用 `io.swagger.annotations.*`	使用 `io.swagger.v3.oas.annotations.*`

注意：并不是 Spring Boot 3 本身“废弃了 Swagger 2 注解”，而是 Spring Boot 3 项目通常不再使用基于 Springfox 的旧方案。迁移到 springdoc-openapi 后，应将旧注解替换为 OpenAPI 3 注解。

Knife4j 相比 Swagger UI 的常见增强

对比项	Swagger UI	Knife4j
页面展示	提供标准 OpenAPI 文档界面	提供更适合中文项目的增强界面
接口调试	支持在线发送请求	增强参数填写、请求调试和结果展示
接口检索	支持基础过滤	提供接口搜索等增强功能
文档导出	默认不提供完整的离线导出流程	支持导出 Markdown、HTML、Word 和 OpenAPI 文档
扩展配置	使用 Swagger UI 配置项	额外提供 Knife4j 增强配置
访问保护	通常需要自行结合安全框架处理	提供生产保护和 Basic 认证等辅助配置

适用场景

前后端分离项目中自动生成并维护接口文档。
开发和测试阶段在线调用接口。
展示请求参数、响应结构、状态码和字段说明。
多模块或微服务项目中统一管理接口文档。
将接口文档导出后用于交付或归档。

Spring Boot 3 集成 Knife4j

环境要求

本文示例采用以下环境：

JDK 17 或更高版本。
Spring Boot 3.x。
Maven 项目。
spring-boot-starter-web。
Knife4j 4.5.0。

实际项目中应根据 Spring Boot 的具体版本检查依赖兼容性，不要仅凭“版本更高”判断组件一定兼容。

引入 Maven 依赖

Spring Boot 3 使用 Jakarta 版本的 Knife4j Starter：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

该 Starter 已经集成 OpenAPI 3 所需的 springdoc-openapi 相关依赖。通常不需要再单独引入 Springfox、Swagger 2 或其他版本的 springdoc-openapi，否则可能产生依赖冲突。

配置 application.yml

下面给出一个适合单模块项目的基础配置：

server:
  port: 8080

spring:
  application:
    name: knife4j-spring-boot3-demo

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: default
      paths-to-match: /**
      packages-to-scan: com.example.knife4jdemo.controller

knife4j:
  enable: true
  setting:
    language: zh_cn

配置说明：

springdoc.api-docs.path 用于配置 OpenAPI JSON 文档地址。
springdoc.group-configs 用于配置文档分组、接口路径和控制器扫描包。
packages-to-scan 必须替换为当前项目实际的控制器包名。
knife4j.enable 用于开启 Knife4j 增强功能。
knife4j.setting.language 用于设置界面语言。

配置接口文档基本信息

通过声明 OpenAPI Bean 可以统一设置文档标题、版本、说明和联系信息：

package com.example.knife4jdemo.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jOpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("用户管理系统接口文档")
                        .version("1.0.0")
                        .description("基于 Spring Boot 3、OpenAPI 3 和 Knife4j 构建的接口文档")
                        .contact(new Contact()
                                .name("项目开发组")
                                .email("demo@example.com"))
                        .license(new License()
                                .name("Apache 2.0")));
    }
}

启动项目并访问文档

启动 Spring Boot 项目后，在浏览器中访问：

http://localhost:8080/doc.html

OpenAPI JSON 文档的默认访问地址为 /v3/api-docs。如果配置了分组，还可能生成对应的分组文档地址。

`doc.html` 无法访问时的排查顺序

正常情况下，引入 Starter 后不需要手动配置静态资源映射。如果出现 404、401 或 403，应按照以下顺序排查：

检查 Maven 依赖是否使用了 Spring Boot 3 对应的 Jakarta Starter。
检查项目是否错误引入了多个 springdoc-openapi 或 Springfox 版本。
检查 packages-to-scan 是否为真实的控制器包路径。
检查项目是否使用了 @EnableWebMvc，或者是否完全接管了 Spring MVC 配置。
检查 Spring Security 是否拦截了文档页面和 OpenAPI 文档接口。
检查应用是否配置了 context-path，访问地址是否需要增加上下文路径。

只有在项目确实自定义了静态资源规则，并确认自动配置没有生效时，才考虑补充资源映射：

package com.example.knife4jdemo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebResourceConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

这段配置属于故障排查方案，不是所有 Spring Boot 3 项目的固定必配项。

OpenAPI 3 常用注解

旧注解与新注解对照

功能	旧版 Swagger 2 注解	OpenAPI 3 注解
控制器分组	`@Api`	`@Tag`
接口说明	`@ApiOperation`	`@Operation`
参数说明	`@ApiParam`、`@ApiImplicitParam`	`@Parameter`
多个参数说明	`@ApiImplicitParams`	`@Parameters`
模型说明	`@ApiModel`	`@Schema`
字段说明	`@ApiModelProperty`	`@Schema`
隐藏接口或类	`@ApiIgnore`	`@Hidden` 或 `@Operation(hidden = true)`

使用 `@Schema` 描述实体类

package com.example.knife4jdemo.domain;

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户信息")
public class User {

    @Schema(
            description = "用户主键",
            requiredMode = Schema.RequiredMode.REQUIRED,
            example = "10001"
    )
    private Long id;

    @Schema(
            description = "用户名",
            requiredMode = Schema.RequiredMode.REQUIRED,
            example = "zhangsan"
    )
    private String username;

    @Schema(
            description = "手机号码",
            requiredMode = Schema.RequiredMode.REQUIRED,
            example = "13800138000"
    )
    private String phone;

    @Schema(description = "年龄", example = "26")
    private Integer age;

    @Schema(description = "用户状态：0 表示禁用，1 表示正常", example = "1")
    private Integer status;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public Integer getStatus() {
        return status;
    }

    public void setStatus(Integer status) {
        this.status = status;
    }
}

使用 Lombok 的项目可以通过 @Data 简化 Getter 和 Setter，但需要确保项目已经正确引入 Lombok 并启用注解处理。

使用 `@Tag` 和 `@Operation` 描述控制器

package com.example.knife4jdemo.controller;

import com.example.knife4jdemo.domain.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/users")
@Tag(name = "用户管理", description = "提供用户查询接口")
public class UserController {

    @GetMapping("/{id}")
    @Operation(
            summary = "根据编号查询用户",
            description = "根据用户主键查询用户详细信息"
    )
    public User getUserById(
            @Parameter(
                    description = "用户主键",
                    required = true,
                    example = "10001"
            )
            @PathVariable("id") Long id
    ) {
        User user = new User();
        user.setId(id);
        user.setUsername("zhangsan");
        user.setPhone("13800138000");
        user.setAge(26);
        user.setStatus(1);
        return user;
    }

    @GetMapping
    @Operation(
            summary = "查询用户列表",
            description = "查询当前系统中的用户数据"
    )
    public List<User> listUsers() {
        return List.of(getUserById(10001L));
    }
}

重启项目后访问：

http://localhost:8080/doc.html

页面中应展示用户管理分组、接口摘要、参数说明和响应模型。

Knife4j 进阶功能

配置全局 JWT 认证

对于使用 JWT 的项目，可以在 OpenAPI 文档中声明 HTTP Bearer 认证方案。下面的配置是前面 OpenAPI Bean 的升级版本，实际项目中只保留一个 OpenAPI Bean：

package com.example.knife4jdemo.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jOpenApiConfig {

    private static final String SECURITY_SCHEME_NAME = "BearerAuth";

    @Bean
    public OpenAPI customOpenAPI() {
        SecurityScheme securityScheme = new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")
                .description("输入登录后获得的 JWT");

        return new OpenAPI()
                .info(new Info()
                        .title("用户管理系统接口文档")
                        .version("1.0.0")
                        .description("支持 JWT 调试的接口文档")
                        .contact(new Contact()
                                .name("项目开发组")
                                .email("demo@example.com"))
                        .license(new License()
                                .name("Apache 2.0")))
                .components(new Components()
                        .addSecuritySchemes(SECURITY_SCHEME_NAME, securityScheme))
                .addSecurityItem(new SecurityRequirement()
                        .addList(SECURITY_SCHEME_NAME));
    }
}

配置完成后，文档页面会显示认证入口。开发人员输入 JWT 后，调试请求会按照 Bearer 认证方式携带 Authorization 请求头。

注意：将安全方案添加到 OpenAPI 对象表示文档默认要求认证，但它不会替代 Spring Security 的服务端鉴权逻辑。

导出离线文档

Knife4j 的文档管理功能可以导出以下内容：

Markdown 文档。
离线 HTML 文档。
Word 文档。
原始 OpenAPI JSON 文档。

Knife4j 官方导出功能不直接生成 PDF。需要 PDF 时，可以先导出 Markdown 或 HTML，再使用其他工具转换为 PDF。

隐藏不需要展示的接口

使用 @Hidden 可以隐藏控制器或接口：

package com.example.knife4jdemo.controller;

import io.swagger.v3.oas.annotations.Hidden;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Hidden
@RestController
@RequestMapping("/admin")
public class AdminController {

    @PostMapping("/password")
    public String updatePassword() {
        return "密码修改成功";
    }
}

也可以只隐藏单个方法：

@Hidden
@PostMapping("/internal/reset")
public String resetData() {
    return "重置成功";
}

重要说明：@Hidden 只控制接口是否出现在 OpenAPI 文档中，不会阻止客户端访问该接口。敏感接口仍然必须通过 Spring Security、权限校验和网关策略进行保护。

生产环境安全配置

开发环境配置

开发环境可以开启接口文档：

knife4j:
  enable: true
  production: false

生产环境关闭文档

生产环境可以同时关闭 Knife4j 页面、Swagger UI 和 OpenAPI JSON 接口：

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

knife4j:
  enable: false
  production: true

其中：

knife4j.production 用于开启 Knife4j 的生产环境保护策略。
springdoc.api-docs.enabled 用于关闭 OpenAPI JSON 接口。
springdoc.swagger-ui.enabled 用于关闭 Swagger UI。

生产环境是否完全禁用接口文档，应根据项目的网络隔离、权限模型和运维要求决定。

使用 Basic 认证保护文档

在内部测试环境确实需要开放文档时，可以启用 Basic 认证：

knife4j:
  enable: true
  production: false
  basic:
    enable: true
    username: doc_user
    password: ${KNIFE4J_PASSWORD}

不要在代码仓库中直接保存真实密码。示例使用环境变量 KNIFE4J_PASSWORD 注入密码。

Basic 认证只能作为文档访问保护的一部分。生产系统还应结合 HTTPS、网络访问控制、Spring Security 和统一身份认证等措施。

常见问题

页面能够打开，但没有接口

重点检查：

packages-to-scan 是否配置正确。
控制器是否使用了 @RestController。
请求方法是否使用了 @GetMapping、@PostMapping 等映射注解。
控制器是否位于 Spring Boot 默认扫描范围内。
是否错误配置了 paths-to-match。

文档页面返回 `401` 或 `403`

这通常表示请求被安全过滤器拦截。需要在开发环境中按需放行以下资源：

/doc.html
/webjars/**
/v3/api-docs/**
/swagger-ui/**
/swagger-ui.html

是否放行以及如何放行，应以项目实际使用的 Spring Security 版本和权限策略为准。

文档页面返回 `404`

重点检查：

Starter 是否选择正确。
依赖是否下载成功。
是否存在依赖冲突。
是否配置了应用上下文路径。
是否使用 @EnableWebMvc 覆盖了自动配置。
是否自定义了静态资源映射。

注解没有显示在文档中

检查注解导包是否来自 io.swagger.v3.oas.annotations。不要混用旧版 io.swagger.annotations 和 OpenAPI 3 注解。

修改接口后文档没有变化

可以依次尝试：

确认代码已经重新编译并重启应用。
刷新浏览器页面。
清除 Knife4j 页面缓存。
检查当前查看的是否为正确分组。
直接访问 /v3/api-docs，确认后端生成的 OpenAPI JSON 是否已经更新。

总结

Spring Boot 3 集成 Knife4j 的核心流程如下：

使用 JDK 17 或更高版本。
引入 Jakarta 版本的 Knife4j OpenAPI 3 Starter。
通过 springdoc 配置扫描包、分组和 OpenAPI 文档路径。
通过 OpenAPI Bean 设置文档基本信息和认证方案。
使用 @Tag、@Operation、@Parameter 和 @Schema 描述接口。
在开发环境开放文档，在生产环境按安全要求关闭或限制访问。
明确区分“隐藏接口文档”和“保护真实接口”，不能将 @Hidden 当作权限控制手段。

Spring 事务管理

Thu, 30 Jul 2026 11:36:45 GMT

Spring 事务管理

Spring 事务管理相关接口的关系如下：

image-001

事务管理概述

Spring 为 JDBC、JPA、Hibernate、JTA 等不同数据访问技术提供统一的事务编程模型。业务代码主要面向 Spring 的事务抽象，而具体的提交、回滚和资源管理由相应事务管理器完成。

核心接口是 PlatformTransactionManager：

public interface PlatformTransactionManager extends TransactionManager {
    TransactionStatus getTransaction(TransactionDefinition definition)
            throws TransactionException;

    void commit(TransactionStatus status) throws TransactionException;

    void rollback(TransactionStatus status) throws TransactionException;
}

getTransaction() 根据事务定义获取当前事务状态；commit() 和 rollback() 分别负责提交与回滚。

常见事务管理器

JDBC 事务

使用 JDBC 或 JdbcTemplate 时，通常使用 DataSourceTransactionManager。

<bean id="transactionManager"
      class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
    <property name="dataSource" ref="dataSource"/>
</bean>

它通过同一数据源获取的 JDBC Connection 管理事务，并最终调用连接的 commit() 或 rollback()。

JPA 事务

使用 JPA 时，通常使用 JpaTransactionManager。

<bean id="transactionManager"
      class="org.springframework.orm.jpa.JpaTransactionManager">
    <property name="entityManagerFactory" ref="entityManagerFactory"/>
</bean>

JpaTransactionManager 与 JPA 的 EntityManagerFactory、EntityManager 协作管理事务。

Hibernate 事务

直接使用原生 Hibernate SessionFactory 时，可以使用 HibernateTransactionManager。如果项目通过 JPA 使用 Hibernate 实现，则应优先使用 JpaTransactionManager。

<bean id="transactionManager"
      class="org.springframework.orm.hibernate5.HibernateTransactionManager">
    <property name="sessionFactory" ref="sessionFactory"/>
</bean>

JTA 事务

当一个业务操作需要协调多个事务资源时，可以使用 JTA 和 JtaTransactionManager。例如，一个事务同时涉及多个数据库或数据库与消息系统。

<bean id="transactionManager"
      class="org.springframework.transaction.jta.JtaTransactionManager"/>

JTA 的具体配置依赖应用服务器或所使用的事务协调器，不能仅靠一个固定 Bean 配置适配所有环境。

事务属性

TransactionDefinition 用于描述事务策略，主要包含传播行为、隔离级别、超时时间、只读标记和事务名称。

image-002

public interface TransactionDefinition {
    int getPropagationBehavior();

    int getIsolationLevel();

    int getTimeout();

    boolean isReadOnly();

    String getName();
}

事务传播行为

传播行为决定一个带事务的方法被其他事务方法调用时，应加入现有事务、创建新事务，还是禁止事务。

传播行为	含义
`REQUIRED`	默认值。有事务则加入，没有事务则新建事务。
`SUPPORTS`	有事务则加入，没有事务则以非事务方式运行。
`MANDATORY`	必须存在事务，否则抛出异常。
`REQUIRES_NEW`	总是创建新事务；若已有事务，则暂停外层事务。
`NOT_SUPPORTED`	以非事务方式运行；若已有事务，则暂停该事务。
`NEVER`	必须以非事务方式运行；若存在事务，则抛出异常。
`NESTED`	有事务时使用保存点形成嵌套范围；没有事务时行为类似 `REQUIRED`。

`REQUIRED`

多个方法加入同一个物理事务，其中任意参与者把事务标记为仅回滚，最终提交时整个事务都会回滚。

@Transactional(propagation = Propagation.REQUIRED)
public void saveOrder() {
    // 业务逻辑
}

`REQUIRES_NEW`

内层方法使用独立事务，外层事务在内层事务执行期间被挂起。内层事务提交后，即使外层事务随后回滚，内层已提交内容通常不会随之回滚。

@Transactional(propagation = Propagation.REQUIRES_NEW)
public void saveAuditLog() {
    // 独立保存审计日志
}

`NESTED`

NESTED 通常基于同一个物理事务中的 JDBC 保存点实现。内层范围可以回滚到保存点，但它不能像独立事务一样脱离外层事务单独最终提交；外层事务回滚时，嵌套范围也会回滚。

该传播行为依赖事务管理器和底层资源对保存点的支持，常见于 JDBC 资源事务。

事务隔离级别

隔离级别用于控制并发事务之间的数据可见性。

并发事务常见问题

脏读：读取到其他事务尚未提交的数据。
不可重复读：同一事务内两次读取同一行，得到不同值，通常由其他事务更新并提交引起。
幻读：同一事务内按相同条件查询两次，结果集中的行数发生变化，通常由其他事务插入或删除并提交引起。

Spring 隔离级别

隔离级别	含义
`DEFAULT`	使用数据库默认隔离级别。
`READ_UNCOMMITTED`	允许读取未提交数据，可能出现脏读、不可重复读和幻读。
`READ_COMMITTED`	只能读取已提交数据，可避免脏读。
`REPEATABLE_READ`	同一事务内重复读取已读取行时保持一致，可避免脏读和不可重复读。
`SERIALIZABLE`	事务近似串行执行，隔离程度最高，但并发性能通常最低。

不同数据库的锁机制和多版本并发控制实现不同，因此同名隔离级别在具体细节上可能存在差异。

@Transactional(isolation = Isolation.READ_COMMITTED)
public void updateAccount() {
    // 业务逻辑
}

只读事务

只读标记表示该事务主要执行查询操作，事务管理器和数据库可以据此进行优化。

@Transactional(readOnly = true)
public User queryById(Long id) {
    return userMapper.selectById(id);
}

readOnly = true 通常是一种优化提示，不应把它当作绝对的数据库写入安全限制。是否真正禁止写操作取决于事务管理器和数据库实现。

事务超时

事务超时用于限制事务允许执行的最长时间。超时后，事务通常会被标记为回滚。

@Transactional(timeout = 10)
public void importData() {
    // 业务逻辑
}

应避免在事务中执行长时间网络调用、文件处理或人为等待，否则会长期占用数据库连接和锁资源。

回滚规则

Spring 声明式事务默认在抛出 RuntimeException 或 Error 时回滚；对于普通受检异常，默认不回滚。

@Transactional(rollbackFor = Exception.class)
public void transfer() throws Exception {
    // 发生受检异常时也回滚
}

也可以通过 noRollbackFor 指定某些异常不触发回滚。

@Transactional(noRollbackFor = BusinessWarningException.class)
public void execute() {
    // 业务逻辑
}

回滚规则应根据业务语义设置，不建议无差别捕获异常后静默处理。若异常被方法内部捕获且不再抛出，事务拦截器通常无法感知该异常，也就不会按异常自动回滚。

事务状态

TransactionStatus 表示当前事务的运行状态，并提供保存点和仅回滚标记等能力。

public interface TransactionStatus extends TransactionExecution, SavepointManager, Flushable {
    boolean hasSavepoint();

    void flush();
}

常见状态方法包括：

isNewTransaction()：是否为当前调用新建了事务。
hasSavepoint()：是否持有保存点。
setRollbackOnly()：把事务标记为只能回滚。
isRollbackOnly()：事务是否已被标记为回滚。
isCompleted()：事务是否已经完成。

接口的具体方法会随 Spring 版本演进，使用时应以当前项目依赖中的 API 为准。

编程式事务

编程式事务由业务代码明确控制事务边界，适合事务范围需要动态决定或精细控制的场景。它的缺点是事务代码会进入业务逻辑，侵入性较强。

使用 `TransactionTemplate`

TransactionTemplate 是推荐的编程式事务方式之一。

@Service
public class UserService {
    private final TransactionTemplate transactionTemplate;
    private final UserRepository userRepository;

    public UserService(
            TransactionTemplate transactionTemplate,
            UserRepository userRepository) {
        this.transactionTemplate = transactionTemplate;
        this.userRepository = userRepository;
    }

    public Boolean save(User user) {
        return transactionTemplate.execute(status -> {
            try {
                userRepository.insert(user);
                return true;
            } catch (RuntimeException e) {
                status.setRollbackOnly();
                throw e;
            }
        });
    }
}

如果回调抛出运行时异常，事务模板会按规则回滚。只有在需要把异常转换为正常返回值时，才需要显式调用 setRollbackOnly()。

直接使用 `PlatformTransactionManager`

DefaultTransactionDefinition definition = new DefaultTransactionDefinition();
definition.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRED);

TransactionStatus status = transactionManager.getTransaction(definition);
try {
    userRepository.insert(user);
    transactionManager.commit(status);
} catch (RuntimeException e) {
    transactionManager.rollback(status);
    throw e;
}

直接操作事务管理器更灵活，但需要自己保证提交、回滚和异常传播逻辑正确。

声明式事务

声明式事务基于 Spring AOP，通过配置或注解把事务逻辑应用到目标方法，业务代码不需要手动提交和回滚。

XML 配置方式

<bean id="transactionManager"
      class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
    <property name="dataSource" ref="dataSource"/>
</bean>

<tx:advice id="txAdvice" transaction-manager="transactionManager">
    <tx:attributes>
        <tx:method name="query*" read-only="true"/>
        <tx:method name="get*" read-only="true"/>
        <tx:method name="*" propagation="REQUIRED" rollback-for="java.lang.Exception"/>
    </tx:attributes>
</tx:advice>

<aop:config>
    <aop:pointcut id="servicePointcut"
                  expression="execution(* com.example.service..*(..))"/>
    <aop:advisor advice-ref="txAdvice" pointcut-ref="servicePointcut"/>
</aop:config>

需要在根元素中声明 tx 和 aop 命名空间。

注解方式

先启用事务注解：

<tx:annotation-driven transaction-manager="transactionManager"/>

也可以使用 Java 配置：

@Configuration
@EnableTransactionManagement
public class TransactionConfig {
    @Bean
    public PlatformTransactionManager transactionManager(DataSource dataSource) {
        return new DataSourceTransactionManager(dataSource);
    }
}

在业务类或方法上使用 @Transactional：

@Service
public class UserService {
    private final UserDao userDao;

    public UserService(UserDao userDao) {
        this.userDao = userDao;
    }

    @Transactional(rollbackFor = Exception.class)
    public void save(User user) throws Exception {
        userDao.insert(user);
    }
}

类上的注解会作为该类方法的默认事务配置；方法上的注解可以覆盖类级配置。

`@Transactional` 常见失效场景

方法不可代理

在常见代理模式下，事务通常应应用于可被代理调用的公开实例方法。private 方法、静态方法和对象自行创建的方法不会按普通 Spring Bean 代理方式生效。

对象不是 Spring Bean

通过 new 手动创建的对象不受 Spring 容器管理，其 @Transactional 注解不会自动生效。

异常被捕获

@Transactional
public void save() {
    try {
        userDao.insert();
    } catch (Exception e) {
        // 异常被吞掉后，事务拦截器无法按该异常自动回滚。
    }
}

应重新抛出异常，或根据业务需要调用 TransactionAspectSupport.currentTransactionStatus().setRollbackOnly()。

异常类型不匹配

受检异常默认不会触发回滚。需要回滚时，应通过 rollbackFor 明确配置。

使用建议

事务通常放在 Service 层，而不是 Controller 层。
一个事务只覆盖必须保持一致性的数据库操作。
避免在事务中进行长时间远程调用。
查询方法可设置为只读事务。
根据业务语义选择传播行为，不要把所有方法都配置成 REQUIRES_NEW。
对异常进行转换时，应保留原始异常信息，并确保回滚规则仍然生效。

Spring MVC

Thu, 30 Jul 2026 11:35:54 GMT

Spring MVC

image-001

核心执行流程

Spring MVC 处理请求时，主要组件及职责如下：

DispatcherServlet：前端控制器，统一接收请求并协调后续处理流程。
HandlerMapping：根据请求地址查找对应的处理器方法。
HandlerAdapter：以统一方式调用处理器，并完成参数解析等工作。
Handler：实际处理请求的控制器方法。
ModelAndView：同时封装模型数据和逻辑视图名。
ViewResolver：把逻辑视图名解析为具体视图。
View：负责渲染响应内容。

搭建传统 Spring MVC 项目

创建 Maven Web 工程

引入 Spring MVC 依赖。以下版本仅对应原课程示例环境：

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webmvc</artifactId>
    <version>5.2.4.RELEASE</version>
</dependency>

配置 `DispatcherServlet`

在 web.xml 中注册前端控制器：

<servlet>
    <servlet-name>spring</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>classpath:spring-servlet.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
    <servlet-name>spring</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

/ 表示让 DispatcherServlet 处理除容器内部特殊请求之外的大部分请求，同时仍可由默认 Servlet 处理静态资源。通常不建议配置为 /*，因为它可能影响 JSP 转发等容器行为。

创建 Spring MVC 配置文件

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:mvc="http://www.springframework.org/schema/mvc"
       xsi:schemaLocation="
           http://www.springframework.org/schema/beans
           https://www.springframework.org/schema/beans/spring-beans.xsd
           http://www.springframework.org/schema/context
           https://www.springframework.org/schema/context/spring-context.xsd
           http://www.springframework.org/schema/mvc
           https://www.springframework.org/schema/mvc/spring-mvc.xsd">

    <context:component-scan base-package="com.hyxy.controller"/>
    <mvc:annotation-driven/>
</beans>

创建控制器

@Controller
public class TestController {
    @RequestMapping("/test")
    @ResponseBody
    public String test() {
        return "test";
    }
}

启动服务器后访问 /test，响应体中会返回 test。

请求映射

`@RequestMapping`

@RequestMapping 可以修饰类和方法。修饰类时通常表示统一的地址前缀；修饰方法时表示具体请求映射。

常用属性包括：

value 或 path：请求地址。
method：允许的请求方法。
params：要求请求中包含或不包含指定参数。
headers：根据请求头进一步限制映射。
consumes：限制请求体的媒体类型。
produces：声明响应媒体类型。

@Controller
@RequestMapping("/test")
public class TestController {
    @RequestMapping(value = "/add", method = RequestMethod.POST)
    @ResponseBody
    public String add() {
        return "add";
    }
}

在实际项目中，也可使用语义更明确的组合注解，例如 @GetMapping、@PostMapping、@PutMapping 和 @DeleteMapping。

请求参数绑定

绑定简单参数

请求参数名与方法参数名一致时，Spring MVC 可以自动绑定。若编译时未保留参数名，或希望显式指定参数名称，应使用 @RequestParam。

@GetMapping("/user")
@ResponseBody
public String getUser(
        @RequestParam(name = "name") String username,
        @RequestParam(name = "age", required = false, defaultValue = "0") Integer age) {
    return username + ":" + age;
}

使用基本类型接收可选参数时，参数缺失会导致类型转换失败，因此可选数字参数一般使用包装类型。

绑定路径变量

@GetMapping("/add/{name}/{pwd}")
@ResponseBody
public String add(
        @PathVariable("name") String username,
        @PathVariable("pwd") String password) {
    return username + ":" + password;
}

例如访问 http://localhost:8088/mvc/test/add/tom/123，username 的值为 tom，password 的值为 123。

读取请求头和 Cookie

@GetMapping("/header")
@ResponseBody
public String header(
        @RequestHeader("Accept") String accept,
        @CookieValue(value = "username", defaultValue = "rose") String username) {
    return accept + ":" + username;
}

绑定 Java 对象

请求参数名与对象属性名一致时，可以把参数绑定到对象中。

@PostMapping("/emp")
@ResponseBody
public Emp add(Emp emp) {
    return emp;
}

对于关联对象，可使用属性路径传参。例如 Emp 中包含 Dept dept 时，请求参数可写成 dept.deptName=开发部。

public class Emp {
    private String empNo;
    private String empName;
    private Dept dept;

    // getter 和 setter
}

public class Dept {
    private String deptName;

    // getter 和 setter
}

获取 Servlet API 对象

需要访问原始请求或会话时，可直接在控制器方法参数中声明。

@GetMapping("/request-info")
@ResponseBody
public String requestInfo(HttpServletRequest request, HttpSession session) {
    session.setAttribute("method", request.getMethod());
    return request.getMethod();
}

业务代码不应过度依赖 Servlet API。能通过注解和参数绑定完成的场景，应优先使用 Spring MVC 的参数解析机制。

视图跳转与模型数据

返回逻辑视图名

@GetMapping("/books")
public String books(Model model) {
    model.addAttribute("bookList", List.of("Java", "Spring"));
    return "book/list";
}

配合视图解析器时，book/list 会被解析为具体页面路径。

<bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
    <property name="prefix" value="/WEB-INF/views/"/>
    <property name="suffix" value=".jsp"/>
</bean>

返回 `ModelAndView`

@GetMapping("/detail")
public ModelAndView detail() {
    ModelAndView modelAndView = new ModelAndView();
    modelAndView.addObject("name", "Spring MVC");
    modelAndView.setViewName("book/detail");
    return modelAndView;
}

静态资源处理

可以显式配置静态资源映射：

<mvc:annotation-driven/>
<mvc:resources mapping="/html/**" location="/html/"/>

也可使用默认 Servlet 处理未匹配的静态资源：

<mvc:default-servlet-handler/>

前后端分离开发

`@RequestBody`

@RequestBody 会读取请求体，并通过消息转换器把 JSON 转换为 Java 对象。请求头通常应包含 Content-Type: application/json。

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.14.2</version>
</dependency>

@RestController
@RequestMapping("/test")
public class TestController {
    @PostMapping("/emp")
    public Emp save(@RequestBody Emp emp) {
        return emp;
    }
}

image-002

JSON 字段名应与 Java 属性名匹配。字段命名不一致时，可以使用 Jackson 注解进行映射。

`@ResponseBody`

@ResponseBody 表示把方法返回值写入响应体。返回对象时，Spring MVC 会通过消息转换器将其序列化为 JSON；返回字符串时，通常直接写入文本内容。

@GetMapping("/get")
@ResponseBody
public User get() {
    User user = new User();
    user.setUsername("jack");
    user.setPassword("123456");
    return user;
}

`@RestController`

@RestController 相当于类级别的 @Controller 与 @ResponseBody 组合，适合以 JSON 为主要响应内容的控制器。

统一响应对象

public class Result<T> {
    private boolean success;
    private T data;
    private String message;

    public static <T> Result<T> success(T data) {
        Result<T> result = new Result<>();
        result.success = true;
        result.data = data;
        return result;
    }

    public static <T> Result<T> failure(String message) {
        Result<T> result = new Result<>();
        result.success = false;
        result.message = message;
        return result;
    }

    // getter 和 setter
}

跨域请求

浏览器的同源策略会限制脚本访问不同源的资源。源由协议、主机和端口共同确定，任意一项不同都属于跨源请求。

使用 `@CrossOrigin`

@RestController
@RequestMapping("/book")
@CrossOrigin(origins = "http://localhost:8081")
public class BookController {
}

全局配置 CORS

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("http://localhost:8081")
                .allowedMethods("GET", "POST", "PUT", "DELETE")
                .allowedHeaders("*")
                .allowCredentials(true)
                .maxAge(3600);
    }
}

开启凭据时，不能把允许来源简单配置为通配符。生产环境应只开放实际需要的来源、方法和请求头。

前端代理与 Nginx 反向代理

开发环境可以通过前端开发服务器代理接口请求；生产环境通常使用 Nginx 将前端静态资源和后端接口统一到同一站点下。

image-003

image-004

反向代理只改变请求转发方式，不会替代后端自身的鉴权、权限校验和输入校验。

文件上传

配置文件解析器

在传统 Spring MVC 项目中，可配置 CommonsMultipartResolver：

<bean id="multipartResolver"
      class="org.springframework.web.multipart.commons.CommonsMultipartResolver">
    <property name="maxUploadSize" value="5242880"/>
    <property name="defaultEncoding" value="UTF-8"/>
</bean>

<dependency>
    <groupId>commons-fileupload</groupId>
    <artifactId>commons-fileupload</artifactId>
    <version>1.4</version>
</dependency>

表单应使用 POST 请求，并设置 enctype="multipart/form-data"。

编写上传接口

@RestController
public class FileUploadController {
    private static final Path UPLOAD_DIR = Paths.get("D:/Lesson/uploadFile");

    @PostMapping("/upload")
    public Result<String> upload(@RequestParam("file") MultipartFile file) {
        if (file.isEmpty()) {
            return Result.failure("上传文件不能为空");
        }

        String originalName = file.getOriginalFilename();
        String safeName = originalName == null
                ? UUID.randomUUID().toString()
                : Paths.get(originalName).getFileName().toString();

        try {
            Files.createDirectories(UPLOAD_DIR);
            Path target = UPLOAD_DIR.resolve(safeName).normalize();
            if (!target.startsWith(UPLOAD_DIR)) {
                return Result.failure("文件名不合法");
            }

            file.transferTo(target);
            return Result.success(safeName);
        } catch (IOException e) {
            return Result.failure(e.getMessage());
        }
    }
}

不要直接信任客户端提交的原始文件名。实际项目还应检查文件大小、扩展名、MIME 类型和存储权限，并避免把上传目录暴露为可执行目录。

image-005

Spring Boot

Thu, 30 Jul 2026 11:34:35 GMT

Spring Boot

image-001

第一个 Spring Boot 应用

目标是在浏览器访问指定地址时，由服务器返回 Hello World。

创建项目并引入依赖

可以通过 Spring Initializr 创建项目。以下示例使用 Spring Boot 3.3.4，因此运行环境至少需要 Java 17。

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.4</version>
    <relativePath/>
</parent>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

编写控制器

@RestController
public class HelloController {
    @GetMapping("/test")
    public String test() {
        return "Hello World";
    }
}

启动项目后访问 http://localhost:8080/test，浏览器将显示 Hello World。

打包与部署

配置 Maven 插件

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

生成可执行 JAR

在项目根目录执行：

mvn clean package

构建成功后，可在 target 目录找到 JAR 文件。

运行项目

java -jar target/项目名称.jar

Spring Boot 的核心机制

父工程与依赖管理

image-002

spring-boot-starter-parent 提供常用 Maven 配置，并继承 Spring Boot 的依赖管理能力。

image-003

Spring Boot 会统一管理大量常用依赖的版本。引入已被管理的依赖时，通常不需要单独声明版本，从而降低版本冲突的概率。

Starter 场景启动器

spring-boot-starter-web 是 Web 场景启动器，会引入 Spring MVC、JSON 处理和默认嵌入式服务器等相关依赖。

如果需要把默认的 Tomcat 替换为 Jetty，可以排除 Tomcat 并引入 Jetty：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jetty</artifactId>
</dependency>

启动类与 `SpringApplication.run()`

@SpringBootApplication
public class SpringBootDemoApplication {
    public static void main(String[] args) {
        ConfigurableApplicationContext applicationContext =
                SpringApplication.run(SpringBootDemoApplication.class, args);

        System.out.println(applicationContext.getBean(HelloController.class));
    }
}

SpringApplication.run() 会启动 Spring 容器，执行自动配置，并在 Web 项目中启动嵌入式服务器。

`@SpringBootApplication`

@SpringBootApplication 是组合注解，主要包含以下能力：

@SpringBootConfiguration：表明当前类是 Spring Boot 配置类，本质上具有 @Configuration 的作用。
@EnableAutoConfiguration：根据类路径中的依赖、已有 Bean 和配置属性进行自动配置。
@ComponentScan：默认扫描启动类所在包及其子包。

因此，控制器、业务类、配置类等通常应放在启动类所在包或其子包中。若包结构不满足默认扫描范围，需要显式配置扫描路径。

自动配置

自动配置并不是无条件注册所有 Bean。Spring Boot 会结合依赖、配置属性和容器中已有 Bean 判断某项配置是否生效。

例如，引入 Web Starter 后，Spring Boot 会为 Spring MVC 应用配置 DispatcherServlet、请求映射、消息转换器等组件。开发者自己声明同类型 Bean 时，部分自动配置会按条件退让。

配置文件

Spring Boot 默认支持 application.properties 和 application.yml。YAML 通过缩进表示层级，缩进必须使用空格，不能使用制表符。

image-004

person:
  last-name: tom
  age: 20
  married: false
  birth: 1995-03-23
  maps:
    name1: jack
    name2: rose
  friends:
    - zhangsan
    - lisi
  dog:
    name: dog
    age: 2

使用 `@ConfigurationProperties`

@Component
@ConfigurationProperties(prefix = "person")
public class Person {
    private String lastName;
    private Integer age;
    private Boolean married;
    private LocalDate birth;
    private Map<String, String> maps;
    private List<String> friends;
    private Dog dog;

    // getter 和 setter
}

@ConfigurationProperties 适合批量绑定同一前缀下的配置。属性名支持宽松绑定，例如配置中的 last-name 可以绑定到 Java 属性 lastName。

对于配置类，也可以配合 @ConfigurationPropertiesScan 或 @EnableConfigurationProperties 注册，而不必在配置对象上添加 @Component。

`@Value`、`@PropertySource` 与 `@ImportResource`

@Value 适合读取少量独立配置。
@PropertySource 可加载额外的 .properties 文件，但不直接支持 YAML。
@ImportResource 可导入传统 Spring XML 配置。

多环境配置

Spring Boot 使用 Profile 管理不同环境的配置。

多文件方式

application.yml
application-dev.yml
application-test.yml
application-prod.yml

在主配置中激活环境：

spring:
  profiles:
    active: dev

也可以通过启动参数覆盖：

java -jar app.jar --spring.profiles.active=prod

单文件多文档方式

image-005

YAML 可以使用 --- 分隔多个文档，并通过 spring.config.activate.on-profile 指定对应环境。

spring:
  application:
    name: demo

---
spring:
  config:
    activate:
      on-profile: dev
server:
  port: 8080

---
spring:
  config:
    activate:
      on-profile: prod
server:
  port: 80

开发工具与热部署

引入 DevTools 后，类路径发生变化时可以触发应用重启。它属于开发辅助工具，不应作为生产环境部署方案。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

IDE 还需要开启自动编译或手动触发构建，否则修改后的类文件没有更新，DevTools 也不会重启应用。

Lombok 简化实体类

@Data
@NoArgsConstructor
@AllArgsConstructor
@Accessors(chain = true)
@Component
@ConfigurationProperties(prefix = "person")
public class Person {
    private String lastName;
    private Integer age;
    private Boolean married;
    private LocalDate birth;
    private Map<String, String> maps;
    private List<String> friends;
    private Dog dog;
}

Lombok 会在编译阶段生成常用方法。使用时应安装 IDE 插件并开启注解处理，避免编辑器误报。

配置 Spring MVC 拦截器

编写拦截器

Spring Boot 3 使用 jakarta.servlet 包下的 Servlet API。

public class MyInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(
            HttpServletRequest request,
            HttpServletResponse response,
            Object handler) {
        System.out.println("preHandle");
        return true;
    }

    @Override
    public void postHandle(
            HttpServletRequest request,
            HttpServletResponse response,
            Object handler,
            ModelAndView modelAndView) {
        System.out.println("postHandle");
    }
}

注册拦截器

推荐把拦截器本身注册为 Bean，再通过构造器注入到配置类中。

@Configuration
public class MyMvcConfig implements WebMvcConfigurer {
    private final MyInterceptor myInterceptor;

    public MyMvcConfig(MyInterceptor myInterceptor) {
        this.myInterceptor = myInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(myInterceptor)
                .addPathPatterns("/**")
                .excludePathPatterns("/login", "/error");
    }
}

@Component
public class MyInterceptor implements HandlerInterceptor {
    // 拦截逻辑
}

整合 Druid 数据源

使用 Spring Boot 3 对应的 Druid Starter 时，不需要再重复引入普通 druid 依赖。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>druid-spring-boot-3-starter</artifactId>
    <version>1.2.23</version>
</dependency>

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

spring:
  datasource:
    type: com.alibaba.druid.pool.DruidDataSource
    druid:
      url: jdbc:mysql://localhost:3306/java2601?serverTimezone=UTC&characterEncoding=utf8
      username: root
      password: root
      driver-class-name: com.mysql.cj.jdbc.Driver
      max-active: 10
      min-idle: 3
      initial-size: 2
      max-wait: 10000

测试数据源

@SpringBootTest
class SpringBootDemoApplicationTests {
    @Autowired
    private JdbcTemplate jdbcTemplate;

    @Test
    void testJdbcTemplate() {
        List<Map<String, Object>> list =
                jdbcTemplate.queryForList("SELECT * FROM t_user");

        System.out.println(list);
        System.out.println(jdbcTemplate.getDataSource());
    }
}

数据库账号和密码不应提交到公开仓库。实际项目可通过环境变量、外部配置文件或密钥管理服务提供敏感配置。

Spring

Thu, 30 Jul 2026 11:32:31 GMT

Spring

IoC 与依赖注入

IoC 的核心思想

IoC 是控制反转。传统代码通常由对象自己创建依赖对象；使用 Spring 后，对象的创建、配置和依赖关系由 Spring IoC 容器统一管理。

依赖注入是 IoC 的一种具体实现方式。对象只声明自己需要哪些依赖，容器在创建 Bean 时把相应对象注入进去。

例如，Driver 依赖 Vehicle。业务类不再自行执行 new Car()，而是由容器创建 Car，再注入 Driver。

public interface Vehicle {
    void run();
}

public class Car implements Vehicle {
    private String name;

    public void setName(String name) {
        this.name = name;
    }

    @Override
    public void run() {
        System.out.println(name + "正在行驶");
    }
}

public class Driver {
    private String name;
    private Vehicle vehicle;

    public void setName(String name) {
        this.name = name;
    }

    public void setVehicle(Vehicle vehicle) {
        this.vehicle = vehicle;
    }

    public void drive() {
        System.out.println(name + "准备出发");
        vehicle.run();
    }
}

Spring 项目搭建

创建 Maven 工程

在 pom.xml 中引入 spring-context。以下版本仅对应原课程示例环境：

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>5.3.20</version>
</dependency>

创建核心配置文件

在资源目录中创建 applicationContext.xml。

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
           http://www.springframework.org/schema/beans
           https://www.springframework.org/schema/beans/spring-beans.xsd">
</beans>

启动容器

ApplicationContext context =
        new ClassPathXmlApplicationContext("applicationContext.xml");

Driver driver = context.getBean("driver", Driver.class);
driver.drive();

XML 配置 Bean

注册 Bean

<bean id="driver" class="com.hyxy.Driver"/>
<bean id="car" class="com.hyxy.Car"/>

id 是 Bean 在容器中的名称，class 是实现类的全限定类名。

Setter 注入

<bean id="car" class="com.hyxy.Car">
    <property name="name" value="小轿车"/>
</bean>

<bean id="driver" class="com.hyxy.Driver">
    <property name="name" value="老张"/>
    <property name="vehicle" ref="car"/>
</bean>

value 用于注入简单值，ref 用于引用容器中的另一个 Bean。

Setter 注入要求属性存在对应的 Setter 方法。Getter 方法不是完成注入的必要条件，但通常会按 JavaBean 规范一并提供。

构造器注入

public class Driver {
    private final String name;
    private final Vehicle vehicle;

    public Driver(String name, Vehicle vehicle) {
        this.name = name;
        this.vehicle = vehicle;
    }
}

<bean id="driver" class="com.hyxy.Driver">
    <constructor-arg index="0" value="老张"/>
    <constructor-arg index="1" ref="car"/>
</bean>

也可以通过 name 或 type 指定参数，但构造器重载较多时，使用 index 或明确的参数名更容易避免歧义。

构造器注入适合必需依赖，可以保证对象创建完成后处于可用状态。

Bean 作用域

Spring Bean 默认是单例作用域，即同一个容器中，同一 Bean 定义通常只创建一个实例。

<bean id="driver" class="com.hyxy.Driver" scope="singleton"/>

原型作用域会在每次获取 Bean 时创建新对象：

<bean id="driver" class="com.hyxy.Driver" scope="prototype"/>

常用作用域包括：

作用域	含义
`singleton`	每个 Spring 容器中通常只有一个实例。
`prototype`	每次获取时创建一个新实例。
`request`	每个 HTTP 请求一个实例。
`session`	每个 HTTP Session 一个实例。
`application`	每个 Web 应用一个实例。

Web 作用域需要在 Web 应用上下文中使用。

自动装配

XML 按名称装配

<bean id="driver"
      class="com.hyxy.Driver"
      autowire="byName">
    <property name="name" value="老张"/>
</bean>

<bean id="vehicle" class="com.hyxy.Car">
    <property name="name" value="小轿车"/>
</bean>

byName 会根据属性名查找同名 Bean。上例要求 Driver 的属性名为 vehicle。

XML 按类型装配

<bean id="driver"
      class="com.hyxy.Driver"
      autowire="byType">
    <property name="name" value="老张"/>
</bean>

<bean id="car" class="com.hyxy.Car"/>

byType 会根据属性类型查找 Bean。若同类型候选对象有多个，容器无法确定唯一依赖，通常会抛出异常。

XML 自动装配可用于学习原理，但实际项目更常使用构造器注入配合注解或 Java 配置。

循环依赖

循环依赖是指 Bean 之间形成相互依赖，例如 A 依赖 B，同时 B 又依赖 A。

Spring 可以解决部分单例 Bean 的 Setter 或字段注入循环依赖，但不能保证解决所有循环依赖。以下情况通常无法自动解决：

构造器之间相互依赖。
prototype Bean 之间循环依赖。
某些代理、初始化过程或自定义生命周期逻辑导致的循环依赖。

循环依赖通常反映类职责划分不合理，应优先通过重新设计依赖关系解决，而不是依赖容器兜底。

Bean 生命周期

XML 生命周期方法

<bean id="driver"
      class="com.hyxy.Driver"
      init-method="init"
      destroy-method="destroy"/>

public class Driver {
    public void init() {
        System.out.println("初始化 Driver");
    }

    public void destroy() {
        System.out.println("销毁 Driver");
    }
}

容器关闭时会调用单例 Bean 的销毁回调。Spring 不会自动完整管理原型 Bean 的销毁过程，原型对象使用完毕后通常由调用方负责清理资源。

注解生命周期方法

Spring 5 常见项目使用 javax.annotation，Spring 6 和 Spring Boot 3 使用 jakarta.annotation。

@PostConstruct
public void init() {
    System.out.println("初始化 Driver");
}

@PreDestroy
public void destroy() {
    System.out.println("销毁 Driver");
}

初始化流程概览

单例 Bean 的典型初始化流程可概括为：

实例化 Bean。
注入属性和依赖。
调用相关 Aware 接口。
执行 BeanPostProcessor 的前置处理。
执行初始化回调，例如 @PostConstruct、InitializingBean 或自定义 init-method。
执行 BeanPostProcessor 的后置处理，AOP 代理通常在此阶段创建。
Bean 进入可用状态。

容器关闭时，会执行相应销毁回调。

`BeanFactory` 与 `FactoryBean`

`BeanFactory`

BeanFactory 是 Spring IoC 容器的基础接口，负责 Bean 的创建、获取和依赖管理。ApplicationContext 在其基础上增加了事件、国际化、资源加载等功能。

`FactoryBean`

FactoryBean<T> 本身是一个 Bean，但调用方通过普通 Bean 名称获取到的通常是它生产的对象。

public class SqlSessionFactoryBean implements FactoryBean<SqlSessionFactory> {
    private String configLocation;

    public void setConfigLocation(String configLocation) {
        this.configLocation = configLocation;
    }

    @Override
    public SqlSessionFactory getObject() throws Exception {
        try (InputStream inputStream =
                     Resources.getResourceAsStream(configLocation)) {
            return new SqlSessionFactoryBuilder().build(inputStream);
        }
    }

    @Override
    public Class<?> getObjectType() {
        return SqlSessionFactory.class;
    }

    @Override
    public boolean isSingleton() {
        return true;
    }
}

<bean id="sqlSessionFactory"
      class="com.hyxy.SqlSessionFactoryBean">
    <property name="configLocation" value="mybatis-config.xml"/>
</bean>

获取 sqlSessionFactory 时得到的是 FactoryBean 生产的对象；若要获取工厂 Bean 本身，需要在名称前加 &。

Bean 注册方式

Spring 常见的 Bean 注册方式包括 XML、组件扫描和 Java 配置。

XML 注册

<bean id="car" class="com.hyxy.Car"/>

XML 适合集中查看配置，也便于注册无法修改源码的第三方类，但配置量较大时会比较繁琐。

注解与组件扫描

先在配置文件中开启扫描：

<context:component-scan base-package="com.hyxy"/>

再用组件注解标记类：

@Component
public class Car {
}

常用分层注解包括：

@Controller：控制层组件。
@Service：业务层组件。
@Repository：数据访问层组件。
@Component：通用组件。

这些注解都能把类注册为 Spring Bean，分层名称主要用于表达职责；部分注解还可能参与框架的异常转换等机制。

依赖注入注解

`@Autowired`

@Autowired 主要按类型查找依赖。若存在多个同类型 Bean，可结合 @Qualifier 或 @Primary 消除歧义。

推荐使用构造器注入：

@Service
public class DriverService {
    private final Vehicle vehicle;

    public DriverService(@Qualifier("car") Vehicle vehicle) {
        this.vehicle = vehicle;
    }
}

只有一个构造器时，通常可以省略构造器上的 @Autowired。

`@Qualifier`

@Component("car")
public class Car implements Vehicle {
}

@Component("bus")
public class Bus implements Vehicle {
}

@Service
public class DriverService {
    private final Vehicle vehicle;

    public DriverService(@Qualifier("bus") Vehicle vehicle) {
        this.vehicle = vehicle;
    }
}

`@Primary`

@Component
@Primary
public class Car implements Vehicle {
}

同类型候选 Bean 有多个时，@Primary 标记的 Bean 会作为默认选择。

`@Resource`

@Resource 属于 Jakarta 或 Java 标准注解，通常先按名称匹配，再按类型匹配。它可以通过 name 显式指定 Bean 名称。

@Resource(name = "car")
private Vehicle vehicle;

`@Value`

@Value 可注入简单配置值或 Spring 表达式。

@Value("${car.name:默认车辆}")
private String carName;

复杂配置对象更适合使用 @ConfigurationProperties。

`@Scope`

@Component
@Scope("prototype")
public class Driver {
}

Java 配置

定义配置类

@Configuration
public class MyConfig {
    @Bean
    public Car car() {
        Car car = new Car();
        car.setName("小轿车");
        return car;
    }

    @Bean
    @Scope("prototype")
    public Driver driver(Car car) {
        Driver driver = new Driver();
        driver.setName("老张");
        driver.setVehicle(car);
        return driver;
    }
}

@Configuration 表明该类是配置类，@Bean 方法的返回对象会注册到容器中。方法参数会由容器自动注入。

通过方法参数表达依赖比在方法内部直接调用其他 @Bean 方法更清晰，也更容易测试。

启动 Java 配置容器

ApplicationContext context =
        new AnnotationConfigApplicationContext(MyConfig.class);

Driver driver = context.getBean(Driver.class);
driver.drive();

代理模式

代理模式包含目标对象、代理对象和双方共同遵循的抽象契约。代理对象在调用目标方法前后增加通用逻辑，例如日志、权限校验或事务管理。

静态代理

public interface HouseService {
    void rentHouse();
}

public class Owner implements HouseService {
    @Override
    public void rentHouse() {
        System.out.println("签合同并收款");
    }
}

public class Agent implements HouseService {
    private final HouseService target;

    public Agent(HouseService target) {
        this.target = target;
    }

    @Override
    public void rentHouse() {
        System.out.println("寻找房源并协商价格");
        target.rentHouse();
    }
}

静态代理需要为不同目标类型编写对应代理类，重复代码较多。

JDK 动态代理

JDK 动态代理基于接口创建代理对象。

HouseService target = new Owner();

HouseService proxy = (HouseService) Proxy.newProxyInstance(
        target.getClass().getClassLoader(),
        target.getClass().getInterfaces(),
        (proxyObject, method, args) -> {
            System.out.println("调用前处理");
            try {
                return method.invoke(target, args);
            } finally {
                System.out.println("调用后处理");
            }
        }
);

proxy.rentHouse();

CGLIB 动态代理

CGLIB 通过生成目标类的子类创建代理，不要求目标类实现接口。目标类不能是 final，需要代理的方法也不能是 final。

public class DaoMethodInterceptor implements MethodInterceptor {
    @Override
    public Object intercept(
            Object proxy,
            Method method,
            Object[] args,
            MethodProxy methodProxy) throws Throwable {
        System.out.println("开启事务");
        try {
            Object result = methodProxy.invokeSuper(proxy, args);
            System.out.println("提交事务");
            return result;
        } catch (Throwable e) {
            System.out.println("回滚事务");
            throw e;
        }
    }
}

Enhancer enhancer = new Enhancer();
enhancer.setSuperclass(EmpDao.class);
enhancer.setCallback(new DaoMethodInterceptor());

EmpDao empDao = (EmpDao) enhancer.create();
empDao.save();

不要使用已经过时的 Class.newInstance()。需要通过反射创建对象时，应使用 getDeclaredConstructor().newInstance()。

AOP

AOP 是面向切面编程，用于把日志、事务、权限等横切逻辑从业务代码中分离出来。

常用术语

连接点：程序执行过程中可被增强的位置，例如方法调用。
切入点：用于筛选需要增强的连接点。
通知：在目标方法前后执行的增强逻辑。
切面：切入点和通知的组合。
目标对象：被增强的业务对象。
代理对象：应用增强逻辑后的对象。

引入依赖

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-aspects</artifactId>
    <version>5.3.20</version>
</dependency>

定义切面

@Aspect
@Component
public class LogAspect {
    @Pointcut("execution(* com.hyxy.service..*(..))")
    public void serviceMethod() {
    }

    @Before("serviceMethod()")
    public void before() {
        System.out.println("执行方法前记录日志");
    }

    @AfterReturning(pointcut = "serviceMethod()", returning = "result")
    public void afterReturning(Object result) {
        System.out.println("方法正常返回：" + result);
    }

    @AfterThrowing(pointcut = "serviceMethod()", throwing = "exception")
    public void afterThrowing(Throwable exception) {
        System.out.println("方法发生异常：" + exception.getMessage());
    }

    @After("serviceMethod()")
    public void after() {
        System.out.println("方法结束");
    }
}

开启注解 AOP：

<aop:aspectj-autoproxy/>

@After 类似 finally，无论方法正常返回还是抛出异常都会执行；只有正常返回时才执行 @AfterReturning。

Spring 事务概述

Spring 声明式事务基于 AOP。常用事务属性包括传播行为、隔离级别、超时、只读和回滚规则。

常见传播行为：

传播行为	含义
`REQUIRED`	有事务则加入，没有事务则创建。
`REQUIRES_NEW`	总是创建新事务，并暂停当前事务。
`SUPPORTS`	有事务则加入，没有事务则非事务运行。
`NESTED`	在支持保存点的环境中使用嵌套事务范围。

@Service
public class UserService {
    @Transactional(rollbackFor = Exception.class)
    public void saveUser(User user) throws Exception {
        // 数据库操作
    }
}

默认情况下，Spring 对 RuntimeException 和 Error 回滚，对普通受检异常不自动回滚。需要对受检异常回滚时，应配置 rollbackFor。

Spring 与 MyBatis 整合

整合目标是由 Spring 管理数据源、SqlSessionFactory、Mapper 代理和事务。

Maven 依赖

以下版本为原课程示例组合：

<properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>5.3.20</version>
    </dependency>

    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-jdbc</artifactId>
        <version>5.3.20</version>
    </dependency>

    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-tx</artifactId>
        <version>5.3.20</version>
    </dependency>

    <dependency>
        <groupId>org.mybatis</groupId>
        <artifactId>mybatis</artifactId>
        <version>3.5.1</version>
    </dependency>

    <dependency>
        <groupId>org.mybatis</groupId>
        <artifactId>mybatis-spring</artifactId>
        <version>2.0.7</version>
    </dependency>

    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <version>8.0.33</version>
    </dependency>

    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>druid</artifactId>
        <version>1.2.23</version>
    </dependency>
</dependencies>

数据库配置

jdbc.driverClassName=com.mysql.cj.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/java2601?serverTimezone=UTC&characterEncoding=utf8
jdbc.username=root
jdbc.password=root
jdbc.maxActive=300
jdbc.initialSize=2
jdbc.maxWait=60000
jdbc.minIdle=1

Spring 配置

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:tx="http://www.springframework.org/schema/tx"
       xmlns:mybatis-spring="http://mybatis.org/schema/mybatis-spring"
       xsi:schemaLocation="
           http://www.springframework.org/schema/beans
           https://www.springframework.org/schema/beans/spring-beans.xsd
           http://www.springframework.org/schema/context
           https://www.springframework.org/schema/context/spring-context.xsd
           http://www.springframework.org/schema/tx
           https://www.springframework.org/schema/tx/spring-tx.xsd
           http://mybatis.org/schema/mybatis-spring
           http://mybatis.org/schema/mybatis-spring.xsd">

    <context:property-placeholder location="classpath:db.properties"/>
    <context:component-scan base-package="com.hyxy"/>

    <bean id="dataSource" class="com.alibaba.druid.pool.DruidDataSource">
        <property name="driverClassName" value="${jdbc.driverClassName}"/>
        <property name="url" value="${jdbc.url}"/>
        <property name="username" value="${jdbc.username}"/>
        <property name="password" value="${jdbc.password}"/>
        <property name="maxActive" value="${jdbc.maxActive}"/>
        <property name="initialSize" value="${jdbc.initialSize}"/>
        <property name="maxWait" value="${jdbc.maxWait}"/>
        <property name="minIdle" value="${jdbc.minIdle}"/>
    </bean>

    <bean id="sqlSessionFactory"
          class="org.mybatis.spring.SqlSessionFactoryBean">
        <property name="dataSource" ref="dataSource"/>
        <property name="mapperLocations"
                  value="classpath*:com/hyxy/mapper/*.xml"/>
        <property name="typeAliasesPackage" value="com.hyxy.po"/>
    </bean>

    <mybatis-spring:scan base-package="com.hyxy.mapper"/>

    <bean id="transactionManager"
          class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
        <property name="dataSource" ref="dataSource"/>
    </bean>

    <tx:annotation-driven transaction-manager="transactionManager"/>
</beans>

SqlSessionFactoryBean 负责创建 MyBatis 的 SqlSessionFactory，Mapper 扫描器会为接口创建代理并注册到 Spring 容器。

Mapper 与 Service

public interface UserMapper {
    int insert(User user);
}

@Service
public class UserService {
    private final UserMapper userMapper;

    public UserService(UserMapper userMapper) {
        this.userMapper = userMapper;
    }

    @Transactional(rollbackFor = Exception.class)
    public void save(User user) throws Exception {
        userMapper.insert(user);
    }
}

业务层只需要注入 Mapper，不应自行创建 SqlSession。事务由 Spring 管理时，也不应在 Mapper 或 Service 中手动调用 commit()。

MyBatis 全套知识体系完全指南

Thu, 30 Jul 2026 11:31:21 GMT

MyBatis 全套知识体系完全指南

本文档全面覆盖 MyBatis 的理论知识与指令操作，从基础概念到高级实战，无遗漏。

MyBatis 概述

什么是 MyBatis

MyBatis 是一款 SQL 映射与持久层框架。它允许开发者自行编写 SQL，并负责参数绑定、结果映射、事务协作等重复工作。MyBatis 常被称为“半自动 ORM”，但它不会像全自动 ORM 框架那样根据实体关系自动生成全部 SQL。

MyBatis 前身是 iBatis，2010 年由 Apache 迁移到 Google Code 并更名为 MyBatis，后迁移至 GitHub。

MyBatis 的定位

特性	JDBC	MyBatis	Hibernate (JPA)
SQL 控制	完全手动	半自动（手写 SQL，自动映射）	全自动（自动生成 SQL）
学习成本	高（大量样板代码）	中	高
灵活性	最高	高	较低
性能可控	是	是	较难（需调优）
数据库移植性	差	中	高
适合场景	—	复杂 SQL、高性能需求	快速开发、简单 CRUD

MyBatis 的核心特性

 ┌────────────────────────────────────────────────────┐
 │              MyBatis 核心特性                        │
 ├──────────────┬──────────────┬─────────────────────┤
 │   SQL 映射    │  动态 SQL    │  高级映射            │
 ├──────────────┼──────────────┼─────────────────────┤
 │ XML/注解配置  │ 条件拼接      │ 一对一/一对多/多对多  │
 │ 参数自动绑定  │ 循环遍历      │ 嵌套结果/嵌套查询     │
 │ 结果自动映射  │ SQL 片段复用  │ 鉴别器（discriminator）│
 ├──────────────┼──────────────┼─────────────────────┤
│   缓存机制    │  插件机制     │  扩展能力            │
├──────────────┼──────────────┼─────────────────────┤
│ 一级缓存      │ 拦截器        │ TypeHandler          │
│ 二级缓存      │ 分页插件      │ ObjectFactory        │
│ 第三方缓存    │ SQL 审计      │ 语言驱动             │
└──────────────┴──────────────┴─────────────────────┘

MyBatis 架构

                     ┌─────────────────┐
                     │   应用程序层      │
                     │  (Service/DAO)   │
                     └────────┬────────┘
                              │
                     ┌────────▼────────┐
                     │  SqlSession 接口  │
                     │ (selectOne/list  │
                     │  insert/update   │
                    │  delete/commit)  │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  Executor 执行器  │
                    │  (Simple/Reuse   │
                    │   Batch)         │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
     ┌────────▼───┐  ┌──────▼─────┐  ┌────▼────────┐
     │ Statement  │  │ Parameter  │  │  ResultSet  │
     │ Handler    │  │ Handler    │  │  Handler    │
     │(SQL预处理)  │  │(参数绑定)   │  │(结果映射)    │
     └────────┬───┘  └────────────┘  └─────────────┘
              │
     ┌────────▼───┐
     │   JDBC     │
     │  数据库     │
     └────────────┘

MyBatis 版本

MyBatis 3 是目前课程和实际项目中常用的主版本系列。本文示例使用 3.5.15，版本号仅用于保证示例可复现；实际项目应以依赖管理中确定的版本为准，并在升级时查阅对应版本的发布说明。

快速入门

示例数据库

本文档统一使用以下示例数据库：

 -- 部门表
 CREATE TABLE dept (
     dept_id   INT PRIMARY KEY AUTO_INCREMENT,
     dept_name VARCHAR(50) NOT NULL,
     location  VARCHAR(100)
 );
 -- 员工表
 CREATE TABLE emp (
    emp_id     INT PRIMARY KEY AUTO_INCREMENT,
    emp_name   VARCHAR(50) NOT NULL,
    email      VARCHAR(100),
    salary     DECIMAL(10,2),
    dept_id    INT,
    hire_date  DATE,
    status     TINYINT DEFAULT 1,  -- 1:在职 0:离职
    FOREIGN KEY (dept_id) REFERENCES dept(dept_id)
);
-- 项目表（多对多）
CREATE TABLE project (
    project_id   INT PRIMARY KEY AUTO_INCREMENT,
    project_name VARCHAR(100) NOT NULL,
    budget       DECIMAL(12,2)
);
-- 员工-项目关联表（多对多）
CREATE TABLE emp_project (
    emp_id     INT,
    project_id INT,
    role       VARCHAR(50),
    PRIMARY KEY (emp_id, project_id),
    FOREIGN KEY (emp_id) REFERENCES emp(emp_id),
    FOREIGN KEY (project_id) REFERENCES project(project_id)
);

Maven 依赖

 <!-- MyBatis 核心 -->
 <dependency>
     <groupId>org.mybatis</groupId>
     <artifactId>mybatis</artifactId>
     <version>3.5.15</version>
 </dependency>
 <!-- MySQL 驱动 -->
 <dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>8.3.0</version>
</dependency>
<!-- 日志 -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>2.0.12</version>
</dependency>
<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.4.14</version>
</dependency>
<!-- Lombok -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.30</version>
    <scope>provided</scope>
</dependency>

实体类

 package com.example.entity;
 import lombok.Data;
 import java.math.BigDecimal;
 import java.time.LocalDate;
 import java.util.List;
 @Data
 public class Emp {
    private Integer empId;
    private String empName;
    private String email;
    private BigDecimal salary;
    private Integer deptId;
    private LocalDate hireDate;
    private Integer status;
    // 关联对象
    private Dept dept;
    // 关联集合（多对多）
    private List<Project> projects;
}
@Data
public class Dept {
    private Integer deptId;
    private String deptName;
    private String location;
    // 关联集合（一对多）
    private List<Emp> emps;
}
@Data
public class Project {
    private Integer projectId;
    private String projectName;
    private BigDecimal budget;
    private List<Emp> emps;
}

mybatis-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
        "https://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
     <!-- 属性配置 -->
     <properties resource="db.properties"/>
     <!-- 设置 -->
    <settings>
        <setting name="mapUnderscoreToCamelCase" value="true"/>
        <setting name="cacheEnabled" value="true"/>
        <setting name="lazyLoadingEnabled" value="true"/>
        <setting name="defaultExecutorType" value="REUSE"/>
        <setting name="logImpl" value="SLF4J"/>
    </settings>
    <!-- 别名 -->
    <typeAliases>
        <package name="com.example.entity"/>
    </typeAliases>
    <!-- 环境配置 -->
    <environments default="development">
        <environment id="development">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <property name="driver" value="${jdbc.driver}"/>
                <property name="url" value="${jdbc.url}"/>
                <property name="username" value="${jdbc.username}"/>
                <property name="password" value="${jdbc.password}"/>
            </dataSource>
        </environment>
    </environments>
    <!-- 映射器 -->
    <mappers>
        <package name="com.example.mapper"/>
    </mappers>
</configuration>

db.properties

jdbc.driver=com.mysql.cj.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/mydb?
    useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=UTF-8
jdbc.username=root
jdbc.password=root123

Mapper 接口

 package com.example.mapper;
 import com.example.entity.Emp;
 import java.util.List;
 public interface EmpMapper {
     // 查询所有员工
     List<Emp> selectAll();
    // 根据 ID 查询
    Emp selectById(Integer empId);
    // 插入
    int insert(Emp emp);
    // 更新
    int update(Emp emp);
    // 删除
    int deleteById(Integer empId);
}

Mapper XML

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
         "https://mybatis.org/dtd/mybatis-3-mapper.dtd">
 <mapper namespace="com.example.mapper.EmpMapper">
     <select id="selectAll" resultType="Emp">
         SELECT * FROM emp
     </select>
    <select id="selectById" resultType="Emp" parameterType="int">
        SELECT * FROM emp WHERE emp_id = #{empId}
    </select>
    <insert id="insert" parameterType="Emp">
        INSERT INTO emp (emp_name, email, salary, dept_id, hire_date, status)
        VALUES (#{empName}, #{email}, #{salary}, #{deptId}, #{hireDate}, #{status})
    </insert>
    <update id="update" parameterType="Emp">
        UPDATE emp SET
            emp_name = #{empName},
            email = #{email},
            salary = #{salary},
            dept_id = #{deptId},
            status = #{status}
        WHERE emp_id = #{empId}
    </update>
    <delete id="deleteById" parameterType="int">
        DELETE FROM emp WHERE emp_id = #{empId}
    </delete>
</mapper>

工具类

 package com.example.util;
 import org.apache.ibatis.io.Resources;
 import org.apache.ibatis.session.SqlSession;
 import org.apache.ibatis.session.SqlSessionFactory;
 import org.apache.ibatis.session.SqlSessionFactoryBuilder;
 import java.io.InputStream;
 public class MyBatisUtil {
    private static final SqlSessionFactory sqlSessionFactory;
    static {
        try {
            String resource = "mybatis-config.xml";
            InputStream inputStream = Resources.getResourceAsStream(resource);
            sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);
        } catch (Exception e) {
            throw new RuntimeException("MyBatis 初始化失败", e);
        }
    }
    public static SqlSession getSqlSession() {
        return sqlSessionFactory.openSession();
    }
    public static SqlSession getSqlSession(boolean autoCommit) {
        return sqlSessionFactory.openSession(autoCommit);
    }
}

测试

public class MyBatisTest {
    @Test
    public void testSelectAll() {
        try (SqlSession session = MyBatisUtil.getSqlSession()) {
            EmpMapper mapper = session.getMapper(EmpMapper.class);
             List<Emp> emps = mapper.selectAll();
             emps.forEach(System.out::println);
         }
    }
    @Test
    public void testInsert() {
        try (SqlSession session = MyBatisUtil.getSqlSession()) {
            EmpMapper mapper = session.getMapper(EmpMapper.class);
            Emp emp = new Emp();
            emp.setEmpName("张三");
            emp.setEmail("zhangsan@example.com");
            emp.setSalary(new BigDecimal("15000"));
            emp.setDeptId(1);
            emp.setHireDate(LocalDate.now());
            emp.setStatus(1);
            int rows = mapper.insert(emp);
            session.commit();  // 必须手动提交
            System.out.println("插入行数: " + rows + ", 主键: " + emp.getEmpId());
        }
    }
}

核心配置文件（mybatis-config.xml）

完整配置结构

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
         "https://mybatis.org/dtd/mybatis-3-config.dtd">
 <configuration>
     <!-- 1. 属性：引入外部 properties 文件 -->
     <properties resource="db.properties">
         <!-- 也可以在这里定义默认属性 -->
         <property name="username" value="root"/>
    </properties>
    <!-- 2. 设置：全局行为配置 -->
    <settings>
        <!-- 驼峰命名自动映射（emp_name → empName） -->
        <setting name="mapUnderscoreToCamelCase" value="true"/>
        <!-- 二级缓存开关 -->
        <setting name="cacheEnabled" value="true"/>
        <!-- 延迟加载开关 -->
        <setting name="lazyLoadingEnabled" value="true"/>
        <!-- 是否按需加载（3.4.2+默认true） -->
        <setting name="aggressiveLazyLoading" value="false"/>
        <!-- 延迟加载触发方法 -->
        <setting name="lazyLoadTriggerMethods"
     value="equals,clone,hashCode,toString"/>
        <!-- 默认执行器类型 -->
        <setting name="defaultExecutorType" value="REUSE"/>
        <!-- 默认语句超时（秒） -->
        <setting name="defaultStatementTimeout" value="30"/>
        <!-- 默认获取大小 -->
        <setting name="defaultFetchSize" value="100"/>
        <!-- 本地缓存范围 -->
        <setting name="localCacheScope" value="SESSION"/>
        <!-- 默认事务隔离级别 -->
        <setting name="defaultTransactionIsolationLevel" value="READ_COMMITTED"/>
        <!-- 日志实现 -->
        <setting name="logImpl" value="SLF4J"/>
        <!-- 代理工厂（CGLIB/JAVASSIST） -->
        <setting name="proxyFactory" value="JAVASSIST"/>
        <!-- 多结果集 -->
        <setting name="multipleResultSetsEnabled" value="true"/>
        <!-- 列名标签前缀 -->
        <setting name="useColumnLabel" value="true"/>
        <!-- 使用生成的主键 -->
        <setting name="useGeneratedKeys" value="false"/>
        <!-- 自动映射行为 -->
        <setting name="autoMappingBehavior" value="PARTIAL"/>
        <!-- 自动映射未知列行为 -->
        <setting name="autoMappingUnknownColumnBehavior" value="WARNING"/>
        <!-- 返回行数上限 -->
        <setting name="safeRowBoundsEnabled" value="false"/>
        <!-- 安全的 ResultHandler -->
        <setting name="safeResultHandlerEnabled" value="true"/>
        <!-- 指定 MyBatis 语言驱动 -->
        <setting name="defaultScriptingLanguage"
     value="org.apache.ibatis.scripting.xmltags.XMLLanguageDriver"/>
        <!-- 枚举类型默认处理器 -->
        <setting name="defaultEnumTypeHandler"
     value="org.apache.ibatis.type.EnumTypeHandler"/>
        <!-- NULL 值的 JDBC 类型 -->
        <setting name="jdbcTypeForNull" value="OTHER"/>
    </settings>
    <!-- 3. 类型别名 -->
    <typeAliases>
        <!-- 单个类配置 -->
        <typeAlias type="com.example.entity.Emp" alias="Emp"/>
        <!-- 包扫描（默认用类名首字母小写） -->
        <package name="com.example.entity"/>
    </typeAliases>
    <!-- 4. 类型处理器 -->
    <typeHandlers>
        <typeHandler handler="com.example.handler.StringListTypeHandler"/>
        <package name="com.example.handler"/>
     </typeHandlers>
     <!-- 5. 对象工厂 -->
     <objectFactory type="com.example.factory.CustomObjectFactory">
         <property name="someProperty" value="100"/>
     </objectFactory>
     <!-- 6. 插件（拦截器） -->
     <plugins>
         <plugin interceptor="com.example.plugin.MyPagePlugin">
             <property name="dialect" value="mysql"/>
         </plugin>
     </plugins>
     <!-- 7. 环境配置 -->
     <environments default="development">
         <environment id="development">
             <transactionManager type="JDBC"/>
             <dataSource type="POOLED">
                 <property name="driver" value="${jdbc.driver}"/>
                 <property name="url" value="${jdbc.url}"/>
                 <property name="username" value="${jdbc.username}"/>
                 <property name="password" value="${jdbc.password}"/>
                 <!-- 连接池配置 -->
                 <property name="poolMaximumActiveConnections" value="10"/>
                 <property name="poolMaximumIdleConnections" value="5"/>
                 <property name="poolMaximumCheckoutTime" value="20000"/>
                 <property name="poolTimeToWait" value="20000"/>
                <property name="poolPingEnabled" value="true"/>
                <property name="poolPingQuery" value="SELECT 1"/>
                <property name="poolPingConnectionsNotUsedFor" value="3600000"/>
            </dataSource>
        </environment>
        <environment id="production">
            <transactionManager type="MANAGED"/>
            <dataSource type="JNDI">
                <property name="initialContext" value="java:comp/env"/>
                <property name="dataSource" value="jdbc/myDataSource"/>
            </dataSource>
        </environment>
    </environments>
    <!-- 8. 数据库厂商标识 -->
    <databaseIdProvider type="DB_VENDOR">
        <property name="MySQL" value="mysql"/>
        <property name="Oracle" value="oracle"/>
        <property name="PostgreSQL" value="pg"/>
    </databaseIdProvider>
    <!-- 9. 映射器 -->
    <mappers>
        <!-- 方式一：资源路径 -->
        <mapper resource="mapper/EmpMapper.xml"/>
        <!-- 方式二：URL -->
        <mapper url="file:///var/mappers/EmpMapper.xml"/>
        <!-- 方式三：接口类 -->
        <mapper class="com.example.mapper.EmpMapper"/>
        <!-- 方式四：包扫描 -->
        <package name="com.example.mapper"/>
    </mappers>
</configuration>

配置元素顺序

mybatis-config.xml 的顶层元素必须按下列顺序出现。没有使用的元素可以省略，但不能随意交换顺序。

1. properties
2. settings
3. typeAliases
4. typeHandlers
5. objectFactory
6. objectWrapperFactory
7. reflectorFactory
8. plugins
9. environments
10. databaseIdProvider
11. mappers

常用 Settings 详解

设置项	可选值	默认值	说明
`cacheEnabled`	`true`、`false`	`true`	是否全局启用映射器二级缓存
`lazyLoadingEnabled`	`true`、`false`	`false`	是否启用延迟加载
`aggressiveLazyLoading`	`true`、`false`	`false`	是否由任意方法调用触发对象的全部延迟属性加载
`mapUnderscoreToCamelCase`	`true`、`false`	`false`	是否将下划线命名自动映射为驼峰命名
`useGeneratedKeys`	`true`、`false`	`false`	是否允许 JDBC 使用自动生成主键
`defaultExecutorType`	`SIMPLE`、`REUSE`、`BATCH`	`SIMPLE`	默认执行器类型
`defaultStatementTimeout`	正整数	未设置	SQL 执行超时时间，单位为秒
`localCacheScope`	`SESSION`、`STATEMENT`	`SESSION`	一级缓存作用域
`jdbcTypeForNull`	JDBC 类型	`OTHER`	为 `null` 参数指定 JDBC 类型
`logImpl`	日志实现类	自动检测	指定 MyBatis 使用的日志实现
`autoMappingBehavior`	`NONE`、`PARTIAL`、`FULL`	`PARTIAL`	自动映射级别

三种数据源类型

type	说明	适用场景
UNPOOLED	每次请求打开/关闭连接	简单应用
POOLED	连接池	大多数应用（推荐）
JNDI	从 JNDI 获取数据源	应用服务器（Tomcat 等）

两种事务管理器

type	说明	适用场景
JDBC	直接使用 JDBC 的 commit/rollback	独立应用
MANAGED	容器管理事务（不提交/回滚）	应用服务器、Spring

类型别名

MyBatis 内置的常用别名：

别名	Java 类型
_int	int
int	Integer
_long	long
long	Long
_boolean	boolean
boolean	Boolean
string	String
integer	Integer
date	Date
decimal	BigDecimal
object	Object
map	Map
hashmap	HashMap
list	List
arraylist	ArrayList

SqlSession 与映射器接口

SqlSession 生命周期

 SqlSessionFactoryBuilder  →  一次创建后丢弃（方法局部变量）
         │
         ▼
 SqlSessionFactory          →  应用级别（单例，全局唯一）
         │
         ▼
 SqlSession                →  方法/请求级别（非线程安全）
         │
         ▼
Mapper 接口实例            →  SqlSession 级别

SqlSession 核心方法

 // 查询
 <T> T selectOne(String statement);
 <T> T selectOne(String statement, Object parameter);
 <E> List<E> selectList(String statement);
 <E> List<E> selectList(String statement, Object parameter);
 <E> List<E> selectList(String statement, Object parameter, RowBounds rowBounds);
 <K, V> Map<K, V> selectMap(String statement, String mapKey);
 <K, V> Map<K, V> selectMap(String statement, Object parameter, String mapKey);
// 游标查询
<T> Cursor<T> selectCursor(String statement);
// 插入
int insert(String statement);
int insert(String statement, Object parameter);
// 更新
int update(String statement);
int update(String statement, Object parameter);
// 删除
int delete(String statement);
int delete(String statement, Object parameter);
// 事务
void commit();
void commit(boolean force);
void rollback();
void rollback(boolean force);
// 批量
void flushStatements();
// 关闭
void close();
// 清除缓存
void clearCache();
// 获取配置
Configuration getConfiguration();
// 获取映射器
<T> T getMapper(Class<T> type);
// 获取连接
Connection getConnection();

两种使用方式

方式一：通过命名空间直接调用

SqlSession session = MyBatisUtil.getSqlSession();
List<Emp> emps = session.selectList("com.example.mapper.EmpMapper.selectAll");
session.close();

方式二：通过 Mapper 接口调用（推荐）

SqlSession session = MyBatisUtil.getSqlSession();
EmpMapper mapper = session.getMapper(EmpMapper.class);
List<Emp> emps = mapper.selectAll();
session.close();

推荐方式二：类型安全、IDE 提示、编译期检查。

三种执行器

执行器	说明	适用场景
Simple	每次执行创建新 Statement	默认
Reuse	复用 Statement	多次相同 SQL
Batch	批量执行	批量 INSERT/UPDATE

// 指定执行器
SqlSession session = sqlSessionFactory.openSession(ExecutorType.BATCH);

事务管理

 // 手动提交（默认）
 SqlSession session = sqlSessionFactory.openSession();  // autoCommit = false
 try {
     EmpMapper mapper = session.getMapper(EmpMapper.class);
     mapper.insert(emp);
     session.commit();   // 手动提交
 } catch (Exception e) {
     session.rollback(); // 回滚
 } finally {
    session.close();
}
// 自动提交
SqlSession session = sqlSessionFactory.openSession(true);  // autoCommit = true
// try-with-resources（推荐）
try (SqlSession session = sqlSessionFactory.openSession()) {
    EmpMapper mapper = session.getMapper(EmpMapper.class);
    mapper.insert(emp);
    session.commit();
}

映射器文件（Mapper XML）

完整结构

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
         "https://mybatis.org/dtd/mybatis-3-mapper.dtd">
 <!-- namespace 必须与 Mapper 接口全限定名一致 -->
 <mapper namespace="com.example.mapper.EmpMapper">
     <!-- ============ 1. 缓存配置 ============ -->
     <cache/>                    <!-- 开启二级缓存（默认） -->
    <cache-ref namespace="com.example.mapper.DeptMapper"/>  <!-- 引用其他命名空间的缓存 -->
    <!-- ============ 2. 结果映射 ============ -->
    <resultMap id="empResultMap" type="Emp">
        <id property="empId" column="emp_id"/>
        <result property="empName" column="emp_name"/>
        <result property="email" column="email"/>
    </resultMap>
    <!-- ============ 3. SQL 片段 ============ -->
    <sql id="empColumns">
        emp_id, emp_name, email, salary, dept_id, hire_date, status
    </sql>
    <sql id="empWhere">
        <where>
            <if test="empName != null and empName != ''">
                AND emp_name LIKE CONCAT('%', #{empName}, '%')
            </if>
            <if test="deptId != null">
                AND dept_id = #{deptId}
            </if>
        </where>
    </sql>
    <!-- ============ 4. 查询 ============ -->
    <select id="selectAll" resultType="Emp">
        SELECT <include refid="empColumns"/> FROM emp
    </select>
    <!-- ============ 5. 插入 ============ -->
    <insert id="insert" parameterType="Emp"
            useGeneratedKeys="true" keyProperty="empId">
        INSERT INTO emp (emp_name, email, salary, dept_id, hire_date, status)
        VALUES (#{empName}, #{email}, #{salary}, #{deptId}, #{hireDate}, #{status})
    </insert>
    <!-- ============ 6. 更新 ============ -->
    <update id="update" parameterType="Emp">
        UPDATE emp SET
            emp_name = #{empName},
            salary = #{salary}
        WHERE emp_id = #{empId}
    </update>
    <!-- ============ 7. 删除 ============ -->
    <delete id="deleteById" parameterType="int">
        DELETE FROM emp WHERE emp_id = #{empId}
    </delete>
</mapper>

select 元素属性详解

 <select
     id="selectEmp"              <!-- 必须与接口方法名一致 -->
     parameterType="map"         <!-- 参数类型（可省略，自动推断） -->
     resultType="Emp"            <!-- 返回类型 -->
     resultMap="empResultMap"    <!-- 结果映射（与 resultType 二选一） -->
     flushCache="false"          <!-- 是否清空缓存 -->
     useCache="true"             <!-- 是否使用二级缓存 -->
     timeout="30"                <!-- 超时秒数 -->
     fetchSize="100"             <!-- 批量获取大小 -->
    statementType="PREPARED"    <!-- STATEMENT/PREPARED/CALLABLE -->
    resultSetType="FORWARD_ONLY" <!-- FORWARD_ONLY/SCROLL_INSENSITIVE/SCROLL_SENSITIVE
     -->
    databaseId="mysql"          <!-- 数据库厂商标识 -->
    resultOrdered="false"       <!-- 嵌套结果是否按顺序 -->
    resultSets="emp,dept"       <!-- 多结果集名 -->
    >
    SELECT * FROM emp WHERE emp_id = #{empId}
</select>

#{} 与 ${} 的区别

特性	#{}	${}
处理方式	预编译参数（PreparedStatement 的 ?）	字符串拼接
SQL 注入	✅ 防止	❌ 有风险
性能	可利用预编译缓存	每次都不同
使用场景	参数值	表名/列名/ORDER BY

 <!-- #{}：安全，用于传值 -->
 <select id="selectById" resultType="Emp">
     SELECT * FROM emp WHERE emp_id = #{empId}  <!-- → WHERE emp_id = ? -->
 </select>
 <!-- ${}：不安全，用于动态表名/列名 -->
 <select id="selectByColumn" resultType="Emp">
     SELECT * FROM emp ORDER BY ${columnName} ${order}
     <!-- → SELECT * FROM emp ORDER BY emp_id DESC -->
</select>
<!-- 必须对 ${} 的输入做校验 -->

参数传递

单个参数

// 接口
Emp selectById(Integer empId);

<!-- XML：#{任意名} -->
<select id="selectById" resultType="Emp">
    SELECT * FROM emp WHERE emp_id = #{empId}
    <!-- 也可写成 #{id} 或 #{任意名}，单参数不限制 -->
</select>

多个参数（使用 @Param）

// 接口
List<Emp> selectByCondition(@Param("empName") String empName,
                             @Param("deptId") Integer deptId);

<select id="selectByCondition" resultType="Emp">
    SELECT * FROM emp
    WHERE emp_name LIKE CONCAT('%', #{empName}, '%')
      AND dept_id = #{deptId}
</select>

多个参数（使用 Map / 对象）

// Map
List<Emp> selectByMap(Map<String, Object> params);
// 对象
List<Emp> selectByEmp(Emp query);

 <!-- Map：#{key} -->
 <select id="selectByMap" resultType="Emp">
     SELECT * FROM emp
     WHERE emp_name = #{name} AND dept_id = #{deptId}
 </select>
 <!-- 对象：#{属性名} -->
 <select id="selectByEmp" resultType="Emp" parameterType="Emp">
     SELECT * FROM emp
    WHERE emp_name = #{empName} AND dept_id = #{deptId}
</select>

参数为 List / Array

1List<Emp> selectByIds(@Param(“ids”) List<Integer> ids);

<select id="selectByIds" resultType="Emp">
    SELECT * FROM emp WHERE emp_id IN
    <foreach collection="ids" item="id" open="(" separator="," close=")">
        #{id}
    </foreach>
</select>

insert 元素详解

 <!-- 普通插入 -->
 <insert id="insert" parameterType="Emp">
     INSERT INTO emp (emp_name, email, salary)
     VALUES (#{empName}, #{email}, #{salary})
 </insert>
 <!-- 主键回填（自增主键） -->
 <insert id="insert" parameterType="Emp"
         useGeneratedKeys="true" keyProperty="empId" keyColumn="emp_id">
    INSERT INTO emp (emp_name, email)
    VALUES (#{empName}, #{email})
</insert>
<!-- 插入后 emp.getEmpId() 可获取生成的主键 -->
<!-- 主键回填（非自增主键，如 Oracle 序列） -->
<insert id="insert" parameterType="Emp">
    <selectKey keyProperty="empId" resultType="int" order="BEFORE">
        SELECT SEQ_EMP.NEXTVAL FROM DUAL
    </selectKey>
    INSERT INTO emp (emp_id, emp_name)
    VALUES (#{empId}, #{empName})
</insert>
<!-- MySQL/PostgreSQL 使用 UUID -->
<insert id="insert" parameterType="Emp">
    <selectKey keyProperty="empId" resultType="string" order="BEFORE">
        SELECT UUID()
    </selectKey>
    INSERT INTO emp (emp_id, emp_name)
    VALUES (#{empId}, #{empName})
</insert>

`selectKey` 属性	说明
`keyProperty`	主键值要写入的 Java 属性
`keyColumn`	数据库中的主键列名，多列主键时可指定
`resultType`	主键值的 Java 类型
`order`	`BEFORE` 表示插入前查询主键，`AFTER` 表示插入后查询主键

SQL 片段

<!-- 定义 SQL 片段 -->
<sql id="empColumns">
    emp_id, emp_name, email, salary, dept_id, hire_date, status
</sql>
 <sql id="empColumnsWithAlias">
     e.emp_id, e.emp_name, e.email, e.salary, e.dept_id, e.hire_date, e.status
 </sql>
<!-- 引用 SQL 片段 -->
<select id="selectAll" resultType="Emp">
    SELECT <include refid="empColumns"/> FROM emp
</select>
<!-- 带参数的 SQL 片段 -->
<sql id="tableName">
    ${prefix}_emp
</sql>
<select id="selectAll" resultType="Emp">
    SELECT * FROM <include refid="tableName">
        <property name="prefix" value="t"/>
    </include>
</select>

ResultMap 详解

为什么需要 ResultMap

当数据库列名与 Java 属性名不一致时，需要通过 ResultMap 进行映射：

数据库列名: emp_id, emp_name, hire_date
Java 属性名: empId, empName, hireDate
→ 开启 mapUnderscoreToCamelCase 可自动映射
→ 但复杂映射（关联、集合、鉴别器）必须用 ResultMap

ResultMap 基本结构

 <resultMap id="empResultMap" type="Emp">
     <!-- id：主键映射（MyBatis 用它判断对象唯一性） -->
     <id property="empId" column="emp_id"/>
     <!-- result：普通字段映射 -->
     <result property="empName" column="emp_name"/>
     <result property="email" column="email"/>
     <result property="salary" column="salary"/>
     <result property="hireDate" column="hire_date"/>
</resultMap>

constructor 构造器映射

 // 实体类有带参构造器
 public class Emp {
     private Integer empId;
     private String empName;
     public Emp(Integer empId, String empName) {
         this.empId = empId;
         this.empName = empName;
     }
}

<resultMap id="empResultMap" type="Emp">
    <constructor>
        <idArg javaType="int" column="emp_id"/>
        <arg javaType="string" column="emp_name"/>
    </constructor>
</resultMap>

autoMapping 自动映射

 <!-- 全局设置 -->
 <settings>
     <!-- NONE: 禁用自动映射 -->
     <!-- PARTIAL(默认): 自动映射非嵌套结果 -->
     <!-- FULL: 自动映射所有（含嵌套） -->
     <setting name="autoMappingBehavior" value="PARTIAL"/>
 </settings>
 <!-- ResultMap 级别 -->
<resultMap id="empResultMap" type="Emp" autoMapping="true">
    <id property="empId" column="emp_id"/>
    <result property="empName" column="emp_name"/>
    <!-- 其他字段自动映射 -->
</resultMap>

ResultMap 继承

 <!-- 基础 ResultMap -->
 <resultMap id="baseResultMap" type="Emp">
     <id property="empId" column="emp_id"/>
     <result property="empName" column="emp_name"/>
     <result property="email" column="email"/>
     <result property="salary" column="salary"/>
 </resultMap>
 <!-- 继承并扩展 -->
<resultMap id="empWithDeptResultMap" type="Emp" extends="baseResultMap">
    <association property="dept" javaType="Dept">
        <id property="deptId" column="d_dept_id"/>
        <result property="deptName" column="dept_name"/>
    </association>
</resultMap>

鉴别器（Discriminator）

根据某列的值决定使用不同的 ResultMap：

 <resultMap id="employeeResultMap" type="Emp">
     <id property="empId" column="emp_id"/>
     <result property="empName" column="emp_name"/>
     <!-- 鉴别器：根据 status 的值决定映射方式 -->
     <discriminator javaType="int" column="status">
         <!-- status = 1：在职员工，映射部门 -->
         <case value="1" resultType="Emp">
             <association property="dept" javaType="Dept">
                <id property="deptId" column="dept_id"/>
                <result property="deptName" column="dept_name"/>
            </association>
        </case>
        <!-- status = 0：离职员工，映射离职信息 -->
        <case value="0" resultType="Emp" resultMap="resignedEmpResultMap"/>
    </discriminator>
</resultMap>

动态 SQL

动态 SQL 元素总览

元素	说明	类似于
<if>	条件判断	if
<choose>/<when>/<otherwise>	多条件选择	switch/case/default
<where>	智能 WHERE 子句	—
<set>	智能 SET 子句	—
<trim>	自定义前缀/后缀裁剪	—
<foreach>	遍历集合	for
<bind>	绑定变量	—
<sql>/<include>	SQL 片段复用	—

if 元素

 <select id="selectByCondition" resultType="Emp">
     SELECT * FROM emp
     WHERE 1=1
     <if test="empName != null and empName != ''">
         AND emp_name LIKE CONCAT('%', #{empName}, '%')
     </if>
     <if test="deptId != null">
         AND dept_id = #{deptId}
     </if>
    <if test="minSalary != null">
        AND salary &gt;= #{minSalary}
    </if>
    <if test="maxSalary != null">
        AND salary &lt;= #{maxSalary}
    </if>
    <if test="status != null">
        AND status = #{status}
    </if>
</select>

注意：XML 中 < 和 > 需要转义为 < 和 >，或使用 <![CDATA[…]]> 包裹。

where 元素

<where> 会自动处理：

去掉首个 AND 或 OR
如果没有任何条件，则不加 WHERE

 <select id="selectByCondition" resultType="Emp">
     SELECT * FROM emp
     <where>
         <if test="empName != null and empName != ''">
             AND emp_name LIKE CONCAT('%', #{empName}, '%')
         </if>
         <if test="deptId != null">
             AND dept_id = #{deptId}
         </if>
        <if test="minSalary != null">
            AND salary &gt;= #{minSalary}
        </if>
    </where>
</select>

choose / when / otherwise

 <select id="selectByChoice" resultType="Emp">
     SELECT * FROM emp
     <where>
         <choose>
             <when test="empName != null and empName != ''">
                 emp_name = #{empName}
             </when>
             <when test="email != null and email != ''">
                 email = #{email}
            </when>
            <otherwise>
                status = 1
            </otherwise>
        </choose>
    </where>
</select>

set 元素

<set> 会自动处理：

去掉末尾多余的逗号
如果没有任何条件，则不加 SET（会报错）

 <update id="updateSelective" parameterType="Emp">
     UPDATE emp
     <set>
         <if test="empName != null">emp_name = #{empName},</if>
         <if test="email != null">email = #{email},</if>
         <if test="salary != null">salary = #{salary},</if>
         <if test="deptId != null">dept_id = #{deptId},</if>
         <if test="status != null">status = #{status},</if>
     </set>
    WHERE emp_id = #{empId}
</update>

trim 元素

<trim> 是 <where> 和 <set> 等元素的基础能力之一，可以自定义前缀、后缀以及需要移除的内容。

<!-- 等价于 <where> 的常见写法 -->
<trim prefix="WHERE" prefixOverrides="AND |OR ">
    ...
</trim>

<!-- 等价于 <set> 的常见写法 -->
<trim prefix="SET" suffixOverrides=",">
    ...
</trim>

属性	说明
`prefix`	在最终内容前添加前缀
`suffix`	在最终内容后添加后缀
`prefixOverrides`	移除内容开头匹配的字符串
`suffixOverrides`	移除内容末尾匹配的字符串

foreach 元素

 <!-- IN 查询 -->
 <select id="selectByIds" resultType="Emp">
     SELECT * FROM emp WHERE emp_id IN
     <foreach collection="ids" item="id" open="(" separator="," close=")">
         #{id}
     </foreach>
 </select>
 <!-- 生成：SELECT * FROM emp WHERE emp_id IN (1, 2, 3) -->
<!-- 批量插入 -->
<insert id="batchInsert" parameterType="list">
    INSERT INTO emp (emp_name, email, salary)
    VALUES
    <foreach collection="list" item="emp" separator=",">
        (#{emp.empName}, #{emp.email}, #{emp.salary})
    </foreach>
</insert>
<!-- 生成：INSERT INTO emp ... VALUES ('张三','a@b.com',10000),('李四','c@d.com',12000) -
     ->
<!-- 批量更新（CASE WHEN 方式） -->
<update id="batchUpdate" parameterType="list">
    UPDATE emp SET
    salary =
    <foreach collection="list" item="emp" open="CASE emp_id" close="END">
        WHEN #{emp.empId} THEN #{emp.salary}
    </foreach>
    WHERE emp_id IN
    <foreach collection="list" item="emp" open="(" separator="," close=")">
        #{emp.empId}
    </foreach>
</update>
<!-- OR 条件 -->
<select id="selectByNames" resultType="Emp">
    SELECT * FROM emp WHERE
    <foreach collection="names" item="name" separator=" OR ">
        emp_name = #{name}
    </foreach>
</select>

属性	说明
`collection`	要遍历的集合名称。单个 `List` 参数通常为 `list`，数组通常为 `array`，也可以使用 `@Param` 指定名称
`item`	当前元素的变量名
`index`	当前索引或 Map 的键
`open`	整段内容的起始字符串
`close`	整段内容的结束字符串
`separator`	相邻元素之间的分隔符

bind 元素

 <!-- 模糊查询拼接 -->
 <select id="selectByName" resultType="Emp">
     <bind name="likeName" value="'%' + empName + '%'" />
     SELECT * FROM emp WHERE emp_name LIKE #{likeName}
 </select>
 <!-- 绑定多个变量 -->
 <select id="selectByCondition" resultType="Emp">
     <bind name="minSalaryValue" value="minSalary != null ? minSalary : 0" />
    <bind name="maxSalaryValue" value="maxSalary != null ? maxSalary : 999999" />
    SELECT * FROM emp
    WHERE salary BETWEEN #{minSalaryValue} AND #{maxSalaryValue}
</select>

完整动态 SQL 示例

<select id="selectByDynamicCondition" resultType="Emp">
    SELECT
    <include refid="empColumns"/>
    FROM emp
    <where>
        <if test="empName != null and empName != ''">
            <bind name="likeName" value="'%' + empName + '%'"/>
            AND emp_name LIKE #{likeName}
         </if>
        <if test="email != null and email != ''">
            AND email = #{email}
        </if>
        <if test="deptId != null">
            AND dept_id = #{deptId}
        </if>
        <if test="deptIds != null and deptIds.size() > 0">
            AND dept_id IN
            <foreach collection="deptIds" item="did" open="(" separator="," close=")">
                #{did}
            </foreach>
        </if>
        <if test="minSalary != null or maxSalary != null">
            <choose>
                <when test="minSalary != null and maxSalary != null">
                    AND salary BETWEEN #{minSalary} AND #{maxSalary}
                </when>
                <when test="minSalary != null">
                    AND salary &gt;= #{minSalary}
                </when>
                <otherwise>
                    AND salary &lt;= #{maxSalary}
                </otherwise>
            </choose>
        </if>
        <if test="status != null">
            AND status = #{status}
        </if>
    </where>
    ORDER BY emp_id DESC
</select>

关联查询

一对一关联（association）

方式一：嵌套结果（join 查询，一次 SQL）

public class Emp {
    private Integer empId;
    private String empName;
    private Dept dept;  // 关联的部门对象
}

<resultMap id="empWithDeptResultMap" type="Emp">
    <id property="empId" column="emp_id"/>
    <result property="empName" column="emp_name"/>
    <result property="email" column="email"/>
     <!-- 一对一关联 -->
     <association property="dept" javaType="Dept">
         <id property="deptId" column="d_dept_id"/>
         <result property="deptName" column="d_dept_name"/>
        <result property="location" column="d_location"/>
    </association>
</resultMap>
<select id="selectEmpWithDept" resultMap="empWithDeptResultMap">
    SELECT
        e.emp_id,
        e.emp_name,
        e.email,
        d.dept_id   AS d_dept_id,
        d.dept_name AS d_dept_name,
        d.location  AS d_location
    FROM emp e
    LEFT JOIN dept d ON e.dept_id = d.dept_id
    WHERE e.emp_id = #{empId}
</select>

方式二：嵌套查询（分步查询，N+1 问题）

 <resultMap id="empWithDeptStepResultMap" type="Emp">
     <id property="empId" column="emp_id"/>
     <result property="empName" column="emp_name"/>
     <!-- column: 传递给子查询的列名; select: 子查询的方法全限定名 -->
     <association property="dept"
                  javaType="Dept"
                  column="dept_id"
                  select="com.example.mapper.DeptMapper.selectById"
                 fetchType="lazy"/>  <!-- lazy: 延迟加载; eager: 立即加载 -->
</resultMap>
<select id="selectEmpWithDeptStep" resultMap="empWithDeptStepResultMap">
    SELECT * FROM emp WHERE emp_id = #{empId}
</select>

<!-- DeptMapper.xml -->
<select id="selectById" resultType="Dept">
    SELECT * FROM dept WHERE dept_id = #{deptId}
</select>

执行流程：

先执行 SELECT * FROM emp WHERE emp_id = ?
取出 dept_id，执行 SELECT * FROM dept WHERE dept_id = ?

方式三：嵌套查询传多个参数

<association property="dept"
             javaType="Dept"
             column="{deptId=dept_id, status=status}"
             select="com.example.mapper.DeptMapper.selectByIdAndStatus"
             fetchType="lazy"/>

一对多关联（collection）

public class Dept {
    private Integer deptId;
    private String deptName;
    private List<Emp> emps;  // 关联的员工列表
}

方式一：嵌套结果

 <resultMap id="deptWithEmpsResultMap" type="Dept">
     <id property="deptId" column="dept_id"/>
     <result property="deptName" column="dept_name"/>
     <result property="location" column="location"/>
     <!-- 一对多关联 -->
     <collection property="emps" ofType="Emp">
         <id property="empId" column="e_emp_id"/>
         <result property="empName" column="e_emp_name"/>
        <result property="email" column="e_email"/>
        <result property="salary" column="e_salary"/>
    </collection>
</resultMap>
<select id="selectDeptWithEmps" resultMap="deptWithEmpsResultMap">
    SELECT
        d.dept_id,
        d.dept_name,
        d.location,
        e.emp_id   AS e_emp_id,
        e.emp_name AS e_emp_name,
        e.email    AS e_email,
        e.salary   AS e_salary
    FROM dept d
    LEFT JOIN emp e ON d.dept_id = e.dept_id
    WHERE d.dept_id = #{deptId}
</select>

方式二：嵌套查询

 <resultMap id="deptWithEmpsStepResultMap" type="Dept">
     <id property="deptId" column="dept_id"/>
     <result property="deptName" column="dept_name"/>
     <collection property="emps"
                 ofType="Emp"
                 column="dept_id"
                 select="com.example.mapper.EmpMapper.selectByDeptId"
                 fetchType="lazy"/>
</resultMap>
<select id="selectDeptWithEmpsStep" resultMap="deptWithEmpsStepResultMap">
    SELECT * FROM dept WHERE dept_id = #{deptId}
</select>

多对多关联

public class Emp {
    private Integer empId;
    private String empName;
    private List<Project> projects;  // 参与的项目
}

 <resultMap id="empWithProjectsResultMap" type="Emp">
     <id property="empId" column="emp_id"/>
     <result property="empName" column="emp_name"/>
     <collection property="projects" ofType="Project">
         <id property="projectId" column="p_project_id"/>
         <result property="projectName" column="p_project_name"/>
         <result property="budget" column="p_budget"/>
     </collection>
</resultMap>
<select id="selectEmpWithProjects" resultMap="empWithProjectsResultMap">
    SELECT
        e.emp_id,
        e.emp_name,
        p.project_id   AS p_project_id,
        p.project_name AS p_project_name,
        p.budget       AS p_budget
    FROM emp e
    LEFT JOIN emp_project ep ON e.emp_id = ep.emp_id
    LEFT JOIN project p ON ep.project_id = p.project_id
    WHERE e.emp_id = #{empId}
</select>

嵌套查询 vs 嵌套结果对比

特性	嵌套结果（join）	嵌套查询（分步）
SQL 次数	1 次（多表 JOIN）	N+1 次
性能	高（单次查询）	低（N+1 问题，但可延迟加载）
延迟加载	❌ 不支持	✅ 支持
SQL 复杂度	高（多表 JOIN）	低（简单查询）
数据量	大（笛卡尔积）	分步获取
推荐	关联数据少	关联数据多 + 延迟加载

延迟加载配置

<!-- mybatis-config.xml -->
<settings>
    <!-- 全局开启延迟加载 -->
    <setting name="lazyLoadingEnabled" value="true"/>
    <!-- false: 按需加载（仅访问关联属性时才加载） -->
    <setting name="aggressiveLazyLoading" value="false"/>
    <!-- 延迟加载触发方法 -->
    <setting name="lazyLoadTriggerMethods" value="equals,clone,hashCode,toString"/>
</settings>

<!-- 单个 association/collection 级别 -->
<association property="dept" fetchType="lazy" .../>
<collection property="emps" fetchType="eager" .../>

缓存机制

缓存体系

 ┌──────────────────────────────────────────────┐
 │             MyBatis 缓存体系                    │
 │                                               │
 │  ┌─────────────┐    ┌─────────────────────┐  │
 │  │  一级缓存     │    │    二级缓存           │  │
 │  │  (SqlSession)│    │  (Mapper namespace)  │  │
 │  │              │    │                      │  │
 │  │  默认开启     │    │  需手动开启           │  │
 │  │  Session级   │    │  跨SqlSession共享     │  │
│  │  HashMap     │    │  可集成第三方          │  │
│  └──────┬──────┘    └──────────┬───────────┘  │
│         │                      │              │
│         └──────────┬───────────┘              │
│                    ▼                          │
│              ┌───────────┐                    │
│              │   数据库    │                   │
│              └───────────┘                    │
└──────────────────────────────────────────────┘
查询顺序：二级缓存 → 一级缓存 → 数据库

一级缓存

一级缓存是 SqlSession 级别的缓存，默认开启，不可关闭。

工作原理

同一次 SqlSession 中：
. 第一次查询 emp_id=1 → 查数据库 → 存入一级缓存
. 第二次查询 emp_id=1 → 直接从一级缓存获取
. 执行 insert/update/delete → 清空一级缓存
. session.commit() 或 session.close() → 一级缓存消失

一级缓存失效条件

条件	说明
不同的 SqlSession	不同 session 不共享缓存
执行了 insert/update/delete	清空当前 session 的所有缓存
执行了 session.clearCache()	手动清空
执行了 session.commit()	清空缓存
执行了 flushCache=“true” 的查询	该查询清空缓存

一级缓存范围

<!-- 默认：SESSION（SqlSession 范围） -->
<setting name="localCacheScope" value="SESSION"/>
<!-- STATEMENT：每条语句执行后清空（相当于关闭一级缓存） -->
<setting name="localCacheScope" value="STATEMENT"/>

二级缓存

二级缓存是 Mapper namespace 级别的缓存，跨 SqlSession 共享。

开启方式

<!-- 1. 全局开启（mybatis-config.xml） -->
<settings>
    <setting name="cacheEnabled" value="true"/>
</settings>
<!-- 2. Mapper XML 中声明 -->
<mapper namespace="com.example.mapper.EmpMapper">
    <cache/>  <!-- 简单声明 -->
</mapper>

cache 元素属性

<cache
    type="org.apache.ibatis.cache.impl.PerpetualCache"   <!-- 缓存实现类 -->
    eviction="LRU"       <!-- 淘汰策略 -->
    flushInterval="60000" <!-- 刷新间隔（毫秒） -->
    size="1024"          <!-- 最大对象数 -->
    readOnly="false"     <!-- 是否只读 -->
/>

eviction 淘汰策略说明

LRU（默认）最近最少使用

FIFO 先进先出

SOFT 软引用（内存不足时回收）

WEAK 弱引用（GC 时回收）

readOnly	说明
true	所有线程共享同一对象（性能高，不安全）
false（默认）	每次返回缓存对象的副本（序列化，安全）

二级缓存使用条件

实体类必须实现 Serializable 接口（readOnly=false 时）
必须在 select 后 commit 或 close 才会写入二级缓存
执行 insert/update/delete 会自动清空该 namespace 的二级缓存

@Test
public void testSecondLevelCache() {
    // Session 1
    try (SqlSession session1 = factory.openSession()) {
        EmpMapper mapper1 = session1.getMapper(EmpMapper.class);
        Emp emp1 = mapper1.selectById(1);
         session1.commit();  // 提交后写入二级缓存
     }
    // Session 2
    try (SqlSession session2 = factory.openSession()) {
        EmpMapper mapper2 = session2.getMapper(EmpMapper.class);
        Emp emp2 = mapper2.selectById(1);  // 从二级缓存获取
    }
}

select 的 useCache 和 flushCache

 <!-- 该查询不使用二级缓存 -->
 <select id="selectCount" resultType="int" useCache="false">
     SELECT COUNT(*) FROM emp
 </select>
 <!-- 该查询执行后清空缓存 -->
 <select id="selectFreshData" resultType="Emp" flushCache="true">
     SELECT * FROM emp
 </select>
<!-- insert/update/delete 默认 flushCache="true" -->

cache-ref 引用其他命名空间缓存

<!-- 多个 Mapper 共享同一个缓存 -->
<mapper namespace="com.example.mapper.EmpMapper">
    <cache/>
</mapper>
<mapper namespace="com.example.mapper.EmpDeptMapper">
    <!-- 引用 EmpMapper 的缓存 -->
    <cache-ref namespace="com.example.mapper.EmpMapper"/>
</mapper>

集成第三方缓存（EhCache）

<!-- 依赖 -->
<dependency>
    <groupId>org.mybatis.caches</groupId>
    <artifactId>mybatis-ehcache</artifactId>
    <version>1.2.1</version>
</dependency>
 <!-- Mapper XML -->
 <cache type="org.mybatis.caches.ehcache.EhcacheCache"/>
 <!-- 或带配置 -->
 <cache type="org.mybatis.caches.ehcache.EhcacheCache">
     <property name="timeToIdleSeconds" value="3600"/>
     <property name="timeToLiveSeconds" value="7200"/>
     <property name="maxEntriesLocalHeap" value="1000"/>
     <property name="maxEntriesLocalDisk" value="10000000"/>
    <property name="memoryStoreEvictionPolicy" value="LRU"/>
</cache>

一级缓存 vs 二级缓存

特性	一级缓存	二级缓存
范围	SqlSession	Mapper namespace
共享	不共享	跨 SqlSession 共享
默认	开启	关闭
可关闭	可设置 STATEMENT	可设置 cacheEnabled=false
失效	增删改、commit、close	增删改同 namespace
存储	HashMap	可自定义（EhCache/Redis）

主键回填与批量操作

主键回填

自增主键回填

<insert id="insert" parameterType="Emp"
        useGeneratedKeys="true"
        keyProperty="empId"
        keyColumn="emp_id">
    INSERT INTO emp (emp_name, email, salary)
    VALUES (#{empName}, #{email}, #{salary})
</insert>

Emp emp = new Emp();
emp.setEmpName("张三");
mapper.insert(emp);
System.out.println(emp.getEmpId());  // 自动回填的主键

非自增主键（selectKey）

 <!-- Oracle 序列 -->
 <insert id="insert" parameterType="Emp">
     <selectKey keyProperty="empId" resultType="int" order="BEFORE">
         SELECT SEQ_EMP.NEXTVAL FROM DUAL
     </selectKey>
     INSERT INTO emp (emp_id, emp_name) VALUES (#{empId}, #{empName})
 </insert>
 <!-- MySQL UUID -->
<insert id="insert" parameterType="Emp">
    <selectKey keyProperty="empId" resultType="string" order="BEFORE">
        SELECT REPLACE(UUID(), '-', '')
    </selectKey>
    INSERT INTO emp (emp_id, emp_name) VALUES (#{empId}, #{empName})
</insert>

批量插入

方式一：foreach 拼接 VALUES

<insert id="batchInsert" parameterType="list">
    INSERT INTO emp (emp_name, email, salary, dept_id, hire_date, status)
    VALUES
    <foreach collection="list" item="emp" separator=",">
        (#{emp.empName}, #{emp.email}, #{emp.salary}, #{emp.deptId}, #{emp.hireDate}, #
    {emp.status})
    </foreach>
</insert>

List<Emp> emps = new ArrayList<>();
emps.add(emp1);
emps.add(emp2);
mapper.batchInsert(emps);

方式二：Batch 执行器

 try (SqlSession session = factory.openSession(ExecutorType.BATCH, false)) {
     EmpMapper mapper = session.getMapper(EmpMapper.class);
     for (int i = 0; i < 10000; i++) {
         Emp emp = new Emp();
         emp.setEmpName("emp_" + i);
         mapper.insert(emp);
         if (i % 1000 == 0) {
            session.flushStatements();  // 每 1000 条执行一次
        }
    }
    session.commit();
}

方式三：ON DUPLICATE KEY UPDATE（MySQL 批量 upsert）

 <insert id="batchUpsert" parameterType="list">
     INSERT INTO emp (emp_id, emp_name, email, salary)
     VALUES
     <foreach collection="list" item="emp" separator=",">
         (#{emp.empId}, #{emp.empName}, #{emp.email}, #{emp.salary})
     </foreach>
     ON DUPLICATE KEY UPDATE
         emp_name = VALUES(emp_name),
         email = VALUES(email),
        salary = VALUES(salary)
</insert>

批量更新

方式一：CASE WHEN

 <update id="batchUpdate" parameterType="list">
     UPDATE emp SET
     salary =
     <foreach collection="list" item="emp" open="CASE emp_id" close="END">
         WHEN #{emp.empId} THEN #{emp.salary}
     </foreach>
     WHERE emp_id IN
     <foreach collection="list" item="emp" open="(" separator="," close=")">
         #{emp.empId}
    </foreach>
</update>

方式二：Batch 执行器

try (SqlSession session = factory.openSession(ExecutorType.BATCH)) {
    EmpMapper mapper = session.getMapper(EmpMapper.class);
    for (Emp emp : empList) {
        mapper.update(emp);
    }
    session.commit();
}

TypeHandler 类型处理器

什么是 TypeHandler

TypeHandler 用于 Java 类型和 JDBC 类型之间的转换：

Java 类型  ←→  JDBC 类型
String    ←→  VARCHAR
Integer   ←→  INT
Date      ←→  TIMESTAMP
List      ←→  VARCHAR (自定义)

内置 TypeHandler

MyBatis 内置了常用 Java 类型与 JDBC 类型之间的转换器。

TypeHandler	Java 类型	JDBC 类型
`BooleanTypeHandler`	`Boolean`、`boolean`	`BOOLEAN`
`IntegerTypeHandler`	`Integer`、`int`	`INTEGER`
`LongTypeHandler`	`Long`、`long`	`BIGINT`
`StringTypeHandler`	`String`	`VARCHAR`、`CHAR`、`LONGVARCHAR`
`DateTypeHandler`	`Date`	`TIMESTAMP`
`BigDecimalTypeHandler`	`BigDecimal`	`DECIMAL`、`NUMERIC`
`ByteArrayTypeHandler`	`byte[]`	`BLOB`、`LONGVARBINARY`
`EnumTypeHandler`	`Enum`	通常为 `VARCHAR`
`EnumOrdinalTypeHandler`	`Enum` 的序号	`INTEGER`
`LocalDateTypeHandler`	`LocalDate`	`DATE`
`LocalDateTimeTypeHandler`	`LocalDateTime`	`TIMESTAMP`

自定义 TypeHandler

场景：将 List 存为 JSON 字符串

package com.example.handler;
import org.apache.ibatis.type.BaseTypeHandler;
import org.apache.ibatis.type.JdbcType;
import org.apache.ibatis.type.MappedJdbcTypes;
import org.apache.ibatis.type.MappedTypes;
import java.sql.*;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
@MappedTypes(List.class)
@MappedJdbcTypes(JdbcType.VARCHAR)
public class StringListTypeHandler extends BaseTypeHandler<List<String>> {
    // 将 Java 类型 → JDBC 类型（存入数据库）
    @Override
    public void setNonNullParameter(PreparedStatement ps, int i,
                                    List<String> parameter, JdbcType jdbcType) throws SQLException {
        // List → "a,b,c"
        String value = String.join(",", parameter);
        ps.setString(i, value);
    }
    // 将 JDBC 类型 → Java 类型（从数据库读取）
    @Override
    public List<String> getNullableResult(ResultSet rs, String columnName) throws SQLException {
        String value = rs.getString(columnName);
        return toList(value);
    }
    @Override
    public List<String> getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
        String value = rs.getString(columnIndex);
        return toList(value);
    }
    @Override
    public List<String> getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
        String value = cs.getString(columnIndex);
        return toList(value);
    }
    private List<String> toList(String value) {
        if (value == null || value.isEmpty()) {
            return new ArrayList<>();
        }
        return Arrays.asList(value.split(","));
    }
}

注册 TypeHandler

<!-- mybatis-config.xml -->
<typeHandlers>
    <!-- 方式一：单个注册 -->
    <typeHandler handler="com.example.handler.StringListTypeHandler"/>
    <!-- 方式二：包扫描 -->
    <package name="com.example.handler"/>
</typeHandlers>

使用 TypeHandler

 <!-- 在映射中指定 typeHandler -->
 <resultMap id="empResultMap" type="Emp">
     <id property="empId" column="emp_id"/>
     <result property="empName" column="emp_name"/>
     <result property="tags" column="tags"
             typeHandler="com.example.handler.StringListTypeHandler"/>
 </resultMap>
 <!-- 在参数中指定 -->
<insert id="insert" parameterType="Emp">
    INSERT INTO emp (emp_name, tags)
    VALUES (#{empName}, #{tags, typeHandler=com.example.handler.StringListTypeHandler})
</insert>

枚举类型处理

 public enum EmpStatus {
     ACTIVE(1, "在职"),
     RESIGNED(0, "离职");
     private int code;
     private String desc;
     EmpStatus(int code, String desc) {
         this.code = code;
        this.desc = desc;
    }
    // getter...
}

<!-- 方式一：按名称存储（默认） -->
<!-- 存入 "ACTIVE"，读取时 Enum.valueOf("ACTIVE") -->
<setting name="defaultEnumTypeHandler" value="org.apache.ibatis.type.EnumTypeHandler"/>
<!-- 方式二：按序号存储 -->
<!-- 存入 0（ACTIVE 的序号） -->
<setting name="defaultEnumTypeHandler"
    value="org.apache.ibatis.type.EnumOrdinalTypeHandler"/>

自定义枚举 TypeHandler（按 code 存储）

 @MappedTypes(EmpStatus.class)
 public class EmpStatusTypeHandler extends BaseTypeHandler<EmpStatus> {
     @Override
     public void setNonNullParameter(PreparedStatement ps, int i,
                                     EmpStatus parameter, JdbcType jdbcType) throws SQLException {
         ps.setInt(i, parameter.getCode());
     }
     @Override
    public EmpStatus getNullableResult(ResultSet rs, String columnName) throws SQLException {
        int code = rs.getInt(columnName);
        return EmpStatus.fromCode(code);
    }
    // ... 其他方法
}

ObjectFactory 对象工厂

什么是 ObjectFactory

ObjectFactory 负责创建结果对象的实例。默认实现是 DefaultObjectFactory。

自定义 ObjectFactory

 package com.example.factory;
 import org.apache.ibatis.reflection.factory.DefaultObjectFactory;
 import java.util.List;
 import java.util.Properties;
 public class CustomObjectFactory extends DefaultObjectFactory {
     @Override
    public <T> T create(Class<T> type) {
        T object = super.create(type);
        // 可以在这里做初始化
        return object;
    }
    @Override
    public <T> T create(Class<T> type, List<Class<?>> constructorArgTypes, List<Object>
     constructorArgs) {
        T object = super.create(type, constructorArgTypes, constructorArgs);
        // 自定义初始化逻辑
        return object;
    }
    @Override
    public void setProperties(Properties properties) {
        super.setProperties(properties);
    }
    @Override
    public <T> boolean isCollection(Class<T> type) {
        return super.isCollection(type);
    }
}
<objectFactory type="com.example.factory.CustomObjectFactory">
    <property name="someProperty" value="100"/>
</objectFactory>

Plugin 插件机制（拦截器）

插件原理

MyBatis 允许通过插件（拦截器）拦截以下四大对象的方法调用：

对象	拦截的方法	说明
Executor	update, query, commit, rollback, createStatement 等	执行器
ParameterHandler	setParameters	参数处理
ResultSetHandler	handleResultSets	结果集处理
StatementHandler	prepare, parameterize, batch	SQL 语句处理

SqlSession.selectList()
    → Executor.query()
        → StatementHandler.prepare()      ← 可拦截（修改 SQL）
        → StatementHandler.parameterize()
            → ParameterHandler.setParameters()  ← 可拦截（修改参数）
        → StatementHandler.query()
            → ResultSetHandler.handleResultSets()  ← 可拦截（修改结果）

编写自定义插件

分页拦截器示例

package com.example.plugin;
import org.apache.ibatis.executor.Executor;
import org.apache.ibatis.mapping.MappedStatement;
 import org.apache.ibatis.plugin.*;
 import org.apache.ibatis.session.ResultHandler;
 import org.apache.ibatis.session.RowBounds;
 import java.util.Properties;
@Intercepts(@Signature(
    type = Executor.class,
    method = "query",
    args = {MappedStatement.class, Object.class, RowBounds.class, ResultHandler.class}
))
public class PagePlugin implements Interceptor {
    private Properties properties;
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        // 获取参数
        Object[] args = invocation.getArgs();
        MappedStatement ms = (MappedStatement) args[0];
        Object parameter = args[1];
        RowBounds rowBounds = (RowBounds) args[2];
        // 执行原查询（获取总数）
        // ... 分页逻辑
        // 修改 RowBounds
        args[2] = new RowBounds(offset, limit);
        return invocation.proceed();
    }
    @Override
    public Object plugin(Object target) {
        return Plugin.wrap(target, this);
    }
    @Override
    public void setProperties(Properties properties) {
        this.properties = properties;
    }
}
<!-- 注册插件 -->
<plugins>
    <plugin interceptor="com.example.plugin.PagePlugin">
        <property name="dialect" value="mysql"/>
    </plugin>
</plugins>

SQL 审计拦截器示例

 @Intercepts({
     @Signature(type = Executor.class, method = "update",
                args = {MappedStatement.class, Object.class})
 })
 public class SqlAuditPlugin implements Interceptor {
     @Override
     public Object intercept(Invocation invocation) throws Throwable {
         MappedStatement ms = (MappedStatement) invocation.getArgs()[0];
        Object parameter = invocation.getArgs()[1];
        // 获取 SQL ID
        String sqlId = ms.getId();
        // 获取 SQL 语句
        BoundSql boundSql = ms.getBoundSql(parameter);
        String sql = boundSql.getSql();
        // 记录审计日志
        long start = System.currentTimeMillis();
        Object result = invocation.proceed();
        long elapsed = System.currentTimeMillis() - start;
        System.out.println("[SQL审计] " + sqlId + " | 耗时: " + elapsed + "ms");
        System.out.println("[SQL] " + sql);
        return result;
    }
    @Override
    public Object plugin(Object target) {
        return Plugin.wrap(target, this);
    }
    @Override
    public void setProperties(Properties properties) {}
}

分页

RowBounds 分页（内存分页）

// 内存分页（不推荐大数据量）
int offset = 0;
int limit = 10;
RowBounds rowBounds = new RowBounds(offset, limit);
List<Emp> emps = session.selectList("com.example.mapper.EmpMapper.selectAll", null,
    rowBounds);

注意：RowBounds 是内存分页，先查出全部数据再取子集，不推荐使用。

SQL 分页（推荐）

1List<Emp> selectByPage(@Param(“offset”) int offset, @Param(“limit”) int limit);

<select id="selectByPage" resultType="Emp">
    SELECT * FROM emp
    ORDER BY emp_id
    LIMIT #{offset}, #{limit}
</select>

PageHelper 分页插件（最常用）

 <!-- 依赖 -->
 <dependency>
     <groupId>com.github.pagehelper</groupId>
     <artifactId>pagehelper</artifactId>
     <version>5.3.3</version>
 </dependency>
 <!-- 或 MyBatis 专用版 -->
 <dependency>
    <groupId>com.github.pagehelper</groupId>
    <artifactId>pagehelper-spring-boot-starter</artifactId>
    <version>2.1.0</version>
</dependency>

 <!-- mybatis-config.xml 配置 -->
 <plugins>
     <plugin interceptor="com.github.pagehelper.PageInterceptor">
         <!-- 数据库方言 -->
         <property name="helperDialect" value="mysql"/>
         <!-- 分页合理化：页码 < 1 查第一页，> 最大页查最后一页 -->
         <property name="reasonable" value="true"/>
         <!-- 支持通过 Mapper 接口参数传递分页参数 -->
         <property name="supportMethodsArguments" value="true"/>
        <!-- 总数统计 -->
        <property name="params" value="count=countSql"/>
    </plugin>
</plugins>

使用 PageHelper

 // 方式一：静态方法调用
 PageHelper.startPage(1, 10);  // 第 1 页，每页 10 条
 List<Emp> emps = mapper.selectAll();
 // PageHelper 会自动追加 LIMIT 0, 10
 // 获取分页信息
 PageInfo<Emp> pageInfo = new PageInfo<>(emps);
 System.out.println("总记录数: " + pageInfo.getTotal());
 System.out.println("总页数: " + pageInfo.getPages());
System.out.println("当前页: " + pageInfo.getPageNum());
System.out.println("每页大小: " + pageInfo.getPageSize());
System.out.println("是否有下一页: " + pageInfo.isHasNextPage());
// 方式二：通过参数传递
List<Emp> emps = mapper.selectByParams(1, 10);
// PageHelper 自动处理
// 方式三：Lambda 方式
PageInfo<Emp> pageInfo = PageHelper.startPage(1, 10)
    .doSelectPageInfo(() -> mapper.selectAll());

PageInfo 属性

 public class PageInfo<T> {
     private int pageNum;        // 当前页
     private int pageSize;       // 每页大小
     private long total;         // 总记录数
     private int pages;          // 总页数
     private List<T> list;       // 数据列表
     private int prePage;        // 上一页
     private int nextPage;       // 下一页
     private boolean isFirstPage;    // 是否首页
    private boolean isLastPage;     // 是否末页
    private boolean hasPreviousPage; // 是否有上一页
    private boolean hasNextPage;     // 是否有下一页
    private int navigateFirstPage;   // 导航首页
    private int navigateLastPage;    // 导航末页
    private int[] navigatepageNums;  // 导航页码数组
}

注解开发

基本注解

public interface EmpMapper {
    // 查询
    @Select("SELECT * FROM emp WHERE emp_id = #{empId}")
     Emp selectById(Integer empId);
     // 查询列表
     @Select("SELECT * FROM emp WHERE dept_id = #{deptId}")
     List<Emp> selectByDeptId(Integer deptId);
    // 插入（主键回填）
    @Insert("INSERT INTO emp (emp_name, email, salary) VALUES (#{empName}, #{email}, #
     {salary})")
    @Options(useGeneratedKeys = true, keyProperty = "empId")
    int insert(Emp emp);
    // 更新
    @Update("UPDATE emp SET emp_name = #{empName}, salary = #{salary} WHERE emp_id = #
     {empId}")
    int update(Emp emp);
    // 删除
    @Delete("DELETE FROM emp WHERE emp_id = #{empId}")
    int deleteById(Integer empId);
    // 查询数量
    @Select("SELECT COUNT(*) FROM emp")
    int selectCount();
}

Results 和 Result 注解

 @Results({
     @Result(property = "empId", column = "emp_id", id = true),
     @Result(property = "empName", column = "emp_name"),
     @Result(property = "hireDate", column = "hire_date"),
     @Result(property = "dept", column = "dept_id",
             one = @One(select = "com.example.mapper.DeptMapper.selectById",
                        fetchType = FetchType.LAZY))
 })
 @Select("SELECT * FROM emp WHERE emp_id = #{empId}")
Emp selectByIdWithDept(Integer empId);

一对多注解

@Results({
    @Result(property = "deptId", column = "dept_id", id = true),
    @Result(property = "deptName", column = "dept_name"),
    @Result(property = "emps", column = "dept_id",
            many = @Many(select = "com.example.mapper.EmpMapper.selectByDeptId",
                         fetchType = FetchType.LAZY))
})
@Select("SELECT * FROM dept WHERE dept_id = #{deptId}")
Dept selectDeptWithEmps(Integer deptId);

动态 SQL 注解（@SelectProvider 等）

 // Provider 方式
 public class EmpSqlProvider {
     public String selectByCondition(final Emp emp) {
         return new SQL() {{
             SELECT("*");
             FROM("emp");
             if (emp.getEmpName() != null) {
                 WHERE("emp_name LIKE CONCAT('%', #{empName}, '%')");
            }
            if (emp.getDeptId() != null) {
                WHERE("dept_id = #{deptId}");
            }
            if (emp.getStatus() != null) {
                WHERE("status = #{status}");
            }
            ORDER_BY("emp_id DESC");
        }}.toString();
    }
}
// 接口
public interface EmpMapper {
    @SelectProvider(type = EmpSqlProvider.class, method = "selectByCondition")
    List<Emp> selectByCondition(Emp emp);
    @InsertProvider(type = EmpSqlProvider.class, method = "insert")
    int insert(Emp emp);
    @UpdateProvider(type = EmpSqlProvider.class, method = "update")
    int update(Emp emp);
    @DeleteProvider(type = EmpSqlProvider.class, method = "delete")
    int delete(Integer empId);
}

注解与 XML 对比

特性	XML 映射	注解映射
SQL 复杂度	适合复杂 SQL 和大型动态 SQL	适合简单 SQL，复杂场景通常需要 Provider
动态 SQL	功能完整、可读性较好	能实现，但代码通常更分散
可读性	SQL 与 Java 代码分离	简单语句直观
维护性	复杂查询更易集中维护	简单 CRUD 维护成本低
推荐场景	复杂查询、多人协作项目	简单 CRUD、少量固定 SQL

Spring 集成

依赖

 <dependency>
     <groupId>org.mybatis</groupId>
     <artifactId>mybatis-spring</artifactId>
     <version>3.0.3</version>
 </dependency>
 <dependency>
     <groupId>org.springframework</groupId>
     <artifactId>spring-jdbc</artifactId>
    <version>6.1.5</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>6.1.5</version>
</dependency>
<!-- 数据源 -->
<dependency>
    <groupId>com.zaxxer</groupId>
    <artifactId>HikariCP</artifactId>
    <version>5.1.0</version>
</dependency>

Spring 配置（XML 方式）

 <!-- 数据源 -->
 <bean id="dataSource" class="com.zaxxer.hikari.HikariDataSource">
     <property name="driverClassName" value="com.mysql.cj.jdbc.Driver"/>
     <property name="jdbcUrl" value="jdbc:mysql://localhost:3306/mydb"/>
     <property name="username" value="root"/>
     <property name="password" value="root123"/>
     <property name="maximumPoolSize" value="10"/>
     <property name="connectionTimeout" value="30000"/>
 </bean>
<!-- SqlSessionFactory -->
<bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean">
    <property name="dataSource" ref="dataSource"/>
    <property name="configLocation" value="classpath:mybatis-config.xml"/>
    <property name="mapperLocations" value="classpath:mapper/*.xml"/>
    <property name="typeAliasesPackage" value="com.example.entity"/>
</bean>
<!-- Mapper 扫描 -->
<bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
    <property name="basePackage" value="com.example.mapper"/>
    <property name="sqlSessionFactoryBeanName" value="sqlSessionFactory"/>
</bean>
<!-- 事务管理 -->
<bean id="transactionManager"
     class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
    <property name="dataSource" ref="dataSource"/>
</bean>
<tx:annotation-driven transaction-manager="transactionManager"/>

Spring 配置（Java 配置方式）

 @Configuration
 @MapperScan("com.example.mapper")
 @EnableTransactionManagement
 public class MyBatisConfig {
     @Bean
     public DataSource dataSource() {
         HikariConfig config = new HikariConfig();
         config.setDriverClassName("com.mysql.cj.jdbc.Driver");
        config.setJdbcUrl("jdbc:mysql://localhost:3306/mydb");
        config.setUsername("root");
        config.setPassword("root123");
        config.setMaximumPoolSize(10);
        return new HikariDataSource(config);
    }
    @Bean
    public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception
     {
        SqlSessionFactoryBean factory = new SqlSessionFactoryBean();
        factory.setDataSource(dataSource);
        factory.setConfigLocation(new ClassPathResource("mybatis-config.xml"));
        factory.setMapperLocations(new PathMatchingResourcePatternResolver()
                .getResources("classpath:mapper/*.xml"));
        factory.setTypeAliasesPackage("com.example.entity");
        return factory.getObject();
    }
    @Bean
    public DataSourceTransactionManager transactionManager(DataSource dataSource) {
        return new DataSourceTransactionManager(dataSource);
    }
}

Service 层使用

 @Service
 @Transactional
 public class EmpServiceImpl implements EmpService {
     @Autowired
     private EmpMapper empMapper;
     @Override
     public Emp getEmpById(Integer empId) {
        return empMapper.selectById(empId);
    }
    @Override
    public void transferSalary(Integer fromId, Integer toId, BigDecimal amount) {
        Emp from = empMapper.selectById(fromId);
        Emp to = empMapper.selectById(toId);
        from.setSalary(from.getSalary().subtract(amount));
        to.setSalary(to.getSalary().add(amount));
        empMapper.update(from);
        // 模拟异常
        // int i = 1 / 0;
        empMapper.update(to);  // 异常时自动回滚
    }
}

Spring Boot 集成

依赖

 <dependency>
     <groupId>org.mybatis.spring.boot</groupId>
     <artifactId>mybatis-spring-boot-starter</artifactId>
     <version>3.0.3</version>
 </dependency>
 <dependency>
     <groupId>com.mysql</groupId>
     <artifactId>mysql-connector-j</artifactId>
</dependency>

application.yml

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: root123
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      maximum-pool-size: 10
      minimum-idle: 2
      connection-timeout: 30000
mybatis:
  # 配置文件位置
  config-location: classpath:mybatis-config.xml
  # Mapper XML 位置
  mapper-locations: classpath:mapper/*.xml
  # 实体类包
  type-aliases-package: com.example.entity
  configuration:
    map-underscore-to-camel-case: true
    cache-enabled: true
    lazy-loading-enabled: true
    default-executor-type: reuse
    log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl
# PageHelper
pagehelper:
  helper-dialect: mysql
  reasonable: true
  support-methods-arguments: true

启动类

@SpringBootApplication
@MapperScan("com.example.mapper")
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

完整项目结构

src/main/
├── java/com/example/
│   ├── Application.java          ← 启动类
│   ├── config/
│   │   └── MyBatisConfig.java    ← 可选：自定义配置
 │   ├── controller/
 │   │   └── EmpController.java
 │   ├── service/
 │   │   ├── EmpService.java
│   │   └── impl/EmpServiceImpl.java
│   ├── mapper/
│   │   ├── EmpMapper.java        ← Mapper 接口
│   │   └── DeptMapper.java
│   └── entity/
│       ├── Emp.java
│       └── Dept.java
└── resources/
    ├── application.yml
    ├── mybatis-config.xml        ← 可选
    ├── mapper/
    │   ├── EmpMapper.xml         ← Mapper XML
    │   └── DeptMapper.xml
    └── logback.xml

MyBatis-Plus

MyBatis-Plus 简介

MyBatis-Plus（简称 MP）是一个 MyBatis 的增强工具，在 MyBatis 的基础上只做增强不做改变，为简化开发、提高效率而生。

核心特性

 ┌─────────────────────────────────────────────┐
 │           MyBatis-Plus 核心特性               │
 ├──────────────┬─────────────────────────────┤
 │  无侵入       │ 只做增强不做改变              │
 │  损耗小       │ 启动即注入基本 CURD           │
 │  强大的 CRUD  │ 内置通用 Mapper/Service      │
 │  Lambda 表达式│ 编译期检查字段名              │
 │  主键自动生成  │ 支持多种主键策略              │
 │  代码生成器    │ 快速生成代码                 │
│  分页插件      │ 内置分页                    │
│  逻辑删除      │ 内置逻辑删除                 │
│  乐观锁        │ 内置乐观锁                   │
│  自动填充      │ 自动填充创建/更新时间         │
└──────────────┴─────────────────────────────┘

依赖

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>3.5.5</version>
</dependency>

实体类注解

 @TableName("emp")   // 指定表名
 public class Emp {
     @TableId(type = IdType.AUTO)   // 主键策略
     private Integer empId;
     @TableField("emp_name")        // 指定列名（驼峰自动映射时可省略）
     private String empName;
    @TableField("email")
    private String email;
    @TableField(exist = false)     // 非数据库字段
    private String tempField;
    @TableField(fill = FieldFill.INSERT)  // 插入时自动填充
    private LocalDateTime createTime;
    @TableField(fill = FieldFill.INSERT_UPDATE)  // 插入和更新时自动填充
    private LocalDateTime updateTime;
    @TableLogic                    // 逻辑删除字段
    @TableField("status")
    private Integer deleted;
    @Version                       // 乐观锁版本号
    private Integer version;
}

`IdType`	说明
`AUTO`	使用数据库自增主键
`NONE`	不指定主键策略，由全局配置或开发者决定
`INPUT`	插入前由开发者手动设置主键
`ASSIGN_ID`	使用默认标识符生成器分配 ID，通常为雪花算法生成的长整型值
`ASSIGN_UUID`	分配不带连字符的 UUID 字符串

BaseMapper 通用 CRUD

public interface EmpMapper extends BaseMapper<Emp> {
    // 自动拥有以下方法，无需编写 XML
}
// 使用
EmpMapper mapper = ...;
 // 插入
 mapper.insert(emp);
// 根据 ID 删除
mapper.deleteById(1);
// 根据 ID 更新
mapper.updateById(emp);
// 根据 ID 查询
Emp emp = mapper.selectById(1);
// 查询所有
List<Emp> list = mapper.selectList(null);
// 条件查询
List<Emp> list = mapper.selectList(
    new QueryWrapper<Emp>()
        .eq("dept_id", 1)
        .ge("salary", 10000)
        .like("emp_name", "张")
        .orderByDesc("salary")
);
// Lambda 条件查询（推荐）
List<Emp> list = mapper.selectList(
    new LambdaQueryWrapper<Emp>()
        .eq(Emp::getDeptId, 1)
        .ge(Emp::getSalary, new BigDecimal("10000"))
        .like(Emp::getEmpName, "张")
        .orderByDesc(Emp::getSalary)
);
// 查询数量
Long count = mapper.selectCount(null);
// 分页查询
Page<Emp> page = mapper.selectPage(
    new Page<>(1, 10),  // 第1页，每页10条
    new LambdaQueryWrapper<Emp>().eq(Emp::getStatus, 1)
);
List<Emp> records = page.getRecords();
long total = page.getTotal();

IService 通用 Service

// Service 接口
public interface EmpService extends IService<Emp> {}
// Service 实现
@Service
 public class EmpServiceImpl extends ServiceImpl<EmpMapper, Emp> implements EmpService
     {}
 // 使用
 @Autowired
private EmpService empService;
// 保存
empService.save(emp);
// 批量保存
empService.saveBatch(empList);
// 批量保存（每100条提交一次）
empService.saveBatch(empList, 100);
// 根据 ID 更新
empService.updateById(emp);
// 保存或更新
empService.saveOrUpdate(emp);
// 根据 ID 查询
Emp emp = empService.getById(1);
// 查询列表
List<Emp> list = empService.list();
// 条件查询
List<Emp> list = empService.list(
    new LambdaQueryWrapper<Emp>().eq(Emp::getDeptId, 1)
);
// 分页
Page<Emp> page = empService.page(
    new Page<>(1, 10),
    new LambdaQueryWrapper<Emp>().eq(Emp::getStatus, 1)
);
// 链式查询
List<Emp> list = empService.lambdaQuery()
    .eq(Emp::getDeptId, 1)
    .ge(Emp::getSalary, new BigDecimal("10000"))
    .list();
// 链式更新
empService.lambdaUpdate()
    .eq(Emp::getDeptId, 1)
    .set(Emp::getSalary, new BigDecimal("20000"))
    .update();
// 链式删除
empService.lambdaUpdate()
    .eq(Emp::getStatus, 0)
    .remove();

条件构造器常用方法

方法	作用
`eq(column, value)`	等于
`ne(column, value)`	不等于
`gt(column, value)`	大于
`ge(column, value)`	大于等于
`lt(column, value)`	小于
`le(column, value)`	小于等于
`like(column, value)`	模糊匹配，值两侧添加通配符
`likeLeft(column, value)`	左模糊匹配
`likeRight(column, value)`	右模糊匹配
`notLike(column, value)`	非模糊匹配
`in(column, list)`	集合包含
`notIn(column, list)`	集合不包含
`isNull(column)`	判断为空
`isNotNull(column)`	判断非空
`between(column, v1, v2)`	区间匹配
`notBetween(column, v1, v2)`	非区间匹配
`orderByDesc(column)`	降序排序
`orderByAsc(column)`	升序排序
`groupBy(column)`	分组
`having(condition)`	添加 `HAVING` 条件
`last(sql)`	在语句末尾拼接 SQL，必须确保内容可信
`select(columns...)`	指定查询列

分页插件配置

 @Configuration
 public class MybatisPlusConfig {
     @Bean
     public MybatisPlusInterceptor mybatisPlusInterceptor() {
         MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
         // 分页插件
         interceptor.addInnerInterceptor(
            new PaginationInnerInterceptor(DbType.MYSQL)
        );
        // 乐观锁插件
        interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());
        return interceptor;
    }
}

逻辑删除配置

mybatis-plus:
  global-config:
    db-config:
      logic-delete-field: deleted   # 逻辑删除字段
      logic-delete-value: 1         # 已删除值
      logic-not-delete-value: 0     # 未删除值

自动填充配置

 @Component
 public class MyMetaObjectHandler implements MetaObjectHandler {
     @Override
     public void insertFill(MetaObject metaObject) {
         this.strictInsertFill(metaObject, "createTime", LocalDateTime.class,
     LocalDateTime.now());
         this.strictInsertFill(metaObject, "updateTime", LocalDateTime.class,
     LocalDateTime.now());
     }
    @Override
    public void updateFill(MetaObject metaObject) {
        this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class,
     LocalDateTime.now());
    }
}

代码生成器

MyBatis Generator (MBG)

 <!-- pom.xml -->
 <build>
     <plugins>
         <plugin>
             <groupId>org.mybatis.generator</groupId>
             <artifactId>mybatis-generator-maven-plugin</artifactId>
             <version>3.0.4</version>
             <configuration>
     <configurationFile>src/main/resources/generatorConfig.xml</configurationFile>
                <overwrite>true</overwrite>
                <verbose>true</verbose>
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>com.mysql</groupId>
                    <artifactId>mysql-connector-j</artifactId>
                    <version>8.3.0</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

 <!-- src/main/resources/generatorConfig.xml -->
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE generatorConfiguration PUBLIC
     "-//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN"
     "https://mybatis.org/dtd/mybatis-generator-config_1_0.dtd">
 <generatorConfiguration>
     <context id="default" targetRuntime="MyBatis3">
        <!-- 不生成注释 -->
        <commentGenerator>
            <property name="suppressAllComments" value="true"/>
        </commentGenerator>
        <!-- 数据库连接 -->
        <jdbcConnection driverClass="com.mysql.cj.jdbc.Driver"
                        connectionURL="jdbc:mysql://localhost:3306/mydb"
                        userId="root"
                        password="root123"/>
        <!-- 实体类生成路径 -->
        <javaModelGenerator targetPackage="com.example.entity"
                            targetProject="src/main/java">
            <property name="enableSubPackages" value="true"/>
            <property name="trimStrings" value="true"/>
        </javaModelGenerator>
        <!-- Mapper XML 生成路径 -->
        <sqlMapGenerator targetPackage="mapper"
                         targetProject="src/main/resources">
            <property name="enableSubPackages" value="true"/>
        </sqlMapGenerator>
        <!-- Mapper 接口生成路径 -->
        <javaClientGenerator type="XMLMAPPER" targetPackage="com.example.mapper"
                             targetProject="src/main/java">
            <property name="enableSubPackages" value="true"/>
        </javaClientGenerator>
        <!-- 要生成的表 -->
        <table tableName="emp" domainObjectName="Emp"
               enableCountByExample="false"
               enableUpdateByExample="false"
               enableDeleteByExample="false"
               enableSelectByExample="false"
               selectByExampleQueryId="false"/>
        <table tableName="dept" domainObjectName="Dept"/>
    </context>
</generatorConfiguration>

1mvn mybatis-generator:generate

MyBatis-Plus 代码生成器

 // 依赖
 // mybatis-plus-generator 3.5.5
 // velocity-engine-core 2.3
 public class CodeGenerator {
     public static void main(String[] args) {
         FastAutoGenerator.create(
                 "jdbc:mysql://localhost:3306/mydb",
                 "root",
                "root123"
        )
        .globalConfig(builder -> {
            builder.author("example")
                   .outputDir(System.getProperty("user.dir") + "/src/main/java")
                   .commentDate("yyyy-MM-dd");
        })
        .packageConfig(builder -> {
            builder.parent("com.example")
                   .entity("entity")
                   .mapper("mapper")
                   .service("service")
                   .serviceImpl("service.impl")
                   .controller("controller")
                   .pathInfo(Collections.singletonMap(
                       OutputFile.xml,
                       System.getProperty("user.dir") + "/src/main/resources/mapper"));
        })
        .strategyConfig(builder -> {
            builder.addInclude("emp", "dept")     // 表名
                   .addTablePrefix("t_", "sys_")  // 去除表前缀
                   .entityBuilder()
                       .enableLombok()
                       .enableTableFieldAnnotation()
                       .logicDeleteColumnName("deleted")
                       .versionColumnName("version")
                   .mapperBuilder()
                       .enableMapperAnnotation()
                   .serviceBuilder()
                       .formatServiceFileName("%sService")
                       .formatServiceImplFileName("%sServiceImpl");
        })
        .templateEngine(new VelocityTemplateEngine())
        .execute();
    }
}

性能优化

SQL 优化

使用 #{} 而非 ${}（防止 SQL 注入 + 利用预编译缓存）
避免 SELECT *，只查需要的列**
合理使用索引（参考 MySQL 索引指南）
避免 N+1 问题（使用嵌套结果代替嵌套查询，或使用延迟加载）
大批量操作使用 Batch 执行器

缓存优化

合理使用二级缓存（读多写少的场景）
缓存粒度控制（useCache / flushCache）
集成 Redis 等分布式缓存（替代本地缓存）

延迟加载

<!-- 开启延迟加载，减少不必要的关联查询 -->
<setting name="lazyLoadingEnabled" value="true"/>
<setting name="aggressiveLazyLoading" value="false"/>

连接池优化

<!-- 使用 HikariCP 高性能连接池 -->
<dataSource type="POOLED">
    <property name="poolMaximumActiveConnections" value="20"/>
    <property name="poolMaximumIdleConnections" value="10"/>
    <property name="poolMaximumCheckoutTime" value="20000"/>
    <property name="poolPingEnabled" value="true"/>
    <property name="poolPingQuery" value="SELECT 1"/>
</dataSource>

批量操作优化

 // 使用 Batch 执行器
 try (SqlSession session = factory.openSession(ExecutorType.BATCH)) {
     EmpMapper mapper = session.getMapper(EmpMapper.class);
     for (int i = 0; i < 10000; i++) {
         mapper.insert(emp);
         if (i % 1000 == 0) {
             session.flushStatements();  // 分批 flush
         }
     }
    session.commit();
}

fetchSize 优化

<!-- 大数据量查询时设置 fetchSize，减少网络交互 -->
<select id="selectLargeData" resultType="Emp" fetchSize="1000">
    SELECT * FROM emp
</select>

开启日志查看 SQL（开发环境）

<settings>
    <setting name="logImpl" value="SLF4J"/>
</settings>

性能优化清单

优化项	说明	优先级
SQL 优化	合理使用索引、避免全表扫描	⭐⭐⭐
避免嵌套查询 N+1	使用 join 或延迟加载	⭐⭐⭐
批量操作	Batch 执行器	⭐⭐⭐
连接池调优	合理设置连接数	⭐⭐
二级缓存	读多写少场景	⭐⭐
延迟加载	减少不必要查询	⭐⭐
fetchSize	大数据量查询	⭐
映射优化	只映射需要的字段	⭐

常见问题与排错

`BindingException`：找不到映射语句

症状：org.apache.ibatis.binding.BindingException: Invalid bound statement (not found)

原因：Mapper 接口方法与 XML 中的 statement id 不匹配

解决：

检查 namespace 是否与接口全限定名一致
检查 id 是否与方法名一致
检查 XML 文件是否被正确加载（mapper-locations 配置）

参数绑定错误

症状：There is no getter for property named ‘xxx’

原因：MyBatis 对单参数的处理规则

解决：

// 方式一：加 @Param
List<Emp> select(@Param("empName") String empName);
// 方式二：用对象包装
List<Emp> select(Emp query);
// 方式三：用 Map
List<Emp> select(Map<String, Object> params);

中文乱码

解决：

数据库 URL 加 characterEncoding=UTF-8
XML 文件编码设为 UTF-8
配置 <setting name=“logImpl” value=“SLF4J”/> 确保日志正确

一级缓存导致数据不一致

场景：同一次 SqlSession 中，其他事务修改了数据，当前 session 仍返回旧数据

解决：

<!-- 关闭一级缓存 -->
<setting name="localCacheScope" value="STATEMENT"/>
<!-- 或在查询时刷新 -->
<select id="selectFresh" flushCache="true">...</select>

二级缓存序列化错误

症状：NotSerializableException

解决：实体类实现 Serializable 接口

嵌套查询 N+1 问题

解决：

使用嵌套结果（join）代替嵌套查询
开启延迟加载
使用 MyBatis-Plus 的批量查询

${} 导致 SQL 注入

解决：

尽量使用 #{}
必须用 ${} 时（表名/列名/排序），做输入校验

自动映射不生效

检查：

mapUnderscoreToCamelCase 是否设为 true
autoMappingBehavior 是否为 PARTIAL 或 FULL
ResultMap 的 autoMapping 是否为 true

动态 SQL 中的比较符号问题

解决：

<!-- 方式一：转义 -->
<if test="salary &gt; 10000">
<!-- 方式二：CDATA -->
<if test="salary <![CDATA[ > ]]> 10000">

PageHelper 分页不生效

检查：

PageHelper.startPage() 必须在查询方法前一行调用
确保只对紧随其后的第一个查询生效
检查插件配置是否正确

实战案例集

案例一：部门员工三级关联查询

 <!-- 查询部门→员工→项目（三级嵌套） -->
 <resultMap id="deptEmpProjectResultMap" type="Dept">
     <id property="deptId" column="dept_id"/>
     <result property="deptName" column="dept_name"/>
     <collection property="emps" ofType="Emp">
         <id property="empId" column="emp_id"/>
         <result property="empName" column="emp_name"/>
         <result property="salary" column="salary"/>
        <collection property="projects" ofType="Project">
            <id property="projectId" column="project_id"/>
            <result property="projectName" column="project_name"/>
            <result property="budget" column="budget"/>
        </collection>
    </collection>
</resultMap>
<select id="selectDeptEmpProject" resultMap="deptEmpProjectResultMap">
    SELECT
        d.dept_id, d.dept_name,
        e.emp_id, e.emp_name, e.salary,
        p.project_id, p.project_name, p.budget
    FROM dept d
    LEFT JOIN emp e ON d.dept_id = e.dept_id
    LEFT JOIN emp_project ep ON e.emp_id = ep.emp_id
    LEFT JOIN project p ON ep.project_id = p.project_id
    WHERE d.dept_id = #{deptId}
</select>

案例二：通用条件分页查询

 // DTO
 @Data
 public class EmpQueryDTO {
     private String empName;
     private Integer deptId;
     private BigDecimal minSalary;
     private BigDecimal maxSalary;
     private Integer status;
     private Integer pageNum = 1;
    private Integer pageSize = 10;
}

 <select id="selectByPage" resultType="Emp">
     SELECT
     <include refid="empColumns"/>
     FROM emp
     <where>
         <if test="empName != null and empName != ''">
             <bind name="likeName" value="'%' + empName + '%'"/>
             AND emp_name LIKE #{likeName}
         </if>
        <if test="deptId != null">
            AND dept_id = #{deptId}
        </if>
        <if test="minSalary != null">
            AND salary &gt;= #{minSalary}
        </if>
        <if test="maxSalary != null">
            AND salary &lt;= #{maxSalary}
        </if>
        <if test="status != null">
            AND status = #{status}
        </if>
    </where>
    ORDER BY emp_id DESC
</select>

// Service
public PageInfo<Emp> getEmpPage(EmpQueryDTO dto) {
    PageHelper.startPage(dto.getPageNum(), dto.getPageSize());
    List<Emp> list = empMapper.selectByPage(dto);
    return new PageInfo<>(list);
}

案例三：批量导入（Excel 数据导入）

 @Transactional
 public void batchImport(List<EmpDTO> dtoList) {
     List<Emp> empList = dtoList.stream().map(dto -> {
         Emp emp = new Emp();
         emp.setEmpName(dto.getName());
         emp.setEmail(dto.getEmail());
         emp.setSalary(dto.getSalary());
         emp.setDeptId(dto.getDeptId());
         emp.setHireDate(dto.getHireDate());
        emp.setStatus(1);
        return emp;
    }).collect(Collectors.toList());
    // 分批插入，每 500 条一批
    int batchSize = 500;
    for (int i = 0; i < empList.size(); i += batchSize) {
        int end = Math.min(i + batchSize, empList.size());
        List<Emp> batch = empList.subList(i, end);
        empMapper.batchInsert(batch);
    }
}

案例四：自定义 TypeHandler（JSON 存储）

// 实体类
@Data
public class Emp {
    private Integer empId;
    private String empName;
    // JSON 格式存储到数据库
    private Map<String, Object> extInfo;
}

 @MappedTypes(Map.class)
 @MappedJdbcTypes(JdbcType.VARCHAR)
 public class JsonTypeHandler extends BaseTypeHandler<Map<String, Object>> {
     private static final ObjectMapper mapper = new ObjectMapper();
     @Override
     public void setNonNullParameter(PreparedStatement ps, int i,
                                     Map<String, Object> parameter, JdbcType jdbcType)
     throws SQLException {
        try {
            ps.setString(i, mapper.writeValueAsString(parameter));
        } catch (JsonProcessingException e) {
            throw new SQLException("JSON 序列化失败", e);
        }
    }
    @Override
    public Map<String, Object> getNullableResult(ResultSet rs, String columnName)
     throws SQLException {
        return parse(rs.getString(columnName));
    }
    @Override
    public Map<String, Object> getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
        return parse(rs.getString(columnIndex));
    }
    @Override
    public Map<String, Object> getNullableResult(CallableStatement cs, int columnIndex)
     throws SQLException {
        return parse(cs.getString(columnIndex));
    }
    private Map<String, Object> parse(String json) {
        if (json == null || json.isEmpty()) return null;
        try {
            return mapper.readValue(json, new TypeReference<Map<String, Object>>() {});
        } catch (JsonProcessingException e) {
            return null;
        }
    }
}

案例五：SQL 审计拦截器

 @Intercepts({
     @Signature(type = Executor.class, method = "query",
                args = {MappedStatement.class, Object.class, RowBounds.class,
     ResultHandler.class}),
     @Signature(type = Executor.class, method = "update",
                args = {MappedStatement.class, Object.class})
 })
 public class SlowSqlInterceptor implements Interceptor {
     private static final long THRESHOLD = 1000;  // 1秒
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        MappedStatement ms = (MappedStatement) invocation.getArgs()[0];
        Object parameter = invocation.getArgs()[1];
        BoundSql boundSql = ms.getBoundSql(parameter);
        String sql = boundSql.getSql().replaceAll("\\s+", " ").trim();
        long start = System.currentTimeMillis();
        Object result;
        try {
            result = invocation.proceed();
        } finally {
            long elapsed = System.currentTimeMillis() - start;
            if (elapsed > THRESHOLD) {
                log.warn("[慢SQL] {}ms | {} | {}", elapsed, ms.getId(), sql);
            } else {
                log.debug("[SQL] {}ms | {} | {}", elapsed, ms.getId(), sql);
            }
        }
        return result;
    }
    @Override
    public Object plugin(Object target) {
        return Plugin.wrap(target, this);
    }
    @Override
    public void setProperties(Properties properties) {}
}

案例六：MyBatis-Plus 完整 CRUD

 // 实体类
 @TableName("emp")
 @Data
 public class Emp {
     @TableId(type = IdType.AUTO)
     private Long empId;
     @TableField("emp_name")
     private String empName;
    private String email;
    private BigDecimal salary;
    private Integer deptId;
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;
    @TableLogic
    private Integer deleted;
}
// Mapper
public interface EmpMapper extends BaseMapper<Emp> {
    // 自定义查询
    @Select("SELECT e.* FROM emp e WHERE e.salary > #{salary}")
    List<Emp> selectHighSalary(@Param("salary") BigDecimal salary);
}
// Service
@Service
public class EmpServiceImpl extends ServiceImpl<EmpMapper, Emp> implements EmpService {
    public Page<Emp> getEmpPage(int pageNum, int pageSize, EmpQueryDTO query) {
        return this.page(
            new Page<>(pageNum, pageSize),
            new LambdaQueryWrapper<Emp>()
                .like(StrUtil.isNotBlank(query.getEmpName()), Emp::getEmpName,
     query.getEmpName())
                .eq(query.getDeptId() != null, Emp::getDeptId, query.getDeptId())
                .ge(query.getMinSalary() != null, Emp::getSalary, query.getMinSalary())
                .le(query.getMaxSalary() != null, Emp::getSalary, query.getMaxSalary())
                .eq(Emp::getDeleted, 0)
                .orderByDesc(Emp::getCreateTime)
        );
    }
    public List<Emp> batchUpsert(List<Emp> empList) {
        this.saveOrUpdateBatch(empList, 500);
        return empList;
    }
}
// Controller
@RestController
@RequestMapping("/emp")
public class EmpController {
    @Autowired
    private EmpService empService;
    @GetMapping("/page")
    public Result<Page<Emp>> page(@RequestParam(defaultValue = "1") int pageNum,
                                   @RequestParam(defaultValue = "10") int pageSize,
                                   EmpQueryDTO query) {
        return Result.ok(empService.getEmpPage(pageNum, pageSize, query));
    }
    @PostMapping
    public Result<Void> save(@RequestBody Emp emp) {
        empService.save(emp);
        return Result.ok();
    }
    @PutMapping
    public Result<Void> update(@RequestBody Emp emp) {
        empService.updateById(emp);
        return Result.ok();
    }
    @DeleteMapping("/{id}")
    public Result<Void> delete(@PathVariable Long id) {
        empService.removeById(id);  // 逻辑删除
        return Result.ok();
    }
}

速查手册

核心配置速查

配置项	默认值	说明
`mapUnderscoreToCamelCase`	`false`	下划线命名自动映射为驼峰命名
`cacheEnabled`	`true`	是否允许使用映射器二级缓存
`lazyLoadingEnabled`	`false`	是否启用延迟加载
`defaultExecutorType`	`SIMPLE`	默认执行器类型
`localCacheScope`	`SESSION`	一级缓存作用域
`jdbcTypeForNull`	`OTHER`	`null` 参数使用的 JDBC 类型
`useGeneratedKeys`	`false`	是否允许 JDBC 自动生成主键
`autoMappingBehavior`	`PARTIAL`	自动映射级别

动态 SQL 速查

元素	用途	说明
`<if>`	条件判断	条件成立时拼接 SQL 片段
`<where>`	生成 `WHERE`	自动移除开头多余的 `AND` 或 `OR`
`<set>`	生成 `SET`	自动移除末尾多余的逗号
`<choose>`	多分支选择	与 `<when>`、`<otherwise>` 配合
`<trim>`	自定义裁剪	使用前缀、后缀和覆盖规则调整 SQL
`<foreach>`	遍历集合	常用于 `IN` 条件和批量写入
`<bind>`	绑定表达式结果	可预先构造供后续引用的变量
`<sql>`	定义 SQL 片段	通过 `<include>` 复用

关联映射速查

元素	用途	常用属性
`<association>`	一对一关联	`property`、`javaType`、`column`、`select`、`fetchType`
`<collection>`	一对多关联	`property`、`ofType`、`column`、`select`、`fetchType`
`<discriminator>`	根据列值选择映射	`column`、`javaType`、`case`

参数占位符速查

特性	`#{}`	`${}`
处理方式	预编译参数占位	字符串直接替换
SQL 注入风险	较低	较高
典型用途	参数值	经过白名单校验的表名、列名或排序片段

缓存速查

特性	一级缓存	二级缓存
作用域	`SqlSession`	Mapper 命名空间
默认状态	开启	需要在映射文件中配置
常见失效时机	更新、提交、回滚、关闭会话或清空缓存	同命名空间执行更新语句时通常会刷新

注解速查

注解	说明
`@Select`	声明查询语句
`@Insert`	声明插入语句
`@Update`	声明更新语句
`@Delete`	声明删除语句
`@Results`、`@Result`	声明结果映射
`@One`、`@Many`	声明关联查询
`@Options`	配置主键回填、缓存等选项
`@Param`	为方法参数命名

常见错误速查

现象	常见原因	排查方向
`BindingException`	映射语句未注册	检查命名空间、语句 ID 和映射文件扫描路径
找不到属性的 getter	参数名或表达式不匹配	检查 `@Param`、实体属性与 OGNL 表达式
`NotSerializableException`	二级缓存对象不可序列化	让缓存对象实现 `Serializable`，或调整缓存实现
N+1 查询	嵌套查询逐条执行	评估联表查询、批量查询或延迟加载
中文乱码	客户端、连接或数据库编码不一致	统一字符集配置

附录：MyBatis 知识体系全景

 MyBatis 知识体系
 ├── 基础
 │   ├── 概述与架构
 │   ├── 快速入门
 │   ├── 核心配置文件
 │   └── SqlSession 与映射器
 │
 ├── SQL 映射
 │   ├── Mapper XML（select/insert/update/delete）
│   ├── #{} vs ${}
│   ├── 参数传递（@Param/Map/对象/List）
│   ├── SQL 片段（<sql>/<include>）
│   └── 主键回填（useGeneratedKeys/selectKey）
│
├── 结果映射
│   ├── ResultMap（id/result/constructor）
│   ├── 自动映射（autoMappingBehavior）
│   ├── ResultMap 继承（extends）
│   └── 鉴别器（discriminator）
│
├── 动态 SQL
│   ├── if / where / set
│   ├── choose / when / otherwise
│   ├── trim / foreach / bind
│   └── SQL 片段复用
│
├── 关联查询
│   ├── 一对一（association）
│   ├── 一对多（collection）
│   ├── 多对多
│   ├── 嵌套结果 vs 嵌套查询
│   └── 延迟加载
│
├── 缓存
│   ├── 一级缓存（SqlSession）
│   ├── 二级缓存（namespace）
│   ├── 第三方缓存（EhCache/Redis）
│   └── cache-ref
│
├── 高级特性
│   ├── TypeHandler 类型处理器
│   ├── ObjectFactory 对象工厂
│   ├── Plugin 插件机制
│   ├── 分页（RowBounds/PageHelper）
│   └── 批量操作（foreach/Batch执行器）
│
├── 注解开发
│   ├── 基本 CRUD 注解
│   ├── @Results/@Result
│   ├── @One/@Many
│   └── @SelectProvider 等
│
├── 框架集成
│   ├── Spring 集成
│   ├── Spring Boot 集成
│   └── MyBatis-Plus
│
├── 工具
│   ├── 代码生成器（MBG/MP Generator）
│   └── 分页插件（PageHelper）
│
├── 性能优化
│   ├── SQL 优化
│   ├── 缓存策略
│   ├── 延迟加载
│   ├── 批量操作
│   ├── 连接池调优
│   └── fetchSize
│
└── 排错
    ├── BindingException
    ├── 参数绑定错误
    ├── 编码问题
    ├── 缓存问题
    └── N+1 问题

文档说明：本文档全面覆盖了 MyBatis 的所有知识点，从基础概念到高级实战，从理论到指令操作，无遗漏。适合初学者系统学习，也适合有经验的开发者作为参考手册。配合之前的 MySQL（JOIN/子查询/事务/索引）和 Maven 指南使用，可构建完整的 Java 后端知识体系。

MyBatis 逆向工程完全指南

Thu, 30 Jul 2026 11:30:20 GMT

MyBatis 逆向工程完全指南

本文档全面覆盖 MyBatis 逆向工程（代码生成器）的所有知识点，包括 MyBatis Generator (MBG) 官方工具与 MyBatis-Plus 代码生成器，从配置到实战，无遗漏。

逆向工程概述

什么是逆向工程

MyBatis 逆向工程（Reverse Engineering）是指通过数据库表结构，自动生成 Java 实体类、Mapper 接口、 Mapper XML 映射文件的过程。

数据库表结构  ──→  逆向工程工具  ──→  Java 实体类
                    (Generator)       Mapper 接口
                                      Mapper XML
                                      Example 类
                                      Service（MP）
                                      Controller（MP）

为什么需要逆向工程

传统手写方式	逆向工程方式
手动创建实体类，逐个字段映射	自动生成，一键完成
手写 CRUD 的 SQL 语句	自动生成单表 CRUD
容易拼写错误、遗漏字段	与数据库完全一致
新增字段需要手动修改多处	重新生成即可
耗时且枯燥	秒级完成

主流逆向工程工具对比

工具	全称	维护方	特点
MyBatis Generator (MBG)	MyBatis Generator	MyBatis 官方	官方工具，稳定可靠，生成实体+Mapper+XML+Example
MyBatis-Plus Generator	MP Code Generator	MyBatis-Plus 社区	功能更强，生成实体+Mapper+XML+Service+Controller，支持模板
IDEA 插件（Free MyBatis Tool）	EasyCode、MyBatisCodeHelper	第三方	可视化操作，适合快速开发
RuoYi 代码生成器	若依代码生成	RuoYi 社区	自带模板引擎，生成完整前后端代码

逆向工程能生成什么

MyBatis Generator 生成物：

src/main/java/
  └── com/example/entity/
      ├── User.java              ← 实体类（POJO）
      └── UserExample.java       ← 查询条件类（QBC风格）
  └── com/example/mapper/
      └── UserMapper.java        ← Mapper 接口
src/main/resources/
  └── mapper/
      └── UserMapper.xml         ← SQL 映射文件

MyBatis-Plus Generator 生成物：

 src/main/java/
   └── com/example/
       ├── entity/User.java       ← 实体类（含 Lombok / Swagger 注解）
       ├── mapper/UserMapper.java ← Mapper 接口（继承 BaseMapper）
       ├── service/
       │   ├── UserService.java       ← Service 接口
       │   └── impl/UserServiceImpl.java ← Service 实现
       └── controller/UserController.java ← Controller
 src/main/resources/
  └── mapper/
      └── UserMapper.xml         ← SQL 映射文件（可选）

MyBatis Generator 核心概念

MBG 架构总览

 ┌──────────────────────────────────────────────────┐
 │              MyBatis Generator                    │
 │                                                    │
 │  ┌──────────┐   ┌───────────┐   ┌──────────────┐ │
 │  │ Database  │   │ Generator  │   │  Generated   │ │
 │  │  Metadata │──→│   Engine   │──→│    Code      │ │
 │  │ (JDBC)    │   │ (Java)     │   │  (Java/XML)  │ │
 │  └──────────┘   └─────┬─────┘   └──────────────┘ │
 │                       │                            │
│              ┌────────┴────────┐                   │
│              │  Configuration  │                   │
│              │  (XML / Java)   │                   │
│              └─────────────────┘                   │
└──────────────────────────────────────────────────┘

MBG 工作流程

读取 generatorConfig.xml 或 Java 配置。
通过 JDBC 连接数据库并读取表、字段、主键和注释等元数据。
将 JDBC 类型转换为 Java 类型。
根据运行模式和模板生成实体类、Mapper 接口、XML 映射文件以及可选的 Example 条件类。
将生成结果写入指定目录。重新生成前应确认覆盖和合并策略，尤其要注意 XML 文件的合并行为。

MBG 版本说明

MyBatis Generator 使用 1.4.x 版本系列。本文示例采用 1.4.2，版本号用于保证示例可复现，不代表任何时点的“最新版本”。

Maven 坐标使用 org.mybatis.generator:mybatis-generator-core:1.4.2。

环境准备与依赖

项目目录结构

 mybatis-generator-demo/
 ├── pom.xml
 ├── src/
 │   ├── main/
 │   │   ├── java/
 │   │   │   └── com/example/
 │   │   │       ├── entity/
 │   │   │       ├── mapper/
 │   │   │       └── generator/
│   │   │           └── Generator.java
│   │   └── resources/
│   │       ├── generatorConfig.xml
│   │       └── mapper/
│   └── test/
└── lib/
    └── mysql-connector-j-8.0.33.jar

Maven 依赖（pom.xml）

 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
          http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <groupId>com.example</groupId>
     <artifactId>mybatis-generator-demo</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>
    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
    <dependencies>
        <!-- MyBatis -->
        <dependency>
            <groupId>org.mybatis</groupId>
            <artifactId>mybatis</artifactId>
            <version>3.5.16</version>
        </dependency>
        <!-- MySQL 驱动 -->
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <version>8.0.33</version>
        </dependency>
        <!-- MyBatis Generator 核心 -->
        <dependency>
            <groupId>org.mybatis.generator</groupId>
            <artifactId>mybatis-generator-core</artifactId>
            <version>1.4.2</version>
        </dependency>
        <!-- Log4j2（可选，用于日志输出） -->
        <dependency>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-core</artifactId>
            <version>2.22.1</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <!-- MyBatis Generator Maven 插件 -->
            <plugin>
                <groupId>org.mybatis.generator</groupId>
                <artifactId>mybatis-generator-maven-plugin</artifactId>
                <version>1.4.2</version>
                <configuration>
                    <!-- 配置文件路径 -->
                    <configurationFile>
                        src/main/resources/generatorConfig.xml
                    </configurationFile>
                    <!-- 是否覆盖已有文件 -->
                    <overwrite>true</overwrite>
                    <!-- 是否将 MBG 的输出打印到控制台 -->
                    <verbose>true</verbose>
                </configuration>
                <dependencies>
                    <!-- MySQL 驱动（插件也需要） -->
                    <dependency>
                        <groupId>com.mysql</groupId>
                        <artifactId>mysql-connector-j</artifactId>
                        <version>8.0.33</version>
                    </dependency>
                </dependencies>
            </plugin>
        </plugins>
    </build>
</project>

示例数据库

 -- 创建数据库
 CREATE DATABASE IF NOT EXISTS mybatis_demo DEFAULT CHARSET utf8mb4;
 USE mybatis_demo;
 -- 部门表
 CREATE TABLE dept (
     dept_id    INT PRIMARY KEY AUTO_INCREMENT COMMENT '部门ID',
     dept_name  VARCHAR(50) NOT NULL COMMENT '部门名称',
     location   VARCHAR(100) COMMENT '部门位置'
) COMMENT '部门表';
-- 员工表
CREATE TABLE emp (
    emp_id      INT PRIMARY KEY AUTO_INCREMENT COMMENT '员工ID',
    emp_name    VARCHAR(50) NOT NULL COMMENT '员工姓名',
    gender      CHAR(1) DEFAULT 'M' COMMENT '性别 M-男 F-女',
    email       VARCHAR(100) COMMENT '邮箱',
    salary      DECIMAL(10,2) COMMENT '工资',
    dept_id     INT COMMENT '所属部门ID',
    hire_date   DATE COMMENT '入职日期',
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT
     '更新时间',
    FOREIGN KEY (dept_id) REFERENCES dept(dept_id)
) COMMENT '员工表';
-- 插入测试数据
INSERT INTO dept VALUES (1, '研发部', '北京'), (2, '市场部', '上海'), (3, '财务部', '广州');
INSERT INTO emp VALUES
(1, '张三', 'M', 'zhangsan@qq.com', 15000.00, 1, '2020-01-15', NOW(), NOW()),
(2, '李四', 'F', 'lisi@qq.com', 12000.00, 2, '2021-03-20', NOW(), NOW()),
(3, '王五', 'M', 'wangwu@qq.com', 18000.00, 1, '2019-07-01', NOW(), NOW());

MBG 三种运行方式

方式一：Java 代码运行（推荐灵活场景）

 package com.example.generator;
 import org.mybatis.generator.api.MyBatisGenerator;
 import org.mybatis.generator.config.xml.ConfigurationParser;
 import org.mybatis.generator.config.Configuration;
 import org.mybatis.generator.internal.DefaultShellCallback;
 import java.io.File;
 import java.util.ArrayList;
import java.util.List;
public class Generator {
    public static void main(String[] args) throws Exception {
        List<String> warnings = new ArrayList<>();
        boolean overwrite = true;  // 是否覆盖已有文件
        // 指向配置文件
        File configFile = new File("src/main/resources/generatorConfig.xml");
        ConfigurationParser parser = new ConfigurationParser(warnings);
        Configuration config = parser.parseConfiguration(configFile);
        DefaultShellCallback callback = new DefaultShellCallback(overwrite);
        MyBatisGenerator generator = new MyBatisGenerator(config, callback, warnings);
        // 执行生成
        generator.generate(null);
        // 打印警告信息
        for (String warning : warnings) {
            System.out.println(warning);
        }
        System.out.println("✅ 代码生成完成！");
    }
}

运行方式： 直接右键 main 方法运行。

方式二：Maven 插件运行（推荐常规项目）

pom.xml 中已配置好插件后，执行命令：

# 在项目根目录执行
mvn mybatis-generator:generate
# 如果配置文件不在默认位置，指定路径
mvn mybatis-generator:generate -DconfigurationFile=src/main/resources/generatorConfig.xml
# 如果不想覆盖已有文件
mvn mybatis-generator:generate -Doverwrite=false

注意： Maven 插件方式默认读取 src/main/resources/generatorConfig.xml，如果配置文件放在此路径，无需额外指定。

方式三：命令行运行（适合脚本化）

# 1. 准备 mybatis-generator-core 和数据库驱动
# 2. 准备 generatorConfig.xml
# 3. 执行生成命令
java -jar mybatis-generator-core-1.4.2.jar -configfile generatorConfig.xml -overwrite

# 常用参数：
# -configfile 指定配置文件路径
# -overwrite 允许覆盖可覆盖的 Java 文件
# -verbose 输出详细信息

三种方式对比

特性	Java 代码运行	Maven 插件	命令行
灵活性	最高（可编程控制）	中等	最低
配置复杂度	中等	低	低
适合场景	需要自定义逻辑	日常开发	CI/CD 脚本
IDE 支持	直接运行	Maven 面板点击	需手动准备 jar

generatorConfig.xml 配置详解

完整配置模板

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE generatorConfiguration
         PUBLIC "-//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN"
         "http://mybatis.org/dtd/mybatis-generator-config_1_0.dtd">
 <generatorConfiguration>
     <!-- ① 引入外部属性文件 -->
     <properties resource="generator.properties"/>
    <!-- ② classPathEntry：指定数据库驱动路径（Maven插件方式可省略） -->
    <classPathEntry location="lib/mysql-connector-j-8.0.33.jar"/>
    <!-- ③ context：生成上下文（可配置多个） -->
    <context id="mysqlContext" targetRuntime="MyBatis3"
     defaultModelType="conditional">
        <!-- ====== 内置插件配置 ====== -->
        <!-- ④ 序列化插件（让实体类实现 Serializable） -->
        <plugin type="org.mybatis.generator.plugins.SerializablePlugin"/>
        <!-- ⑤ ToString 插件（生成 toString 方法） -->
        <plugin type="org.mybatis.generator.plugins.ToStringPlugin"/>
        <!-- ⑥ EqualsAndHashCode 插件 -->
        <plugin type="org.mybatis.generator.plugins.EqualsAndHashCodePlugin"/>
        <!-- ⑦ Row Bounds 插件（分页用，MySQL 不推荐） -->
        <!-- <plugin type="org.mybatis.generator.plugins.RowBoundsPlugin"/> -->
        <!-- ⑧ 虚拟主键插件 -->
        <!-- <plugin type="org.mybatis.generator.plugins.VirtualKeyPlugin"/> -->
        <!-- ====== 注释生成器 ====== -->
        <!-- ⑨ 自定义注释生成器 -->
        <commentGenerator>
            <!-- 是否去除自动生成的注释 true：去除 false：保留 -->
            <property name="suppressAllComments" value="false"/>
            <!-- 是否生成注释中的日期 -->
            <property name="suppressDate" value="true"/>
            <!-- 是否添加数据库表的字段备注 -->
            <property name="addRemarkComments" value="true"/>
        </commentGenerator>
        <!-- ====== 数据库连接 ====== -->
        <!-- ⑩ JDBC 连接配置 -->
         <jdbcConnection
             driverClass="${jdbc.driver}"
             connectionURL="${jdbc.url}"
             userId="${jdbc.username}"
             password="${jdbc.password}">
             <!-- MySQL 8.x 需要设置以下属性，才能获取表注释 -->
             <property name="useInformationSchema" value="true"/>
         </jdbcConnection>
         <!-- ====== 类型解析 ====== -->
         <!-- ⑪ Java 类型解析器 -->
         <javaTypeResolver>
             <!-- 是否强制使用 BigDecimal -->
             <property name="forceBigDecimals" value="false"/>
             <!-- 是否使用 JSR-310 日期类型（java.time） -->
             <property name="useJSR310Types" value="true"/>
         </javaTypeResolver>
         <!-- ====== 代码生成器 ====== -->
         <!-- ⑫ Java 实体类生成器 -->
         <javaModelGenerator
             targetPackage="com.example.entity"
             targetProject="src/main/java">
             <!-- 是否让 schema 作为包的后缀 -->
             <property name="enableSubPackages" value="false"/>
             <!-- 从数据库返回的值是否清理前后的空格 -->
             <property name="trimStrings" value="true"/>
             <!-- 是否为实体类生成构造方法 -->
             <property name="constructorBased" value="false"/>
             <!-- 是否不可变（final 类，全参构造，无 setter） -->
             <property name="immutable" value="false"/>
             <!-- 父类（所有实体类继承的基类） -->
             <!-- <property name="rootClass" value="com.example.BaseEntity"/> -->
         </javaModelGenerator>
         <!-- ⑬ SQL 映射文件生成器 -->
         <sqlMapGenerator
             targetPackage="mapper"
             targetProject="src/main/resources">
             <property name="enableSubPackages" value="false"/>
         </sqlMapGenerator>
         <!-- ⑭ Mapper 接口生成器 -->
         <javaClientGenerator
             type="XMLMAPPER"
             targetPackage="com.example.mapper"
             targetProject="src/main/java">
             <property name="enableSubPackages" value="false"/>
             <!-- 父接口（所有 Mapper 继承的接口） -->
             <!-- <property name="rootInterface" value="com.example.BaseMapper"/> -->
        </javaClientGenerator>
        <!-- ====== 表配置 ====== -->
        <!-- ⑮ table：每张表配置一个 -->
        <table schema="mybatis_demo" tableName="emp"
               domainObjectName="Emp"
               enableCountByExample="true"
               enableDeleteByExample="true"
               enableSelectByExample="true"
               enableUpdateByExample="true"
               enableDeleteByPrimaryKey="true"
               enableInsert="true"
               enableSelectByPrimaryKey="true"
               enableUpdateByPrimaryKey="true">
            <!-- 主键策略：将自增主键回填到实体 -->
            <generatedKey column="emp_id" sqlStatement="MySql" identity="true"/>
            <!-- 列覆盖：强制指定某列的 Java 类型 -->
            <!-- <columnOverride column="salary" property="salary"
      javaType="java.math.BigDecimal"/> -->
            <!-- 列忽略：不生成该字段 -->
            <!-- <ignoreColumn column="create_time"/> -->
        </table>
        <table schema="mybatis_demo" tableName="dept"
               domainObjectName="Dept"
               enableCountByExample="true"
               enableDeleteByExample="true"
               enableSelectByExample="true"
               enableUpdateByExample="true">
            <generatedKey column="dept_id" sqlStatement="MySql" identity="true"/>
        </table>
    </context>
</generatorConfiguration>

外部属性文件（generator.properties）

# generator.properties
jdbc.driver=com.mysql.cj.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/mybatis_demo?useSSL=false&serverTimezone=Asia/Shanghai&useUnicode=true&characterEncoding=UTF-8
jdbc.username=root
jdbc.password=123456

context 元素详解

context 属性

<context> 是配置的核心，所有生成规则都在其中定义。

<context id="mysqlContext"
         targetRuntime="MyBatis3"
         defaultModelType="conditional"
         introspectedColumnImpl="org.mybatis.generator.internal.db.DatabaseIntrospector"
         autoDelimitKeywords="false"
         beginningDelimiter="`"
         endingDelimiter="`">

属性	说明	常用值
`id`	当前上下文的唯一标识	任意不重复字符串
`targetRuntime`	选择生成器运行模式	`MyBatis3`、`MyBatis3Simple`、`MyBatis3DynamicSql` 等
`defaultModelType`	设置模型类结构	`conditional`、`flat`、`hierarchical`
`autoDelimitKeywords`	是否自动为数据库关键字添加分隔符	`true`、`false`
`beginningDelimiter`	关键字起始分隔符	MySQL 通常使用反引号
`endingDelimiter`	关键字结束分隔符	MySQL 通常使用反引号

targetRuntime 详解

值	说明	生成物
MyBatis3	默认，生成完整代码	实体 + Example + Mapper + XML（含 Example 方法）
MyBatis3Simple	简化版，不生成 Example	实体 + Mapper + XML（仅基本 CRUD）
MyBatis3DynamicSql	动态 SQL 版（需 MyBatis 3.4.0+）	实体 + Mapper（使用 DSL，无 XML）
MyBatis3Kotlin	Kotlin 版	Kotlin 实体 + DSL Mapper

MyBatis3Simple 生成的 Mapper 方法（无 Example）：

insert()
deleteByPrimaryKey()
updateByPrimaryKey()
selectByPrimaryKey()
selectAll()

MyBatis3 生成的 Mapper 方法（有 Example）：

 insert()
 deleteByPrimaryKey()
 updateByPrimaryKey()
 selectByPrimaryKey()
 selectAll() (Simple 没有)
 countByExample()
 deleteByExample()
 selectByExample()
 updateByExampleSelective()
updateByExample()

defaultModelType 详解

值	说明	使用场景
conditional	默认。如果表只有一个主键，不生成主键类；有复合主键则生成主键类	大多数场景
flat	所有表都生成一个扁平的实体类，主键也作为普通字段	简单单表
hierarchical	生成层次结构：主键类继承→基础实体类→带 BLOB 的类	有 BLOB 字段的复杂表

hierarchical 模式生成的类结构：

Emp.java           ← 继承 EmpKey，包含普通字段
EmpKey.java        ← 仅包含主键字段
EmpWithBLOBs.java  ← 继承 Emp，包含 BLOB 字段（如 TEXT/LONGTEXT）

jdbcConnection — 数据库连接

基本配置

<jdbcConnection
    driverClass="com.mysql.cj.jdbc.Driver"
    connectionURL="jdbc:mysql://localhost:3306/mybatis_demo?
    useSSL=false&serverTimezone=Asia/Shanghai"
    userId="root"
    password="123456">
</jdbcConnection>

MySQL 8.x 特殊配置

 <jdbcConnection
     driverClass="com.mysql.cj.jdbc.Driver"
     connectionURL="jdbc:mysql://localhost:3306/mybatis_demo"
     userId="root"
     password="123456">
     <!-- ★ 关键：使用 information_schema 获取表/字段注释 -->
     <property name="useInformationSchema" value="true"/>
    <!-- 其他可选属性 -->
    <property name="nullCatalogMeansCurrent" value="true"/>
    <property name="characterEncoding" value="utf-8"/>
    <property name="serverTimezone" value="Asia/Shanghai"/>
</jdbcConnection>

重要： MySQL 8.x 默认不返回表注释和字段注释。必须设置 useInformationSchema=true，否则 commentGenerator 的 addRemarkComments 无效。

各数据库连接配置参考

 <!-- MySQL 8.x -->
 <jdbcConnection
     driverClass="com.mysql.cj.jdbc.Driver"
     connectionURL="jdbc:mysql://localhost:3306/mybatis_demo?
     useSSL=false&amp;serverTimezone=Asia/Shanghai"
     userId="root" password="123456">
     <property name="useInformationSchema" value="true"/>
 </jdbcConnection>
 <!-- PostgreSQL -->
<jdbcConnection
    driverClass="org.postgresql.Driver"
    connectionURL="jdbc:postgresql://localhost:5432/mydb"
    userId="postgres" password="123456"/>
<!-- Oracle -->
<jdbcConnection
    driverClass="oracle.jdbc.OracleDriver"
    connectionURL="jdbc:oracle:thin:@localhost:1521:orcl"
    userId="scott" password="tiger"/>
<!-- SQL Server -->
<jdbcConnection
    driverClass="com.microsoft.sqlserver.jdbc.SQLServerDriver"
    connectionURL="jdbc:sqlserver://localhost:1433;databaseName=mydb"
    userId="sa" password="123456"/>

javaModelGenerator — 实体类生成

基本配置

 <javaModelGenerator
     targetPackage="com.example.entity"
     targetProject="src/main/java">
     <!-- 是否让 schema 作为包名后缀 -->
     <!-- true: com.example.entity.mybatis_demo.Emp -->
     <!-- false: com.example.entity.Emp -->
     <property name="enableSubPackages" value="false"/>
    <!-- 是否清理从数据库返回的字符串前后的空格 -->
    <property name="trimStrings" value="true"/>
    <!-- 是否基于构造方法（生成全参构造 + setter） -->
    <property name="constructorBased" value="false"/>
    <!-- 是否生成不可变类（final + 全参构造 + 无 setter） -->
    <property name="immutable" value="false"/>
    <!-- 所有实体类的父类 -->
    <!-- <property name="rootClass" value="com.example.BaseEntity"/> -->
</javaModelGenerator>

生成的实体类示例

配置： targetPackage=“com.example.entity”, trimStrings=“true”

 package com.example.entity;
 import java.math.BigDecimal;
 import java.time.LocalDate;
 import java.time.LocalDateTime;
 public class Emp {
     private Integer empId;
    private String empName;
    private String gender;
    private String email;
    private BigDecimal salary;
    private Integer deptId;
    private LocalDate hireDate;
    private LocalDateTime createTime;
    private LocalDateTime updateTime;
    // ====== 构造方法 ======
    public Emp(Integer empId, String empName, String gender, String email,
               BigDecimal salary, Integer deptId, LocalDate hireDate,
               LocalDateTime createTime, LocalDateTime updateTime) {
        this.empId = empId;
        this.empName = empName == null ? null : empName.trim();
        this.gender = gender;
        this.email = email == null ? null : email.trim();
        this.salary = salary;
        this.deptId = deptId;
        this.hireDate = hireDate;
        this.createTime = createTime;
        this.updateTime = updateTime;
    }
    public Emp() {
    }
    // ====== getter / setter ======
    public Integer getEmpId() {
        return empId;
    }
    public void setEmpId(Integer empId) {
        this.empId = empId;
    }
    public String getEmpName() {
        return empName;
    }
    public void setEmpName(String empName) {
        this.empName = empName == null ? null : empName.trim();
    }
    // ... 其他 getter/setter 省略 ...
}

rootClass 示例

// BaseEntity.java — 所有实体类的父类
package com.example.entity;
import java.time.LocalDateTime;
public abstract class BaseEntity {
    private LocalDateTime createTime;
    private LocalDateTime updateTime;
    // getter / setter
    public LocalDateTime getCreateTime() { return createTime; }
    public void setCreateTime(LocalDateTime createTime) { this.createTime = createTime;
     }
    public LocalDateTime getUpdateTime() { return updateTime; }
    public void setUpdateTime(LocalDateTime updateTime) { this.updateTime = updateTime;
     }
}

配置 rootClass 后，create_time 和 update_time 字段不会被重复生成在子类中。

sqlMapGenerator — XML 映射文件生成

基本配置

<sqlMapGenerator
    targetPackage="mapper"
    targetProject="src/main/resources">
    <property name="enableSubPackages" value="false"/>
</sqlMapGenerator>

生成的 XML 示例（EmpMapper.xml）

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
         "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
 <mapper namespace="com.example.mapper.EmpMapper">
     <resultMap id="BaseResultMap" type="com.example.entity.Emp">
         <id column="emp_id" property="empId" jdbcType="INTEGER"/>
         <result column="emp_name" property="empName" jdbcType="VARCHAR"/>
         <result column="gender" property="gender" jdbcType="CHAR"/>
        <result column="email" property="email" jdbcType="VARCHAR"/>
        <result column="salary" property="salary" jdbcType="DECIMAL"/>
        <result column="dept_id" property="deptId" jdbcType="INTEGER"/>
        <result column="hire_date" property="hireDate" jdbcType="DATE"/>
        <result column="create_time" property="createTime" jdbcType="TIMESTAMP"/>
        <result column="update_time" property="updateTime" jdbcType="TIMESTAMP"/>
    </resultMap>
    <!-- 通用列名 -->
    <sql id="Base_Column_List">
        emp_id, emp_name, gender, email, salary, dept_id, hire_date, create_time,
        update_time
    </sql>
    <!-- 按主键查询 -->
    <select id="selectByPrimaryKey" parameterType="java.lang.Integer"
            resultMap="BaseResultMap">
        SELECT
        <include refid="Base_Column_List"/>
        FROM emp
        WHERE emp_id = #{empId,jdbcType=INTEGER}
    </select>
    <!-- 删除 -->
    <delete id="deleteByPrimaryKey" parameterType="java.lang.Integer">
        DELETE FROM emp
        WHERE emp_id = #{empId,jdbcType=INTEGER}
    </delete>
    <!-- 插入 -->
    <insert id="insert" parameterType="com.example.entity.Emp"
            useGeneratedKeys="true" keyProperty="empId">
        INSERT INTO emp (emp_name, gender, email,
                         salary, dept_id, hire_date,
                         create_time, update_time)
        VALUES (#{empName,jdbcType=VARCHAR}, #{gender,jdbcType=CHAR},
                #{email,jdbcType=VARCHAR}, #{salary,jdbcType=DECIMAL},
                #{deptId,jdbcType=INTEGER}, #{hireDate,jdbcType=DATE},
                #{createTime,jdbcType=TIMESTAMP}, #{updateTime,jdbcType=TIMESTAMP})
    </insert>
    <!-- 选择性插入（null 字段不插入） -->
    <insert id="insertSelective" parameterType="com.example.entity.Emp"
            useGeneratedKeys="true" keyProperty="empId">
        INSERT INTO emp
        <trim prefix="(" suffix=")" suffixOverrides=",">
            <if test="empName != null">emp_name,</if>
            <if test="gender != null">gender,</if>
            <if test="email != null">email,</if>
            <if test="salary != null">salary,</if>
            <if test="deptId != null">dept_id,</if>
            <if test="hireDate != null">hire_date,</if>
            <if test="createTime != null">create_time,</if>
            <if test="updateTime != null">update_time,</if>
        </trim>
        <trim prefix="VALUES (" suffix=")" suffixOverrides=",">
            <if test="empName != null">#{empName,jdbcType=VARCHAR},</if>
            <if test="gender != null">#{gender,jdbcType=CHAR},</if>
            <if test="email != null">#{email,jdbcType=VARCHAR},</if>
            <if test="salary != null">#{salary,jdbcType=DECIMAL},</if>
            <if test="deptId != null">#{deptId,jdbcType=INTEGER},</if>
            <if test="hireDate != null">#{hireDate,jdbcType=DATE},</if>
            <if test="createTime != null">#{createTime,jdbcType=TIMESTAMP},</if>
            <if test="updateTime != null">#{updateTime,jdbcType=TIMESTAMP},</if>
        </trim>
    </insert>
    <!-- 选择性更新 -->
     <update id="updateByPrimaryKeySelective" parameterType="com.example.entity.Emp">
         UPDATE emp
         <set>
             <if test="empName != null">emp_name = #{empName,jdbcType=VARCHAR},</if>
             <if test="gender != null">gender = #{gender,jdbcType=CHAR},</if>
             <if test="email != null">email = #{email,jdbcType=VARCHAR},</if>
             <if test="salary != null">salary = #{salary,jdbcType=DECIMAL},</if>
             <if test="deptId != null">dept_id = #{deptId,jdbcType=INTEGER},</if>
             <if test="hireDate != null">hire_date = #{hireDate,jdbcType=DATE},</if>
             <if test="createTime != null">create_time = #
      {createTime,jdbcType=TIMESTAMP},</if>
             <if test="updateTime != null">update_time = #
      {updateTime,jdbcType=TIMESTAMP},</if>
         </set>
         WHERE emp_id = #{empId,jdbcType=INTEGER}
     </update>
     <!-- 全量更新 -->
     <update id="updateByPrimaryKey" parameterType="com.example.entity.Emp">
         UPDATE emp
         SET emp_name    = #{empName,jdbcType=VARCHAR},
             gender      = #{gender,jdbcType=CHAR},
             email       = #{email,jdbcType=VARCHAR},
             salary      = #{salary,jdbcType=DECIMAL},
            dept_id     = #{deptId,jdbcType=INTEGER},
            hire_date   = #{hireDate,jdbcType=DATE},
            create_time = #{createTime,jdbcType=TIMESTAMP},
            update_time = #{updateTime,jdbcType=TIMESTAMP}
        WHERE emp_id = #{empId,jdbcType=INTEGER}
    </update>
</mapper>

javaClientGenerator — Mapper 接口生成

基本配置

<javaClientGenerator
    type="XMLMAPPER"
    targetPackage="com.example.mapper"
    targetProject="src/main/java">
    <property name="enableSubPackages" value="false"/>
</javaClientGenerator>

`type` 属性

值	说明	生成物
`XMLMAPPER`	接口与 XML 映射文件分离，适合大多数项目	Mapper 接口与对应 XML
`ANNOTATEDMAPPER`	SQL 主要通过注解写在接口中	Mapper 接口，无独立 XML
`MIXEDMAPPER`	基础语句使用注解，复杂语句保留 XML	Mapper 接口与部分 XML

生成的 Mapper 接口示例（XMLMAPPER 模式）

 package com.example.mapper;
 import com.example.entity.Emp;
 import com.example.entity.EmpExample;
 import java.util.List;
 import org.apache.ibatis.annotations.Param;
 public interface EmpMapper {
    // ====== 按 Example 查询 ======
    long countByExample(EmpExample example);
    int deleteByExample(EmpExample example);
    List<Emp> selectByExample(EmpExample example);
    int updateByExampleSelective(@Param("record") Emp record,
                                  @Param("example") EmpExample example);
    int updateByExample(@Param("record") Emp record,
                         @Param("example") EmpExample example);
    // ====== 按主键操作 ======
    int deleteByPrimaryKey(Integer empId);
    int insert(Emp record);
    int insertSelective(Emp record);
    Emp selectByPrimaryKey(Integer empId);
    int updateByPrimaryKeySelective(Emp record);
    int updateByPrimaryKey(Emp record);
}

ANNOTATEDMAPPER 模式生成的接口

// 纯注解，没有 XML 文件
public interface EmpMapper {
    @Insert({
        "INSERT INTO emp (emp_name, gender, ...)",
        "VALUES (#{empName,jdbcType=VARCHAR}, #{gender,jdbcType=CHAR}, ...)"
    })
     @Options(useGeneratedKeys = true, keyProperty = "empId")
     int insert(Emp record);
    @Select({
        "SELECT emp_id, emp_name, gender, ...",
        "FROM emp",
        "WHERE emp_id = #{empId,jdbcType=INTEGER}"
    })
    @ResultMap("BaseResultMap")
    Emp selectByPrimaryKey(Integer empId);
    // ... 其他方法
}

table 元素详解

table 完整属性

 <table
     schema="mybatis_demo"           <!-- 数据库名/schema -->
     tableName="emp"                  <!-- 数据库表名（支持通配符 %） -->
     domainObjectName="Emp"           <!-- 生成的实体类名 -->
     mapperName="EmpMapper"           <!-- 生成的 Mapper 接口名（可含包名） -->
     sqlMapName="EmpMapper"           <!-- 生成的 XML 文件名 -->
     alias="e"                        <!-- 表别名（用于多表查询） -->
     enableCountByExample="true"      <!-- 是否生成 countByExample -->
     enableDeleteByExample="true"     <!-- 是否生成 deleteByExample -->
    enableSelectByExample="true"     <!-- 是否生成 selectByExample -->
    enableUpdateByExample="true"     <!-- 是否生成 updateByExample -->
    enableDeleteByPrimaryKey="true"  <!-- 是否生成 deleteByPrimaryKey -->
    enableInsert="true"              <!-- 是否生成 insert -->
    enableSelectByPrimaryKey="true"  <!-- 是否生成 selectByPrimaryKey -->
    enableUpdateByPrimaryKey="true"  <!-- 是否生成 updateByPrimaryKey -->
    selectByPrimaryKeyQueryId="false"
    selectByExampleQueryId="false"
    modelType="conditional"          <!-- 覆盖 context 的 defaultModelType -->
    delimitIdentifiers="false"       <!-- 是否给所有标识符加分隔符 -->
    delimitAllColumns="false"        <!-- 是否给所有列加分隔符 -->
>

tableName 通配符用法

 <!-- 生成所有表（慎用） -->
 <table tableName="%"/>
 <!-- 生成所有以 t_ 开头的表 -->
 <table tableName="t_%" />
 <!-- 排除某些表（需配合 table 的 schema 属性） -->
 <table tableName="%" >
     <!-- 通过 domainObjectRenamingRule 来调整命名 -->
</table>

generatedKey — 主键回填

 <table tableName="emp" domainObjectName="Emp">
     <!-- 方式一：MySQL 自增主键 -->
     <generatedKey column="emp_id" sqlStatement="MySql" identity="true"/>
     <!-- 方式二：SQL Server 自增主键 -->
     <!-- <generatedKey column="id" sqlStatement="SQL Server" identity="true"/> -->
     <!-- 方式三：Oracle 序列 -->
     <!-- <generatedKey column="id" sqlStatement="select SEQ_EMP.nextval from dual"
     identity="false"/> -->
    <!-- 方式四：PostgreSQL -->
    <!-- <generatedKey column="id" sqlStatement="PostgreSQL" identity="true"/> -->
</table>

属性	说明
`column`	主键列名
`sqlStatement`	获取主键值的语句或数据库标识，例如 MySQL 常用 `MySql`
`identity`	`true` 表示数据库自增主键；`false` 表示由语句取得主键值
`type`	`pre` 表示插入前获取主键，`post` 表示插入后获取主键

columnOverride — 列覆盖

<table tableName="emp" domainObjectName="Emp">
    <!-- 强制指定某列的 Java 类型和 jdbcType -->
    <columnOverride column="salary"
                    property="salary"
                    javaType="java.math.BigDecimal"
                    jdbcType="DECIMAL"/>
    <!-- 强制指定枚举类型 -->
     <columnOverride column="gender"
                    property="gender"
                    javaType="com.example.enums.Gender"
                    typeHandler="com.example.handler.GenderTypeHandler"/>
    <!-- 修改属性名（驼峰自定义） -->
    <columnOverride column="emp_name" property="name"/>
    <!-- 强制 BLOB 类型 -->
    <columnOverride column="content" isBlob="true" javaType="java.lang.String"/>
</table>

ignoreColumn — 忽略列

<table tableName="emp" domainObjectName="Emp">
    <!-- 不生成这些字段 -->
    <ignoreColumn column="create_time"/>
    <ignoreColumn column="update_time"/>
    <!-- 支持正则匹配 -->
    <!-- <ignoreColumn pattern="^temp_.*"/> -->
</table>

domainObjectRenamingRule — 实体类重命名规则

<table tableName="t_emp" domainObjectName="Emp">
    <!-- 去掉表名前缀 t_ -->
    <domainObjectRenamingRule searchString="^T_" replaceString=""/>
</table>

columnRenamingRule — 列重命名规则

<table tableName="emp">
    <!-- 去掉列名前缀 F_ -->
    <columnRenamingRule searchString="^F_" replaceString=""/>
</table>

生成的代码结构说明

完整目录结构

mybatis-generator-demo/
├── src/main/java/com/example/
│   ├── entity/
│   │   ├── Emp.java              ← 员工实体类
│   │   ├── EmpExample.java       ← 员工查询条件类
│   │   ├── Dept.java             ← 部门实体类
│   │   └── DeptExample.java      ← 部门查询条件类
│   ├── mapper/
 │   │   ├── EmpMapper.java        ← 员工 Mapper 接口
│   │   └── DeptMapper.java       ← 部门 Mapper 接口
│   └── generator/
│       └── Generator.java        ← 生成器启动类
├── src/main/resources/
│   ├── generatorConfig.xml       ← MBG 配置文件
│   ├── generator.properties      ← 属性文件
│   ├── mapper/
│   │   ├── EmpMapper.xml         ← 员工 SQL 映射
│   │   └── DeptMapper.xml        ← 部门 SQL 映射
│   └── mybatis-config.xml        ← MyBatis 主配置
└── pom.xml

各方法功能对照表

方法功能对应 SQL

INSERT INTO emp (…) VALUES insert(Emp record)插入全部字段(…)

insertSelective(Emp record)

选择性插入（null 字 INSERT INTO emp (…) VALUES 段不插入）(…) +

DELETE FROM emp WHERE emp_id deleteByPrimaryKey(Integer id)按主键删除= ?

deleteByExample(EmpExample example)按条件删除 DELETE FROM emp WHERE …

UPDATE emp SET … WHERE updateByPrimaryKey(Emp record)全量更新 emp_id = ?

updateByPrimaryKeySelective(EmpUPDATE emp SET … WHERE 选择性更新 record)emp_id = ? +

updateByExample(…)按条件全量更新 UPDATE emp SET … WHERE …

 UPDATE emp SET ... WHERE ...
+ <if>

updateByExampleSelective(…)按条件选择性更新

SELECT … FROM emp WHERE selectByPrimaryKey(Integer id)按主键查询 emp_id = ?

 SELECT ... FROM emp WHERE
...

selectByExample(EmpExample example)按条件查询

SELECT COUNT(*) FROM emp countByExample(EmpExample example)按条件计数 WHERE …

Example 类详解（QBC 风格查询）

Example 类的作用

Example 类是 MBG 自动生成的查询条件构造器，采用 QBC（Query By Criteria） 风格，通过链式调用构建 WHERE 条件，避免手写 SQL。

Example 类结构

 public class EmpExample {
     protected String orderByClause;          // 排序字段
     protected boolean distinct;              // 是否去重
     protected List<Criteria> oredCriteria;   // OR 条件列表
     // 设置排序
     public void setOrderByClause(String orderByClause) { ... }
     // 设置去重
    public void setDistinct(boolean distinct) { ... }
    // 获取 OR 条件列表
    public List<Criteria> getOredCriteria() { ... }
    // 创建一个 OR 条件（相当于 OR (...)）
    public Criteria or() { ... }
    // 添加一个 Criteria 到 OR 列表
    public void or(Criteria criteria) { ... }
    // 创建一个 Criteria（相当于一个 AND 条件组）
    public Criteria createCriteria() { ... }
    // = createCriteria()，内部调用
    protected Criteria createCriteriaInternal() { ... }
    // 清空所有条件
    public void clear() { ... }
    // ====== Criteria 内部类 ======
    public abstract static class GeneratedCriteria {
        // 等于
        public Criteria andEmpIdEqualTo(Integer value) { ... }
        // 不等于
        public Criteria andEmpIdNotEqualTo(Integer value) { ... }
        // 大于
        public Criteria andEmpIdGreaterThan(Integer value) { ... }
        // 大于等于
        public Criteria andEmpIdGreaterThanOrEqualTo(Integer value) { ... }
        // 小于
        public Criteria andEmpIdLessThan(Integer value) { ... }
        // 小于等于
        public Criteria andEmpIdLessThanOrEqualTo(Integer value) { ... }
        // IN
        public Criteria andEmpIdIn(List<Integer> values) { ... }
        // NOT IN
        public Criteria andEmpIdNotIn(List<Integer> values) { ... }
        // BETWEEN
        public Criteria andEmpIdBetween(Integer value1, Integer value2) { ... }
        // NOT BETWEEN
        public Criteria andEmpIdNotBetween(Integer value1, Integer value2) { ... }
        // LIKE
        public Criteria andEmpNameLike(String value) { ... }
        // NOT LIKE
        public Criteria andEmpNameNotLike(String value) { ... }
        // IS NULL
        public Criteria andEmpNameIsNull() { ... }
        // IS NOT NULL
        public Criteria andEmpNameIsNotNull() { ... }
        // ... 每个字段都有以上方法
    }
    // ====== Criteria 继承类 ======
    public static class Criteria extends GeneratedCriteria {
        // ...
    }
}

Example 常用查询示例

 // ====== 1. 查询所有 ======
 List<Emp> allEmps = empMapper.selectByExample(new EmpExample());
 // ====== 2. 按主键查询 ======
 Emp emp = empMapper.selectByPrimaryKey(1);
 // ====== 3. 等值查询：gender = 'M' ======
 EmpExample example = new EmpExample();
 example.createCriteria().andGenderEqualTo("M");
List<Emp> males = empMapper.selectByExample(example);
// ====== 4. 多条件 AND 查询 ======
// WHERE gender = 'M' AND salary > 10000 AND dept_id = 1
EmpExample example = new EmpExample();
example.createCriteria()
        .andGenderEqualTo("M")
        .andSalaryGreaterThan(new BigDecimal("10000"))
        .andDeptIdEqualTo(1);
List<Emp> result = empMapper.selectByExample(example);
// ====== 5. OR 条件查询 ======
// WHERE (gender = 'M' AND salary > 15000) OR (gender = 'F' AND salary > 12000)
EmpExample example = new EmpExample();
example.createCriteria()
        .andGenderEqualTo("M")
        .andSalaryGreaterThan(new BigDecimal("15000"));
example.or()
        .andGenderEqualTo("F")
        .andSalaryGreaterThan(new BigDecimal("12000"));
List<Emp> result = empMapper.selectByExample(example);
// ====== 6. LIKE 查询 ======
// WHERE emp_name LIKE '%张%'
EmpExample example = new EmpExample();
example.createCriteria().andEmpNameLike("%张%");
List<Emp> result = empMapper.selectByExample(example);
// ====== 7. IN 查询 ======
// WHERE dept_id IN (1, 2, 3)
EmpExample example = new EmpExample();
example.createCriteria().andDeptIdIn(Arrays.asList(1, 2, 3));
List<Emp> result = empMapper.selectByExample(example);
// ====== 8. BETWEEN 查询 ======
// WHERE salary BETWEEN 8000 AND 20000
EmpExample example = new EmpExample();
example.createCriteria()
        .andSalaryBetween(new BigDecimal("8000"), new BigDecimal("20000"));
List<Emp> result = empMapper.selectByExample(example);
// ====== 9. IS NULL 查询 ======
// WHERE email IS NULL
EmpExample example = new EmpExample();
example.createCriteria().andEmailIsNull();
List<Emp> result = empMapper.selectByExample(example);
// ====== 10. 排序 ======
// ORDER BY salary DESC
EmpExample example = new EmpExample();
example.setOrderByClause("salary DESC");
List<Emp> result = empMapper.selectByExample(example);
// ====== 11. 去重 ======
EmpExample example = new EmpExample();
example.setDistinct(true);
example.setOrderByClause("dept_id");
List<Emp> result = empMapper.selectByExample(example);
// ====== 12. 条件删除 ======
// DELETE FROM emp WHERE dept_id = 3
EmpExample example = new EmpExample();
example.createCriteria().andDeptIdEqualTo(3);
empMapper.deleteByExample(example);
// ====== 13. 条件更新 ======
// UPDATE emp SET salary = 20000 WHERE dept_id = 1
EmpExample example = new EmpExample();
example.createCriteria().andDeptIdEqualTo(1);
Emp record = new Emp();
record.setSalary(new BigDecimal("20000"));
empMapper.updateByExampleSelective(record, example);
// ====== 14. 条件计数 ======
EmpExample example = new EmpExample();
example.createCriteria().andGenderEqualTo("M");
long count = empMapper.countByExample(example);

Example 使用对照表

需求	Example 方法	SQL 操作符
等于	`andXxxEqualTo(value)`	`=`
不等于	`andXxxNotEqualTo(value)`	`<>`
大于	`andXxxGreaterThan(value)`	`>`
大于等于	`andXxxGreaterThanOrEqualTo(value)`	`>=`
小于	`andXxxLessThan(value)`	`<`
小于等于	`andXxxLessThanOrEqualTo(value)`	`<=`
模糊匹配	`andXxxLike(value)`	`LIKE`
非模糊匹配	`andXxxNotLike(value)`	`NOT LIKE`
集合包含	`andXxxIn(list)`	`IN`
集合不包含	`andXxxNotIn(list)`	`NOT IN`
区间匹配	`andXxxBetween(v1, v2)`	`BETWEEN`
为空	`andXxxIsNull()`	`IS NULL`
非空	`andXxxIsNotNull()`	`IS NOT NULL`
添加 OR 条件组	`example.or().andXxx...()`	`OR`
排序	`example.setOrderByClause("xxx DESC")`	`ORDER BY`
去重	`example.setDistinct(true)`	`DISTINCT`

自定义 CommentGenerator（注释生成器）

默认注释的问题

MBG 默认生成的注释格式：

/**
 * This field was generated by MyBatis Generator.
 * This field corresponds to the database column emp.emp_name
 *
 * @mbg.generated
 */
private String empName;

问题：注释无用、没有数据库字段注释、没有日期格式。

自定义 CommentGenerator

 package com.example.generator;
 import org.mybatis.generator.api.IntrospectedColumn;
 import org.mybatis.generator.api.IntrospectedTable;
 import org.mybatis.generator.api.dom.java.*;
 import org.mybatis.generator.api.dom.xml.XmlElement;
 import org.mybatis.generator.internal.DefaultCommentGenerator;
 import java.util.Properties;
/**
 * 自定义注释生成器
 * 生成数据库字段注释到 Java 实体类中
 */
public class CustomCommentGenerator extends DefaultCommentGenerator {
    private boolean addRemarkComments;
    @Override
    public void addConfigurationProperties(Properties properties) {
        super.addConfigurationProperties(properties);
        this.addRemarkComments = Boolean.parseBoolean(
            properties.getProperty("addRemarkComments"));
    }
    /**
     * 给字段添加注释（数据库列注释）
     */
    @Override
    public void addFieldComment(Field field,
                                 IntrospectedTable introspectedTable,
                                 IntrospectedColumn introspectedColumn) {
        if (addRemarkComments) {
            String remark = introspectedColumn.getRemarks();
            if (remark != null && !remark.trim().isEmpty()) {
                field.addJavaDocLine("/**");
                field.addJavaDocLine(" * " + remark);
                field.addJavaDocLine(" */");
            }
        }
    }
    /**
     * 给类添加注释（表注释）
     */
    @Override
    public void addClassComment(InnerClass innerClass,
                                 IntrospectedTable introspectedTable) {
        String remark = introspectedTable.getRemarks();
        innerClass.addJavaDocLine("/**");
        if (remark != null && !remark.trim().isEmpty()) {
            innerClass.addJavaDocLine(" * " + remark);
        }
        innerClass.addJavaDocLine(" * 对应数据库表: " +
            introspectedTable.getFullyQualifiedTable());
        innerClass.addJavaDocLine(" */");
    }
    /**
     * 给 getter 方法添加注释
     */
    @Override
    public void addGetterComment(Method method,
                                  IntrospectedTable introspectedTable,
                                  IntrospectedColumn introspectedColumn) {
        // 不生成 getter 注释（保持简洁）
    }
    /**
     * 给 setter 方法添加注释
     */
    @Override
    public void addSetterComment(Method method,
                                  IntrospectedTable introspectedTable,
                                  IntrospectedColumn introspectedColumn) {
        // 不生成 setter 注释（保持简洁）
    }
}

在配置文件中使用自定义注释生成器

 <context id="mysqlContext" targetRuntime="MyBatis3">
     <!-- 使用自定义注释生成器 -->
     <commentGenerator type="com.example.generator.CustomCommentGenerator">
         <property name="suppressAllComments" value="false"/>
         <property name="suppressDate" value="true"/>
         <property name="addRemarkComments" value="true"/>
     </commentGenerator>
    <!-- ... 其他配置 ... -->
</context>

生成的实体类效果

 /**
  * 员工表
  * 对应数据库表: mybatis_demo.emp
  */
 public class Emp {
     /**
      * 员工ID
      */
    private Integer empId;
    /**
     * 员工姓名
     */
    private String empName;
    /**
     * 性别 M-男 F-女
     */
    private String gender;
    // ... getter/setter
}

自定义 Plugin 插件

Plugin 机制概述

MBG 通过 Plugin 插件机制 实现代码生成过程的扩展。插件可以拦截生成过程，修改或增加生成的代码。

 MBG 生成流程
     ↓
 ┌─────────────────────────────────┐
 │  阶段1: Model Class 生成         │ ← Plugin 可拦截
 ├─────────────────────────────────┤
 │  阶段2: SQL Map (XML) 生成       │ ← Plugin 可拦截
 ├─────────────────────────────────┤
 │  阶段3: Client (Mapper) 生成     │ ← Plugin 可拦截
 ├─────────────────────────────────┤
│  阶段4: Example Class 生成       │ ← Plugin 可拦截
└─────────────────────────────────┘

内置插件列表

插件类	功能
SerializablePlugin	让实体类实现 Serializable 接口
ToStringPlugin	生成 toString() 方法
EqualsAndHashCodePlugin	生成 equals() 和 hashCode() 方法
RowBoundsPlugin	生成分页方法（基于 RowBounds，不推荐 MySQL 使用）
VirtualKeyPlugin	虚拟主键插件
FluentBuilderMethodsPlugin	生成链式 setter（返回 this）
MapperNamePlugin	自定义 Mapper 名称
RenameExampleClassPlugin	重命名 Example 类
CaseInsensitiveLikePlugin	大小写不敏感 LIKE 查询
UnmergeableXmlMapperPlugin	XML 不合并，直接覆盖

自定义 Plugin 示例：Lombok 插件

让生成的实体类使用 Lombok 注解，替代冗长的 getter/setter：

 package com.example.generator;
 import org.mybatis.generator.api.IntrospectedTable;
 import org.mybatis.generator.api.PluginAdapter;
 import org.mybatis.generator.api.dom.java.*;
 import java.util.List;
 /**
 * 自定义 Lombok 插件
 * 让生成的实体类使用 @Data 注解，去掉 getter/setter
 */
public class LombokPlugin extends PluginAdapter {
    @Override
    public boolean validate(List<String> warnings) {
        return true;
    }
    /**
     * 给实体类添加 Lombok 注解
     */
    @Override
    public boolean modelBaseRecordClassGenerated(TopLevelClass topLevelClass,
                                                  IntrospectedTable introspectedTable)
     {
        // 添加 @Data 注解
        topLevelClass.addImportedType("lombok.Data");
        topLevelClass.addAnnotation("@Data");
        // 添加 @Builder 注解（可选）
        topLevelClass.addImportedType("lombok.Builder");
        topLevelClass.addAnnotation("@Builder");
        // 添加 @NoArgsConstructor
        topLevelClass.addImportedType("lombok.NoArgsConstructor");
        topLevelClass.addAnnotation("@NoArgsConstructor");
        // 添加 @AllArgsConstructor
        topLevelClass.addImportedType("lombok.AllArgsConstructor");
        topLevelClass.addAnnotation("@AllArgsConstructor");
        return true;
    }
    /**
     * 给主键类添加 Lombok 注解（如果有）
     */
    @Override
    public boolean modelPrimaryKeyClassGenerated(TopLevelClass topLevelClass,
                                                  IntrospectedTable introspectedTable)
     {
        topLevelClass.addImportedType("lombok.Data");
        topLevelClass.addAnnotation("@Data");
        return true;
    }
    /**
     * 禁止生成 getter 方法（由 Lombok @Data 提供）
     */
    @Override
    public boolean modelGetterMethodGenerated(Method method,
                                               TopLevelClass topLevelClass,
                                               IntrospectedColumn introspectedColumn,
                                               IntrospectedTable introspectedTable,
                                               ModelClassType modelClassType) {
        return false;  // false = 不生成 getter
    }
    /**
     * 禁止生成 setter 方法
     */
    @Override
    public boolean modelSetterMethodGenerated(Method method,
                                               TopLevelClass topLevelClass,
                                               IntrospectedColumn introspectedColumn,
                                               IntrospectedTable introspectedTable,
                                               ModelClassType modelClassType) {
        return false;  // false = 不生成 setter
    }
}

配置中使用自定义插件

 <context id="mysqlContext" targetRuntime="MyBatis3">
     <!-- 内置插件 -->
     <plugin type="org.mybatis.generator.plugins.SerializablePlugin"/>
     <plugin type="org.mybatis.generator.plugins.EqualsAndHashCodePlugin"/>
     <!-- ★ 自定义 Lombok 插件 -->
     <plugin type="com.example.generator.LombokPlugin"/>
    <!-- ★ 重命名 Example 类为 Query -->
    <plugin type="org.mybatis.generator.plugins.RenameExampleClassPlugin">
        <property name="searchString" value="Example$"/>
        <property name="replaceString" value="Query"/>
    </plugin>
    <!-- 自定义注释生成器 -->
    <commentGenerator type="com.example.generator.CustomCommentGenerator">
        <property name="suppressAllComments" value="false"/>
        <property name="addRemarkComments" value="true"/>
    </commentGenerator>
    <!-- ... 其他配置 ... -->
</context>

自定义 Plugin 示例：Mapper 继承通用接口

package com.example.generator;
import org.mybatis.generator.api.IntrospectedTable;
import org.mybatis.generator.api.PluginAdapter;
import org.mybatis.generator.api.dom.java.FullyQualifiedJavaType;
import org.mybatis.generator.api.dom.java.Interface;
 import org.mybatis.generator.api.dom.java.TopLevelClass;
 import java.util.List;
/**
 * 让所有生成的 Mapper 接口继承自定义的 BaseMapper
 */
public class BaseMapperPlugin extends PluginAdapter {
    private String baseMapperPackage;
    @Override
    public boolean validate(List<String> warnings) {
        baseMapperPackage = properties.getProperty("baseMapperPackage");
        return baseMapperPackage != null && !baseMapperPackage.trim().isEmpty();
    }
    @Override
    public boolean clientGenerated(Interface interfaze,
                                    TopLevelClass topLevelClass,
                                    IntrospectedTable introspectedTable) {
        // 导入 BaseMapper
        FullyQualifiedJavaType baseMapperType =
            new FullyQualifiedJavaType(baseMapperPackage);
        interfaze.addImportedType(baseMapperType);
        // 让 Mapper 继承 BaseMapper<实体类>
        FullyQualifiedJavaType entityType =
            new FullyQualifiedJavaType(introspectedTable.getBaseRecordType());
        interfaze.addSuperInterface(
            new FullyQualifiedJavaType(baseMapperPackage + "<" +
     entityType.getShortName() + ">"));
        return true;
    }
}
<plugin type="com.example.generator.BaseMapperPlugin">
    <property name="baseMapperPackage" value="com.example.mapper.BaseMapper"/>
</plugin>

MyBatis-Plus 代码生成器（3.5.x+）

MP Generator 概述

MyBatis-Plus 代码生成器比 MBG 功能更强大，能生成：

Entity 实体类（支持 Lombok / Swagger 注解）
Mapper 接口（继承 BaseMapper）
Mapper XML 映射文件
Service 接口 + Service 实现类
Controller 控制器（含 RESTful 接口）

依赖配置

 <dependencies>
     <!-- MyBatis-Plus（包含 MyBatis） -->
     <dependency>
         <groupId>com.baomidou</groupId>
         <artifactId>mybatis-plus-boot-starter</artifactId>
         <version>3.5.7</version>
     </dependency>
     <!-- MP 代码生成器核心 -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-generator</artifactId>
        <version>3.5.7</version>
    </dependency>
    <!-- 模板引擎（Freemarker / Velocity / Beetl 任选其一） -->
    <dependency>
        <groupId>org.freemarker</groupId>
        <artifactId>freemarker</artifactId>
        <version>2.3.32</version>
    </dependency>
    <!-- MySQL 驱动 -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <version>8.0.33</version>
    </dependency>
    <!-- Lombok（可选） -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.34</version>
        <scope>provided</scope>
    </dependency>
    <!-- Swagger / SpringDoc（可选） -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.5.0</version>
    </dependency>
</dependencies>

快速生成器（FastAutoGenerator）

MyBatis-Plus 3.5.3+ 提供了 FastAutoGenerator，链式配置一行搞定：

 package com.example.generator;
 import com.baomidou.mybatisplus.generator.FastAutoGenerator;
 import com.baomidou.mybatisplus.generator.config.OutputFile;
 import com.baomidou.mybatisplus.generator.config.rules.NamingStrategy;
 import com.baomidou.mybatisplus.generator.engine.FreemarkerTemplateEngine;
 import java.util.Collections;
public class MpGenerator {
    public static void main(String[] args) {
        FastAutoGenerator.create(
                "jdbc:mysql://localhost:3306/mybatis_demo?
     useSSL=false&serverTimezone=Asia/Shanghai",
                "root",
                "123456")
            // ====== 全局配置 ======
            .globalConfig(builder -> {
                builder.author("example")               // 作者
                       .outputDir("src/main/java")      // 输出目录
                       .enableSwagger()                  // 开启 Swagger 注解
                       .commentDate("yyyy-MM-dd");       // 注释日期格式
            })
            // ====== 包配置 ======
            .packageConfig(builder -> {
                builder.parent("com.example")           // 父包名
                       .entity("entity")                // 实体类包名
                       .mapper("mapper")                // Mapper 包名
                       .service("service")              // Service 包名
                       .serviceImpl("service.impl")     // Service 实现包名
                       .controller("controller")        // Controller 包名
                       .xml("mapper")                   // XML 资源路径
                       .pathInfo(Collections.singletonMap(
                           OutputFile.xml,
                           "src/main/resources/mapper")); // XML 输出目录
            })
            // ====== 策略配置 ======
            .strategyConfig(builder -> {
                builder.addInclude("emp", "dept")       // 表名（可变参数）
                       .addTablePrefix("t_", "sys_")    // 过滤表前缀
                       .entityBuilder()
                       .naming(NamingStrategy.underline_to_camel)  // 下划线转驼峰
                       .columnNaming(NamingStrategy.underline_to_camel)
                       .enableLombok()                   // 使用 Lombok
                       .enableTableFieldAnnotation()     // 生成字段注解
                       .logicDeleteColumnName("deleted") // 逻辑删除字段
                       .versionColumnName("version")     // 乐观锁字段
                       .idType(IdType.AUTO)              // 主键策略
                       .formatFileName("%s")             // 实体类名格式
                       .mapperBuilder()
                       .enableMapperAnnotation()          // 生成 @Mapper 注解
                       .formatMapperFileName("%sMapper")   // Mapper 文件名格式
                       .formatXmlFileName("%sMapper")      // XML 文件名格式
                       .serviceBuilder()
                       .formatServiceFileName("%sService")     // Service 接口名
                       .formatServiceImplFileName("%sServiceImpl") // Service 实现名
                       .controllerBuilder()
                       .enableRestStyle();                // 生成 @RestController
            })
            // ====== 模板引擎 ======
            .templateEngine(new FreemarkerTemplateEngine())
            // ====== 执行 ======
            .execute();
        System.out.println("✅ MyBatis-Plus 代码生成完成！");
    }
}

生成的目录结构

 src/main/java/com/example/
 ├── entity/
 │   ├── Emp.java              ← @Data + @TableName + 字段注解
 │   └── Dept.java
 ├── mapper/
 │   ├── EmpMapper.java        ← extends BaseMapper<Emp>
 │   └── DeptMapper.java
 ├── service/
 │   ├── EmpService.java       ← extends IService<Emp>
│   └── impl/
│       └── EmpServiceImpl.java  ← extends ServiceImpl<EmpMapper, Emp>
└── controller/
    ├── EmpController.java    ← @RestController
    └── DeptController.java
src/main/resources/
└── mapper/
    ├── EmpMapper.xml
    └── DeptMapper.xml

MyBatis-Plus Generator 配置详解

完整 AutoGenerator 配置（非 Fast 模式）

package com.example.generator;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.generator.AutoGenerator;
 import com.baomidou.mybatisplus.generator.config.*;
 import com.baomidou.mybatisplus.generator.config.rules.NamingStrategy;
 import com.baomidou.mybatisplus.generator.engine.FreemarkerTemplateEngine;
 public class MpFullGenerator {
    public static void main(String[] args) {
        // ====== 1. 数据源配置 ======
        DataSourceConfig dataSourceConfig = DataSourceConfig.builder(
                "jdbc:mysql://localhost:3306/mybatis_demo?
     useSSL=false&serverTimezone=Asia/Shanghai",
                "com.mysql.cj.jdbc.Driver",
                "root",
                "123456")
            .build();
        // ====== 2. 全局配置 ======
        GlobalConfig globalConfig = GlobalConfig.builder()
                .author("example")
                .outputDir("src/main/java")
                .enableSwagger()                    // Swagger 注解
                .disableOpenDir()                    // 生成后不自动打开目录
                .commentDate("yyyy-MM-dd")
                .dateType(DateType.TIME_PACK)        // 使用 java.time 包
                .build();
        // ====== 3. 包配置 ======
        PackageConfig packageConfig = PackageConfig.builder()
                .parent("com.example")
                .moduleName("system")               // 模块名（会加到包路径中）
                .entity("entity")
                .mapper("mapper")
                .service("service")
                .serviceImpl("service.impl")
                .controller("controller")
                .xml("mapper.xml")
                .pathInfo(java.util.Collections.singletonMap(
                    OutputFile.xml,
                    "src/main/resources/mapper"))
                .build();
        // ====== 4. 模板配置 ======
        TemplateConfig templateConfig = TemplateConfig.builder()
                .entity("templates/entity.java")    // 使用自定义模板
                .mapper("templates/mapper.java")
                .xml("templates/mapper.xml")
                .service("templates/service.java")
                .serviceImpl("templates/serviceImpl.java")
                .controller("templates/controller.java")
                .build();
        // ====== 5. 策略配置 ======
         StrategyConfig strategyConfig = StrategyConfig.builder()
                 .addInclude("emp", "dept")          // 要生成的表
                 .addTablePrefix("t_", "sys_")       // 过滤表前缀
                 .addTableSuffix("_tab")             // 过滤表后缀
                 // 实体策略
                 .entityBuilder()
                 .naming(NamingStrategy.underline_to_camel)
                 .columnNaming(NamingStrategy.underline_to_camel)
                 .enableLombok()                     // Lombok 注解
                 .enableTableFieldAnnotation()       // @TableField 注解
                 .enableActiveRecord()               // ActiveRecord 模式
                 .enableFileOverride()               // 覆盖已有文件
                 .logicDeleteColumnName("deleted")   // 逻辑删除
                 .versionColumnName("version")       // 乐观锁
                 .idType(IdType.AUTO)                // 主键策略
                 .formatFileName("%s")               // 实体类名格式
                 .superClass("com.example.BaseEntity")  // 父类
                 // Mapper 策略
                 .mapperBuilder()
                 .enableMapperAnnotation()           // @Mapper 注解
                 .enableBaseResultMap()              // 生成 BaseResultMap
                 .enableBaseColumnList()             // 生成 BaseColumnList
                 .formatMapperFileName("%sMapper")
                 .formatXmlFileName("%sMapper")
                 // Service 策略
                 .serviceBuilder()
                 .formatServiceFileName("%sService")
                 .formatServiceImplFileName("%sServiceImpl")
                 .superServiceClass("com.example.BaseService")
                 .superServiceImplClass("com.example.BaseServiceImpl")
                 // Controller 策略
                 .controllerBuilder()
                 .enableRestStyle()                  // @RestController
                 .enableHyphenStyle()                // URL 连字符风格
                 .formatFileName("%sController")
                 .build();
         // ====== 6. 注入配置（自定义变量） ======
         InjectionConfig injectionConfig = InjectionConfig.builder()
                 .customMap(java.util.Map.of(
                     "author", "example",
                     "version", "1.0.0"))
                 .build();
        // ====== 7. 组装执行 ======
        AutoGenerator generator = new AutoGenerator(dataSourceConfig);
        generator.global(globalConfig);
        generator.packageInfo(packageConfig);
        generator.template(templateConfig);
        generator.strategy(strategyConfig);
        generator.injection(injectionConfig);
        generator.templateEngine(new FreemarkerTemplateEngine());
        generator.execute();
        System.out.println("✅ 代码生成完成！");
    }
}

IdType 主键策略

`IdType` 值	说明	常见场景
`AUTO`	使用数据库自增主键	MySQL `AUTO_INCREMENT` 等
`NONE`	不指定局部策略，按全局配置处理	由项目统一配置
`INPUT`	插入前由开发者手动赋值	业务主键
`ASSIGN_ID`	使用默认标识符生成器分配长整型 ID	分布式系统常用
`ASSIGN_UUID`	分配不带连字符的 UUID 字符串	字符串主键

NamingStrategy 命名策略

值	说明	示例
`underline_to_camel`	下划线命名转驼峰命名	`emp_name` 转为 `empName`
`no_change`	保持数据库名称不变	`emp_name` 保持为 `emp_name`

数据源类型映射配置

 // MySQL 8.x 类型映射自定义
 DataSourceConfig dataSourceConfig = DataSourceConfig.builder(
         url, driver, username, password)
     .typeConvert(new ITypeConvert() {
         @Override
         public IColumnType executeTypeConvert(TableInfo tableInfo, String fieldName,
     String fieldType) {
             // 自定义类型映射
             if ("tinyint(1)".equalsIgnoreCase(fieldType)) {
                 return DbColumnType.BOOLEAN;
            }
            if ("json".equalsIgnoreCase(fieldType)) {
                return DbColumnType.OBJECT;
            }
            // 默认使用 MP 内置映射
            return TypeConverts.useDefault(tableInfo, fieldName, fieldType);
        }
    })
    .build();

模板自定义

自定义实体类模板

MP 使用 Freemarker 模板引擎，默认模板位于 mybatis-plus-generator jar 包中的 templates/ 目录。

自定义 entity.java.ftl 模板：

 package ${package.Entity};
 <#list table.importPackages as pkg>
 import ${pkg};
 </#list>
 <#if swagger2>
 import io.swagger.v3.oas.annotations.media.Schema;
 </#if>
 <#if entityLombokAnnotations>
import lombok.Data;
import lombok.experimental.Accessors;
</#if>
/**
 * <p>
 * ${table.comment!}
 * </p>
 *
 * @author ${author}
 * @since ${date}
 */
<#if entityLombokAnnotations>
@Data
@Accessors(chain = true)
</#if>
<#if swagger2>
@Schema(description = "${table.comment!}")
</#if>
@TableName("${schemaName}${table.name}")
public class ${entity} implements Serializable {
    private static final long serialVersionUID = 1L;
<#-- ----------  BEGIN 字段循环遍历  ---------->
<#list table.fields as field>
    <#if field.keyFlag>
        <#if field.keyIdentityFlag>
    @TableId(value = "${field.annotationColumnName}", type = IdType.AUTO)
        <#elseif idType??>
    @TableId(value = "${field.annotationColumnName}", type = IdType.${idType})
        <#else>
    @TableId(value = "${field.annotationColumnName}", type = IdType.ASSIGN_ID)
        </#if>
    <#elseif field.fill??>
    <#-- 通用填充字段 -->
    @TableField(value = "${field.annotationColumnName}", fill =
     FieldFill.${field.fill})
    <#elseif !field.propertyType?ends_with("Serializable")>
    @TableField("${field.annotationColumnName}")
    </#if>
    <#if swagger2>
    @Schema(description = "${field.comment!}")
    </#if>
    private ${field.propertyType} ${field.propertyName};
</#list>
<#------------  END 字段循环遍历  ---------->
<#if !entityLombokAnnotations>
    <#list table.fields as field>
        <#if field.propertyType == "boolean">
            <#assign getprefix="is"/>
        <#else>
            <#assign getprefix="get"/>
        </#if>
    public ${field.propertyType} ${getprefix}${field.capitalPropertyName}() {
        return ${field.propertyName};
    }
    public void set${field.capitalPropertyName}(${field.propertyType}
     ${field.propertyName}) {
        this.${field.propertyName} = ${field.propertyName};
    }
    </#list>
</#if>
}

使用自定义模板

TemplateConfig templateConfig = TemplateConfig.builder()
    .entity("/templates/my-entity.java")    // 自定义模板路径
    .mapper("/templates/my-mapper.java")
    .xml("/templates/my-mapper.xml")
    .service("/templates/my-service.java")
    .serviceImpl("/templates/my-serviceImpl.java")
    .controller("/templates/my-controller.java")
    .build();

将自定义模板放在 src/main/resources/templates/ 目录下。

自定义 Controller 模板（RESTful 风格）

 package ${package.Controller};
 import ${package.Entity}.${entity};
 import ${package.Service}.${entity}Service;
 <#if swagger2>
 import io.swagger.v3.oas.annotations.tags.Tag;
 import io.swagger.v3.oas.annotations.Operation;
 </#if>
 import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;
/**
 * <p>
 * ${table.comment!} 前端控制器
 * </p>
 *
 * @author ${author}
 * @since ${date}
 */
<#if swagger2>
@Tag(name = "${table.comment!}")
</#if>
@RestController
@RequestMapping("/${table.entityPath}")
public class ${entity}Controller {
    @Autowired
    private ${entity}Service ${table.entityPath}Service;
    @Operation(summary = "查询所有")
    @GetMapping
    public List<${entity}> list() {
        return ${table.entityPath}Service.list();
    }
    @Operation(summary = "根据ID查询")
    @GetMapping("/{id}")
    public ${entity} getById(@PathVariable ${entity} ${table.entityPath}) {
        return ${table.entityPath}Service.getById(${table.entityPath});
    }
    @Operation(summary = "新增")
    @PostMapping
    public boolean save(@RequestBody ${entity} ${table.entityPath}) {
        return ${table.entityPath}Service.save(${table.entityPath});
    }
    @Operation(summary = "修改")
    @PutMapping
    public boolean update(@RequestBody ${entity} ${table.entityPath}) {
        return ${table.entityPath}Service.updateById(${table.entityPath});
    }
    @Operation(summary = "根据ID删除")
    @DeleteMapping("/{id}")
    public boolean delete(@PathVariable ${entity} ${table.entityPath}) {
        return ${table.entityPath}Service.removeById(${table.entityPath});
    }
}

Spring Boot 集成逆向工程

Spring Boot 项目中集成 MBG

pom.xml 配置：

 <dependencies>
     <!-- Spring Boot Starter -->
     <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-web</artifactId>
     </dependency>
     <!-- MyBatis Spring Boot Starter -->
     <dependency>
        <groupId>org.mybatis.spring.boot</groupId>
        <artifactId>mybatis-spring-boot-starter</artifactId>
        <version>3.0.3</version>
    </dependency>
    <!-- MySQL -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>
</dependencies>
<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
        <!-- MBG 插件 -->
        <plugin>
            <groupId>org.mybatis.generator</groupId>
            <artifactId>mybatis-generator-maven-plugin</artifactId>
            <version>1.4.2</version>
            <executions>
                <!-- 可选：绑定到 generate-sources 阶段自动执行 -->
                <execution>
                    <id>Generate MyBatis Artifacts</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <!-- 取消注释则每次构建自动生成 -->
                    <!-- <phase>generate-sources</phase> -->
                </execution>
            </executions>
            <configuration>
                <configurationFile>
                    src/main/resources/generator/generatorConfig.xml
                </configurationFile>
                <overwrite>true</overwrite>
                <verbose>true</verbose>
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>com.mysql</groupId>
                    <artifactId>mysql-connector-j</artifactId>
                    <version>8.0.33</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

Spring Boot + MyBatis-Plus 集成

pom.xml:

 <dependencies>
     <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-web</artifactId>
     </dependency>
     <dependency>
         <groupId>com.baomidou</groupId>
         <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
        <version>3.5.7</version>
    </dependency>
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-generator</artifactId>
        <version>3.5.7</version>
    </dependency>
    <dependency>
        <groupId>org.freemarker</groupId>
        <artifactId>freemarker</artifactId>
    </dependency>
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

application.yml:

 spring:
   datasource:
     url: jdbc:mysql://localhost:3306/mybatis_demo?
     useSSL=false&serverTimezone=Asia/Shanghai
     username: root
     password: 123456
     driver-class-name: com.mysql.cj.jdbc.Driver
 mybatis-plus:
   mapper-locations: classpath:mapper/*.xml
  type-aliases-package: com.example.entity
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
  global-config:
    db-config:
      id-type: auto
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0

生成的实体类使用示例

 // ====== Emp.java（MP 生成的实体类）======
 @Schema(description = "员工表")
 @TableName("emp")
 @Data
 @Accessors(chain = true)
 public class Emp implements Serializable {
     private static final long serialVersionUID = 1L;
    @Schema(description = "员工ID")
    @TableId(value = "emp_id", type = IdType.AUTO)
    private Integer empId;
    @Schema(description = "员工姓名")
    @TableField("emp_name")
    private String empName;
    @Schema(description = "性别 M-男 F-女")
    private String gender;
    @Schema(description = "邮箱")
    private String email;
    @Schema(description = "工资")
    private BigDecimal salary;
    @Schema(description = "所属部门ID")
    @TableField("dept_id")
    private Integer deptId;
    @Schema(description = "入职日期")
    private LocalDate hireDate;
    @Schema(description = "创建时间")
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;
    @Schema(description = "更新时间")
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;
}
// ====== EmpMapper.java ======
@Mapper
public interface EmpMapper extends BaseMapper<Emp> {
    // BaseMapper 已提供 insert/delete/update/select 等方法
    // 可以在这里添加自定义 SQL
}
// ====== EmpService.java ======
public interface EmpService extends IService<Emp> {
    // IService 已提供通用业务方法
    // 可以在这里添加自定义业务方法
}
// ====== EmpServiceImpl.java ======
@Service
public class EmpServiceImpl extends ServiceImpl<EmpMapper, Emp> implements EmpService {
    // ServiceImpl 已实现 IService 的所有方法
}
 // ====== EmpController.java ======
 @Tag(name = "员工管理")
 @RestController
 @RequestMapping("/emp")
 public class EmpController {
     @Autowired
     private EmpService empService;
    @Operation(summary = "分页查询")
    @GetMapping("/page")
    public Page<Emp> page(
            @RequestParam(defaultValue = "1") Integer current,
            @RequestParam(defaultValue = "10") Integer size) {
        return empService.page(new Page<>(current, size));
    }
    @Operation(summary = "新增员工")
    @PostMapping
    public boolean save(@RequestBody Emp emp) {
        return empService.save(emp);
    }
    @Operation(summary = "根据ID查询")
    @GetMapping("/{id}")
    public Emp getById(@PathVariable Integer id) {
        return empService.getById(id);
    }
    @Operation(summary = "更新员工")
    @PutMapping
    public boolean update(@RequestBody Emp emp) {
        return empService.updateById(emp);
    }
    @Operation(summary = "删除员工")
    @DeleteMapping("/{id}")
    public boolean delete(@PathVariable Integer id) {
        return empService.removeById(id);
    }
}

多模块项目中的逆向工程

多模块项目结构

my-project/
├── pom.xml                          ← 父 POM
├── my-project-common/               ← 通用模块
│   └── pom.xml
├── my-project-entity/               ← 实体模块
 │   ├── pom.xml
 │   └── src/main/java/com/example/entity/
 ├── my-project-mapper/               ← Mapper 模块
 │   ├── pom.xml
│   └── src/main/java/com/example/mapper/
├── my-project-service/              ← Service 模块
│   ├── pom.xml
│   └── src/main/java/com/example/service/
├── my-project-web/                  ← Web 模块（启动模块）
│   ├── pom.xml
│   └── src/main/resources/
│       ├── generatorConfig.xml
│       └── application.yml
└── my-project-generator/            ← 代码生成器模块（独立）
    ├── pom.xml
    └── src/main/java/com/example/Generator.java

多模块 MBG 配置

 <!-- generatorConfig.xml 放在 my-project-generator 模块中 -->
 <generatorConfiguration>
     <context id="multiModule" targetRuntime="MyBatis3">
         <plugin type="org.mybatis.generator.plugins.SerializablePlugin"/>
         <plugin type="org.mybatis.generator.plugins.ToStringPlugin"/>
         <commentGenerator>
             <property name="suppressAllComments" value="false"/>
        </commentGenerator>
        <jdbcConnection driverClass="${jdbc.driver}"
                        connectionURL="${jdbc.url}"
                        userId="${jdbc.username}"
                        password="${jdbc.password}">
            <property name="useInformationSchema" value="true"/>
        </jdbcConnection>
        <javaTypeResolver>
            <property name="useJSR310Types" value="true"/>
        </javaTypeResolver>
        <!-- 实体类输出到 entity 模块 -->
        <javaModelGenerator
            targetPackage="com.example.entity"
            targetProject="../my-project-entity/src/main/java">
            <property name="trimStrings" value="true"/>
        </javaModelGenerator>
        <!-- XML 输出到 web 模块的 resources -->
        <sqlMapGenerator
            targetPackage="mapper"
            targetProject="../my-project-web/src/main/resources">
        </sqlMapGenerator>
        <!-- Mapper 接口输出到 mapper 模块 -->
        <javaClientGenerator
            type="XMLMAPPER"
            targetPackage="com.example.mapper"
            targetProject="../my-project-mapper/src/main/java">
        </javaClientGenerator>
        <table tableName="emp" domainObjectName="Emp">
            <generatedKey column="emp_id" sqlStatement="MySql" identity="true"/>
        </table>
    </context>
</generatorConfiguration>

关键： targetProject 使用相对路径 ../模块名/src/main/java 指向其他模块的源码目录。

多模块 MP Generator 配置

 FastAutoGenerator.create(url, username, password)
     .globalConfig(builder -> builder
         .author("example")
         .outputDir(System.getProperty("user.dir") + "/my-project-generator/src/main/java")
     )
     .packageConfig(builder -> builder
         .parent("com.example")
         // 实体类输出到 entity 模块
         .entity("entity")
        // Mapper 输出到 mapper 模块
        .mapper("mapper")
        .pathInfo(java.util.Map.of(
            OutputFile.entity, "../my-project-entity/src/main/java",
            OutputFile.mapper, "../my-project-mapper/src/main/java",
            OutputFile.service, "../my-project-service/src/main/java",
            OutputFile.serviceImpl, "../my-project-service/src/main/java",
            OutputFile.controller, "../my-project-web/src/main/java",
            OutputFile.xml, "../my-project-web/src/main/resources/mapper"
        ))
    )
    .strategyConfig(builder -> builder
        .addInclude("emp", "dept")
        .entityBuilder().enableLombok()
    )
    .execute();

实战案例一：MBG 完整项目

项目搭建

# 1. 创建 Maven 项目
mvn archetype:generate -DgroupId=com.example -DartifactId=mbg-demo -DarchetypeArtifactId=maven-archetype-quickstart
# 2. 进入项目目录
cd mbg-demo
# 3. 添加依赖（参考 III 章节 pom.xml）

完整配置文件

generatorConfig.xml:

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE generatorConfiguration
         PUBLIC "-//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN"
         "http://mybatis.org/dtd/mybatis-generator-config_1_0.dtd">
 <generatorConfiguration>
     <properties resource="generator.properties"/>
     <context id="mysqlContext" targetRuntime="MyBatis3"
             defaultModelType="conditional">
        <!-- 插件 -->
        <plugin type="org.mybatis.generator.plugins.SerializablePlugin"/>
        <plugin type="org.mybatis.generator.plugins.ToStringPlugin"/>
        <plugin type="org.mybatis.generator.plugins.EqualsAndHashCodePlugin"/>
        <!-- 重命名 Example 为 Query -->
        <plugin type="org.mybatis.generator.plugins.RenameExampleClassPlugin">
            <property name="searchString" value="Example$"/>
            <property name="replaceString" value="Query"/>
        </plugin>
        <!-- 注释生成器 -->
        <commentGenerator>
            <property name="suppressAllComments" value="false"/>
            <property name="suppressDate" value="true"/>
            <property name="addRemarkComments" value="true"/>
        </commentGenerator>
        <!-- 数据库连接 -->
        <jdbcConnection driverClass="${jdbc.driver}"
                        connectionURL="${jdbc.url}"
                        userId="${jdbc.username}"
                        password="${jdbc.password}">
            <property name="useInformationSchema" value="true"/>
        </jdbcConnection>
        <!-- 类型解析 -->
        <javaTypeResolver>
            <property name="forceBigDecimals" value="false"/>
            <property name="useJSR310Types" value="true"/>
        </javaTypeResolver>
        <!-- 实体类 -->
        <javaModelGenerator
            targetPackage="com.example.entity"
            targetProject="src/main/java">
            <property name="trimStrings" value="true"/>
        </javaModelGenerator>
        <!-- XML -->
        <sqlMapGenerator
            targetPackage="mapper"
            targetProject="src/main/resources">
        </sqlMapGenerator>
        <!-- Mapper -->
        <javaClientGenerator
            type="XMLMAPPER"
            targetPackage="com.example.mapper"
            targetProject="src/main/java">
        </javaClientGenerator>
        <!-- 表配置 -->
        <table tableName="emp" domainObjectName="Emp"
               enableCountByExample="true"
               enableDeleteByExample="true"
               enableSelectByExample="true"
               enableUpdateByExample="true">
            <generatedKey column="emp_id" sqlStatement="MySql" identity="true"/>
        </table>
        <table tableName="dept" domainObjectName="Dept">
            <generatedKey column="dept_id" sqlStatement="MySql" identity="true"/>
        </table>
    </context>
</generatorConfiguration>

执行生成

# 方式一：Maven 命令
mvn mybatis-generator:generate
# 方式二：运行 Java 类
# 直接运行 Generator.java 的 main 方法

编写测试

 package com.example.test;
 import com.example.entity.Emp;
 import com.example.entity.EmpQuery;
 import com.example.mapper.EmpMapper;
 import org.apache.ibatis.io.Resources;
 import org.apache.ibatis.session.SqlSession;
 import org.apache.ibatis.session.SqlSessionFactory;
 import org.apache.ibatis.session.SqlSessionFactoryBuilder;
import org.junit.After;
import org.junit.Before;
import org.junit.Test;
import java.io.InputStream;
import java.math.BigDecimal;
import java.util.List;
public class EmpMapperTest {
    private SqlSession session;
    private EmpMapper empMapper;
    @Before
    public void setUp() throws Exception {
        InputStream is = Resources.getResourceAsStream("mybatis-config.xml");
        SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(is);
        session = factory.openSession();
        empMapper = session.getMapper(EmpMapper.class);
    }
    @After
    public void tearDown() {
        if (session != null) {
            session.close();
        }
    }
    // 测试1：插入
    @Test
    public void testInsert() {
        Emp emp = new Emp();
        emp.setEmpName("赵六");
        emp.setGender("M");
        emp.setEmail("zhaoliu@qq.com");
        emp.setSalary(new BigDecimal("13000"));
        emp.setDeptId(1);
        int rows = empMapper.insert(emp);
        System.out.println("插入行数: " + rows);
        System.out.println("主键回填: " + emp.getEmpId());
         session.commit();
     }
     // 测试2：按主键查询
     @Test
     public void testSelectByPrimaryKey() {
         Emp emp = empMapper.selectByPrimaryKey(1);
         System.out.println(emp);
     }
     // 测试3：条件查询
     @Test
     public void testSelectByExample() {
         EmpQuery query = new EmpQuery();
         query.createCriteria()
                 .andGenderEqualTo("M")
                 .andSalaryGreaterThan(new BigDecimal("10000"));
         query.setOrderByClause("salary DESC");
         List<Emp> list = empMapper.selectByExample(query);
         list.forEach(System.out::println);
     }
     // 测试4：选择性更新
     @Test
     public void testUpdateByPrimaryKeySelective() {
         Emp emp = new Emp();
         emp.setEmpId(1);
         emp.setSalary(new BigDecimal("20000"));
         int rows = empMapper.updateByPrimaryKeySelective(emp);
         System.out.println("更新行数: " + rows);
         session.commit();
     }
     // 测试5：条件删除
     @Test
     public void testDeleteByExample() {
         EmpQuery query = new EmpQuery();
         query.createCriteria().andDeptIdIsNull();
         int rows = empMapper.deleteByExample(query);
         System.out.println("删除行数: " + rows);
         session.commit();
     }
     // 测试6：条件计数
     @Test
     public void testCountByExample() {
        EmpQuery query = new EmpQuery();
        query.createCriteria().andGenderEqualTo("M");
        long count = empMapper.countByExample(query);
        System.out.println("男性员工数量: " + count);
    }
}

实战案例二：MyBatis-Plus Generator 完整项目

项目搭建

 <!-- pom.xml 关键依赖 -->
 <dependencies>
     <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-web</artifactId>
     </dependency>
     <dependency>
         <groupId>com.baomidou</groupId>
         <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
        <version>3.5.7</version>
    </dependency>
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-generator</artifactId>
        <version>3.5.7</version>
    </dependency>
    <dependency>
        <groupId>org.freemarker</groupId>
        <artifactId>freemarker</artifactId>
    </dependency>
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.5.0</version>
    </dependency>
</dependencies>

生成器代码

 package com.example.generator;
 import com.baomidou.mybatisplus.annotation.IdType;
 import com.baomidou.mybatisplus.generator.FastAutoGenerator;
 import com.baomidou.mybatisplus.generator.config.OutputFile;
 import com.baomidou.mybatisplus.generator.config.rules.NamingStrategy;
 import com.baomidou.mybatisplus.generator.engine.FreemarkerTemplateEngine;
 import java.util.HashMap;
import java.util.Map;
public class CodeGenerator {
    public static void main(String[] args) {
        // 数据库配置
        String url = "jdbc:mysql://localhost:3306/mybatis_demo" +
                     "?
     useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8";
        String username = "root";
        String password = "123456";
        // 输出目录
        String projectPath = System.getProperty("user.dir");
        FastAutoGenerator.create(url, username, password)
            .globalConfig(builder -> builder
                .author("example")
                .outputDir(projectPath + "/src/main/java")
                .enableSwagger()
                .commentDate("yyyy-MM-dd")
                .disableOpenDir()
            )
            .packageConfig(builder -> {
                Map<OutputFile, String> pathInfo = new HashMap<>();
                pathInfo.put(OutputFile.xml, projectPath +
     "/src/main/resources/mapper");
                builder
                    .parent("com.example")
                    .entity("entity")
                    .mapper("mapper")
                    .service("service")
                    .serviceImpl("service.impl")
                    .controller("controller")
                    .pathInfo(pathInfo);
            })
            .strategyConfig(builder -> builder
                .addInclude("emp", "dept")       // 要生成的表
                .addTablePrefix("t_", "sys_")    // 去掉表前缀
                .entityBuilder()
                    .naming(NamingStrategy.underline_to_camel)
                    .columnNaming(NamingStrategy.underline_to_camel)
                    .enableLombok()
                    .enableTableFieldAnnotation()
                    .idType(IdType.AUTO)
                    .logicDeleteColumnName("deleted")
                    .versionColumnName("version")
                    .formatFileName("%s")
                .mapperBuilder()
                    .enableMapperAnnotation()
                    .enableBaseResultMap()
                    .enableBaseColumnList()
                    .formatMapperFileName("%sMapper")
                    .formatXmlFileName("%sMapper")
                .serviceBuilder()
                    .formatServiceFileName("%sService")
                    .formatServiceImplFileName("%sServiceImpl")
                .controllerBuilder()
                    .enableRestStyle()
                    .enableHyphenStyle()
                    .formatFileName("%sController")
            )
            .templateEngine(new FreemarkerTemplateEngine())
            .execute();
        System.out.println("✅ 代码生成完成！");
    }
}

自动填充处理器

 package com.example.config;
 import com.baomidou.mybatisplus.core.handlers.MetaObjectHandler;
 import org.apache.ibatis.reflection.MetaObject;
 import org.springframework.stereotype.Component;
 import java.time.LocalDateTime;
 /**
 * 自动填充处理器
 * 配合实体类 @TableField(fill = FieldFill.INSERT) 使用
 */
@Component
public class MyMetaObjectHandler implements MetaObjectHandler {
    @Override
    public void insertFill(MetaObject metaObject) {
        // 新增时自动填充
        this.strictInsertFill(metaObject, "createTime",
            LocalDateTime.class, LocalDateTime.now());
        this.strictInsertFill(metaObject, "updateTime",
            LocalDateTime.class, LocalDateTime.now());
    }
    @Override
    public void updateFill(MetaObject metaObject) {
        // 更新时自动填充
        this.strictUpdateFill(metaObject, "updateTime",
            LocalDateTime.class, LocalDateTime.now());
    }
}

分页配置

 package com.example.config;
 import com.baomidou.mybatisplus.annotation.DbType;
 import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
 import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 @Configuration
public class MyBatisPlusConfig {
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        // 分页插件
        interceptor.addInnerInterceptor(
            new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}

测试使用

 package com.example.controller;
 import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
 import com.example.entity.Emp;
 import com.example.service.EmpService;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.web.bind.annotation.*;
import java.util.List;
@Tag(name = "员工管理")
@RestController
@RequestMapping("/emp")
public class EmpController {
    @Autowired
    private EmpService empService;
    @Operation(summary = "分页查询")
    @GetMapping("/page")
    public Page<Emp> page(
            @RequestParam(defaultValue = "1") Integer current,
            @RequestParam(defaultValue = "10") Integer size) {
        return empService.page(new Page<>(current, size));
    }
    @Operation(summary = "条件分页查询")
    @GetMapping("/search")
    public Page<Emp> search(
            @RequestParam(defaultValue = "1") Integer current,
            @RequestParam(defaultValue = "10") Integer size,
            @RequestParam(required = false) String name,
            @RequestParam(required = false) String gender,
            @RequestParam(required = false) Integer deptId) {
        Page<Emp> page = new Page<>(current, size);
        return empService.lambdaQuery()
                .like(name != null && !name.isEmpty(), Emp::getEmpName, name)
                .eq(gender != null && !gender.isEmpty(), Emp::getGender, gender)
                .eq(deptId != null, Emp::getDeptId, deptId)
                .orderByDesc(Emp::getSalary)
                .page(page);
    }
    @Operation(summary = "新增")
    @PostMapping
    public boolean save(@RequestBody Emp emp) {
        return empService.save(emp);
    }
    @Operation(summary = "批量新增")
    @PostMapping("/batch")
    public boolean saveBatch(@RequestBody List<Emp> list) {
        return empService.saveBatch(list);
    }
    @Operation(summary = "根据ID查询")
    @GetMapping("/{id}")
    public Emp getById(@PathVariable Integer id) {
        return empService.getById(id);
    }
    @Operation(summary = "更新")
    @PutMapping
    public boolean update(@RequestBody Emp emp) {
        return empService.updateById(emp);
    }
    @Operation(summary = "根据ID删除")
    @DeleteMapping("/{id}")
    public boolean delete(@PathVariable Integer id) {
        return empService.removeById(id);
    }
}

实战案例三：自定义插件生成 Swagger 注解

需求

让 MBG 生成的实体类自动添加 Swagger/OpenAPI 注解：

@Schema(description = "员工表")
public class Emp {
    @Schema(description = "员工ID")
    private Integer empId;
    @Schema(description = "员工姓名")
    private String empName;
}

自定义 Swagger 插件

 package com.example.generator;
 import org.mybatis.generator.api.IntrospectedColumn;
 import org.mybatis.generator.api.IntrospectedTable;
 import org.mybatis.generator.api.PluginAdapter;
 import org.mybatis.generator.api.dom.java.*;
 import java.util.List;
/**
 * 自定义 Swagger 注解插件
 * 自动给实体类和字段添加 @Schema 注解
 */
public class SwaggerAnnotationPlugin extends PluginAdapter {
    private static final String SCHEMA = "io.swagger.v3.oas.annotations.media.Schema";
    @Override
    public boolean validate(List<String> warnings) {
        return true;
    }
    /**
     * 给实体类添加 @Schema 注解
     */
    @Override
    public boolean modelBaseRecordClassGenerated(TopLevelClass topLevelClass,
                                                  IntrospectedTable introspectedTable)
     {
        // 导入 @Schema
        topLevelClass.addImportedType(SCHEMA);
        // 生成注解：@Schema(description = "表注释")
        String remark = introspectedTable.getRemarks();
        String description = (remark != null && !remark.trim().isEmpty())
                ? remark
                : introspectedTable.getFullyQualifiedTable().toString();
        topLevelClass.addAnnotation("@Schema(description = \"" + escape(description) +
     "\")");
        return true;
    }
    /**
     * 给字段添加 @Schema 注解
     */
    @Override
    public boolean modelFieldGenerated(Field field,
                                        TopLevelClass topLevelClass,
                                        IntrospectedColumn introspectedColumn,
                                        IntrospectedTable introspectedTable,
                                        ModelClassType modelClassType) {
        // 确保 @Schema 已导入
        if (!topLevelClass.getImportedTypes().stream()
                .anyMatch(t -> t.getFullyQualifiedName().equals(SCHEMA))) {
            topLevelClass.addImportedType(SCHEMA);
        }
        // 生成字段注解
        String remark = introspectedColumn.getRemarks();
        String description = (remark != null && !remark.trim().isEmpty())
                ? remark
                : introspectedColumn.getActualColumnName();
        field.addAnnotation("@Schema(description = \"" + escape(description) + "\")");
        return true;
    }
    /**
     * 转义特殊字符
     */
    private String escape(String s) {
        return s.replace("\"", "\\\"").replace("\n", " ").trim();
    }
}

配置使用

 <context id="mysqlContext" targetRuntime="MyBatis3">
     <!-- ★ Swagger 注解插件 -->
     <plugin type="com.example.generator.SwaggerAnnotationPlugin"/>
     <!-- ★ Lombok 插件（配合使用） -->
     <plugin type="com.example.generator.LombokPlugin"/>
     <!-- Serializable -->
    <plugin type="org.mybatis.generator.plugins.SerializablePlugin"/>
    <commentGenerator>
        <property name="suppressAllComments" value="true"/>
    </commentGenerator>
    <jdbcConnection driverClass="com.mysql.cj.jdbc.Driver"
                    connectionURL="jdbc:mysql://localhost:3306/mybatis_demo"
                    userId="root" password="123456">
        <property name="useInformationSchema" value="true"/>
    </jdbcConnection>
    <javaTypeResolver>
        <property name="useJSR310Types" value="true"/>
    </javaTypeResolver>
    <javaModelGenerator targetPackage="com.example.entity"
                        targetProject="src/main/java">
        <property name="trimStrings" value="true"/>
    </javaModelGenerator>
    <sqlMapGenerator targetPackage="mapper"
                     targetProject="src/main/resources">
    </sqlMapGenerator>
    <javaClientGenerator type="XMLMAPPER"
                         targetPackage="com.example.mapper"
                         targetProject="src/main/java">
    </javaClientGenerator>
    <table tableName="emp" domainObjectName="Emp">
        <generatedKey column="emp_id" sqlStatement="MySql" identity="true"/>
    </table>
</context>

生成的实体类效果

 package com.example.entity;
 import io.swagger.v3.oas.annotations.media.Schema;
 import java.io.Serializable;
 import java.math.BigDecimal;
 import java.time.LocalDate;
 import java.time.LocalDateTime;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "员工表")
public class Emp implements Serializable {
    private static final long serialVersionUID = 1L;
    @Schema(description = "员工ID")
    private Integer empId;
    @Schema(description = "员工姓名")
    private String empName;
    @Schema(description = "性别 M-男 F-女")
    private String gender;
    @Schema(description = "邮箱")
    private String email;
    @Schema(description = "工资")
    private BigDecimal salary;
    @Schema(description = "所属部门ID")
    private Integer deptId;
    @Schema(description = "入职日期")
    private LocalDate hireDate;
    @Schema(description = "创建时间")
    private LocalDateTime createTime;
    @Schema(description = "更新时间")
    private LocalDateTime updateTime;
}

常见问题与排错

生成后没有表注释和字段注释

原因： MySQL 8.x 默认不返回注释信息。

解决： 在 <jdbcConnection> 中添加 <property name=“useInformationSchema” value=“true”/>。

<jdbcConnection ...>
    <property name="useInformationSchema" value="true"/>
</jdbcConnection>

日期类型生成的是 Date 而不是 LocalDateTime

原因： 默认使用 java.util.Date。

解决： 在 <javaTypeResolver> 中开启 JSR-310：

<javaTypeResolver>
    <property name="useJSR310Types" value="true"/>
</javaTypeResolver>

注意：此属性在 MBG 1.4.0+ 才支持。DATETIME → LocalDateTime，DATE → LocalDate，TIME → LocalTime。

文件覆盖问题：XML 文件没有完全覆盖

原因： MBG 默认对 XML 文件使用 merge（合并） 策略，而不是完全覆盖。这是为了保护你手写的自定义 SQL。

解决： 使用 UnmergeableXmlMapperPlugin 插件强制覆盖：

1<plugin type=“org.mybatis.generator.plugins.UnmergeableXmlMapperPlugin”/>

生成的包名多了一层 schema 名

原因： enableSubPackages 设为 true 时，会将 schema 名作为包的后缀。

解决： 设置 enableSubPackages=“false”：

<javaModelGenerator targetPackage="com.example.entity" ...>
    <property name="enableSubPackages" value="false"/>
</javaModelGenerator>

主键没有回填（insert 后实体类中 id 为 null）

原因： 没有配置 <generatedKey>。

解决：

<table tableName="emp" domainObjectName="Emp">
    <generatedKey column="emp_id" sqlStatement="MySql" identity="true"/>
</table>

Maven 插件运行时找不到驱动

原因： Maven 插件的 classpath 中没有 MySQL 驱动。

解决： 在 <plugin> 的 <dependencies> 中添加驱动：

 <plugin>
     <groupId>org.mybatis.generator</groupId>
     <artifactId>mybatis-generator-maven-plugin</artifactId>
     <version>1.4.2</version>
     <dependencies>
         <dependency>
             <groupId>com.mysql</groupId>
             <artifactId>mysql-connector-j</artifactId>
             <version>8.0.33</version>
        </dependency>
    </dependencies>
</plugin>

MySQL 关键字冲突（如`desc`, `order`, `key`）

原因： 表名或字段名是 MySQL 保留字。

解决： 在 context 上配置分隔符：

<context id="mysqlContext" targetRuntime="MyBatis3"
         autoDelimitKeywords="true"
         beginningDelimiter="`"
         endingDelimiter="`">

或者在 table 上配置：

1<table tableName=“order” delimitIdentifiers=“true”>

MP Generator 生成的代码在错误的目录

原因： outputDir 路径不正确。

解决： 使用 System.getProperty(“user.dir”) 确保路径正确：

String projectPath = System.getProperty("user.dir");
FastAutoGenerator.create(url, username, password)
    .globalConfig(builder -> builder
        .outputDir(projectPath + "/src/main/java")  // 绝对路径
    )
    ...

MBG 生成文件中文乱码

原因： 编码不一致。

解决： 在 pom.xml 中配置编码：

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

并在 Maven 插件中配置：

<plugin>
    <groupId>org.mybatis.generator</groupId>
    <artifactId>mybatis-generator-maven-plugin</artifactId>
    <configuration>
        <configurationFile>src/main/resources/generatorConfig.xml</configurationFile>
    </configuration>
</plugin>

MP Generator 3.5.x API 变化

问题： 从 3.4.x 升级到 3.5.x 后 API 不兼容。

主要变化：

3.4.x（旧）	3.5.x（新）
new AutoGenerator()	new AutoGenerator(dataSourceConfig)
generator.setDataSource(config)	构造器参数传入
generator.setGlobalConfig(config)	generator.global(config)
generator.setStrategy(config)	generator.strategy(config)
generator.setPackageInfo(config)	generator.packageInfo(config)
generator.setTemplate(config)	generator.template(config)

最佳实践

生成策略选择

是否需要 Service / Controller？
├── 是 → 使用 MyBatis-Plus Generator
│        （自带 Service / Controller / BaseMapper）
│
└── 否 → 使用 MyBatis Generator
         （仅生成 Entity / Mapper / XML / Example）

将生成代码与自定义代码分离

核心原则：生成的代码可以随时重新生成，不要直接修改。

正确的做法：
├── 生成的 Mapper 接口 ← 保持不变（继承 BaseMapper 扩展）
├── 自定义 SQL ← 新建 CustomXxxMapper.java 或在同一 XML 中追加
└── 业务逻辑 ← 写在 Service 层
错误的做法：
├── 直接在生成的 EmpMapper.java 中添加方法 ← 重新生成会被覆盖
├── 直接在生成的 EmpMapper.xml 中修改 SQL ← merge 可能保留，但有风险
└── 直接在生成的 Emp.java 中添加逻辑 ← 重新生成会被覆盖

XML 自定义 SQL 扩展方案

 <!-- EmpMapper.xml — MBG 生成的部分保持不变 -->
 <!-- ====== 以下为手动追加的自定义 SQL ====== -->
 <!-- 多表关联查询 -->
 <select id="selectEmpWithDept" resultMap="EmpWithDeptResultMap">
     SELECT e.*, d.dept_name, d.location
     FROM emp e
     LEFT JOIN dept d ON e.dept_id = d.dept_id
    WHERE e.emp_id = #{empId}
</select>
<resultMap id="EmpWithDeptResultMap" type="com.example.dto.EmpDeptDTO">
    <id column="emp_id" property="empId"/>
    <result column="emp_name" property="empName"/>
    <result column="gender" property="gender"/>
    <result column="salary" property="salary"/>
    <result column="dept_name" property="deptName"/>
    <result column="location" property="location"/>
</resultMap>

配置管理建议

项目结构建议：
├── src/main/resources/
│   ├── generator/
│   │   ├── generatorConfig.xml      ← MBG 配置
│   │   ├── generator.properties     ← 数据库连接属性
│   │   └── generator-dev.properties ← 开发环境属性（可选）
│   ├── mapper/
│   │   └── EmpMapper.xml            ← 生成的 XML
│   └── mybatis-config.xml

生成 vs 手写决策表

场景	建议方式
单表 CRUD	逆向工程生成
单表条件查询	MBG 的 Example 或 MP 的 LambdaQueryWrapper
多表 JOIN 查询	手写 SQL（XML 或注解）
复杂统计报表	手写 SQL
分页查询	MP 分页插件
批量操作	MP 的 saveBatch / updateBatchById

速查表

MBG 配置元素速查表

元素	作用	必填
<generatorConfiguration>	根元素	是
<properties>	引入属性文件	否
<classPathEntry>	数据库驱动路径	Maven 方式可省
<context>	生成上下文	是
<plugin>	插件配置	否
<commentGenerator>	注释生成器	否
<jdbcConnection>	数据库连接	是
<javaTypeResolver>	类型解析器	否
<javaModelGenerator>	实体类生成器	是
<sqlMapGenerator>	XML 生成器	XMLMAPPER 模式必填
<javaClientGenerator>	Mapper 接口生成器	是
<table>	表配置	是

MBG 内置插件速查表

插件	功能
SerializablePlugin	实体类实现 Serializable
ToStringPlugin	生成 toString()
EqualsAndHashCodePlugin	生成 equals() 和 hashCode()
FluentBuilderMethodsPlugin	链式 setter
RowBoundsPlugin	RowBounds 分页
RenameExampleClassPlugin	重命名 Example 类
MapperNamePlugin	自定义 Mapper 名称
UnmergeableXmlMapperPlugin	XML 强制覆盖
CaseInsensitiveLikePlugin	大小写不敏感 LIKE
VirtualKeyPlugin	虚拟主键

MBG targetRuntime 速查表

值	生成 Example	生成 XML	说明
MyBatis3	✅	✅	完整版（默认）
MyBatis3Simple	❌	✅	简化版（仅基本 CRUD）
MyBatis3DynamicSql	❌	❌	动态 SQL DSL 版
MyBatis3Kotlin	❌	❌	Kotlin 版

MP Generator 配置速查表

配置项	方法	说明
作者	globalConfig.author(“xxx”)	注释中的作者名
输出目录	globalConfig.outputDir(“path”)	代码输出根目录
Swagger	globalConfig.enableSwagger()	开启 Swagger 注解
父包	packageConfig.parent(“com.xxx”)	根包名
表名	strategyConfig.addInclude(“table”)	指定要生成的表
表前缀	strategyConfig.addTablePrefix(“t_“)	去掉表前缀
Lombok	entityBuilder.enableLombok()	使用 Lombok
主键策略	entityBuilder.idType(IdType.AUTO)	主键生成策略
命名策略	entityBuilder.naming(…)	下划线转驼峰
RestController	controllerBuilder.enableRestStyle()	REST 风格

Example 方法速查表

 EmpExample example = new EmpExample();
 // 创建 AND 条件组
 EmpExample.Criteria criteria = example.createCriteria();
 // 等值
 criteria.andXxxEqualTo(value);          // = value
 criteria.andXxxNotEqualTo(value);       // <> value
// 范围
criteria.andXxxGreaterThan(value);      // > value
criteria.andXxxGreaterThanOrEqualTo(value); // >= value
criteria.andXxxLessThan(value);         // < value
criteria.andXxxLessThanOrEqualTo(value); // <= value
criteria.andXxxBetween(v1, v2);        // BETWEEN v1 AND v2
criteria.andXxxNotBetween(v1, v2);     // NOT BETWEEN
// 集合
criteria.andXxxIn(list);               // IN (...)
criteria.andXxxNotIn(list);            // NOT IN (...)
// 模糊
criteria.andXxxLike("%keyword%");      // LIKE '%keyword%'
criteria.andXxxNotLike("%keyword%");   // NOT LIKE '%keyword%'
// NULL
criteria.andXxxIsNull();               // IS NULL
criteria.andXxxIsNotNull();            // IS NOT NULL
// OR 条件组
example.or().andXxxEqualTo(value);     // OR (...)
// 排序
example.setOrderByClause("salary DESC");
// 去重
example.setDistinct(true);

类型映射速查表

MySQL 类型	Java 类型（`useJSR310Types=true`）	JDBC 类型
`INT`	`Integer`	`INTEGER`
`BIGINT`	`Long`	`BIGINT`
`TINYINT`	`Integer`	`TINYINT`
`SMALLINT`	`Integer`	`SMALLINT`
`DECIMAL`	`BigDecimal`	`DECIMAL`
`VARCHAR`	`String`	`VARCHAR`
`CHAR`	`String`	`CHAR`
`TEXT`	`String`	`LONGVARCHAR`
`DATE`	`LocalDate`	`DATE`
`DATETIME`	`LocalDateTime`	`TIMESTAMP`
`TIME`	`LocalTime`	`TIME`
`TIMESTAMP`	`LocalDateTime`	`TIMESTAMP`
`BLOB`	`byte[]`	`LONGVARBINARY`
`BIT`	`Boolean`	`BIT`
`FLOAT`	`Float`	`FLOAT`
`DOUBLE`	`Double`	`DOUBLE`
`JSON`	`String`	`VARCHAR`

常用命令速查表

 # ====== MBG ======
 # Maven 插件执行
 mvn mybatis-generator:generate
 # 指定配置文件
 mvn mybatis-generator:generate -DconfigurationFile=src/main/resources/generatorConfig.xml
 # 不覆盖已有文件
mvn mybatis-generator:generate -Doverwrite=false
# 命令行执行
java -jar mybatis-generator-core-1.4.2.jar -configfile generatorConfig.xml -overwrite
# ====== MP Generator ======
# 直接运行 main 方法（IDE 中右键运行）
# 或使用 Maven exec 插件
mvn exec:java -Dexec.mainClass="com.example.generator.CodeGenerator"

总结： MyBatis 逆向工程的核心在于理解「数据库表结构 → Java 代码」的自动映射过程。MyBatis Generator 是官方工具，稳定可靠，适合生成基础 DAO 层代码；MyBatis-Plus Generator 功能更丰富，能一键生成从 Entity 到 Controller 的全栈代码。两者都可以通过自定义插件和模板深度定制生成结果。掌握逆向工程可以大幅提升开发效率，但需谨记：应将可重复生成的代码与自定义代码分离，并在重新生成前确认覆盖范围；扩展查询可放在独立 Mapper、扩展接口或自定义 SQL 中。