当前位置：首页 > news >正文

规范说明：MyBatis\-Plus 链式查询/更新/删除

news 2026/4/27 8:51:05

MyBatis-Plus 链式查询/更新/删除规范说明

目的：统一团队 MyBatis-Plus Lambda 链式调用写法，提升代码可读性、可维护性，降低团队协作成本；确保链式调用逻辑清晰、语义对齐 SQL 语法，同时保证功能一致性和性能最优。本规范适用于所有使用 MyBatis-Plus LambdaQueryWrapper、LambdaUpdateWrapper 的业务场景。

一、通用基础规范

所有链式调用需遵循「语义优先、顺序统一」原则，调用顺序不影响 SQL 生成及性能，但必须严格遵循本规范规定的顺序，禁止随意调整。
必加安全条件：所有涉及业务数据的操作（查询、更新、删除），必须添加逻辑删除筛选条件（.eq(Entity::getDeleted, false)），除非有明确的特殊业务需求（如查询已删除数据）。
字段指定规范：查询时优先使用 .select() 指定所需字段，排除大字段（如文件二进制、长文本）和冗余字段，提升查询性能；更新时仅 .set() 所需修改的字段，避免无用更新。
代码格式：链式调用每行仅写一个方法（如 .eq()、.set()），缩进对齐，提升可读性；禁止多行方法挤在一行书写。
Wrapper 实例创建：统一使用 Wrappers.lambdaQuery()、Wrappers.lambdaUpdate() 创建实例，禁止使用 new 关键字直接创建。

二、查询场景（LambdaQueryWrapper）规范

2.1 链式调用固定顺序

优先级：业务条件 → 安全条件 → 排序 → 分页 → 字段筛选（.select() 放最后）

2.2 规范写法模板

// 1. 创建 Wrapper 实例 LambdaQueryWrapper<Entity> wrapper = Wrappers.lambdaQuery(); // 2. 链式调用（严格遵循顺序） wrapper // 第一步：业务条件（等值、范围、模糊等查询条件） .eq(Entity::getField1, 条件值1) // 等值查询 .ne(Entity::getField2, 条件值2) // 不等值查询 .in(Entity::getField3, 集合条件) // 范围查询 .like(Entity::getField4, 模糊条件) // 模糊查询 .ge(Entity::getField5, 起始值) // 大于等于 .le(Entity::getField6, 结束值) // 小于等于 // 第二步：安全条件（必加，逻辑删除筛选） .eq(Entity::getDeleted, false) // 第三步：排序（按需添加，优先按创建时间降序） .orderByDesc(Entity::getCreateTime) // 降序排序 .orderByAsc(Entity::getSortNum) // 升序排序（按需补充） // 第四步：分页（按需添加，分页条件放排序之后） .last("LIMIT " + (pageNum-1)*pageSize + "," + pageSize) // 手动分页（或配合 Page 对象） // 第五步：字段筛选（最后一步，指定查询字段，排除冗余/大字段） .select( Entity::getId, Entity::getField1, Entity::getField2, Entity::getCreateTime );

2.3 项目业务示例（FileSource 实体）

LambdaQueryWrapper<FileSource> wrapper = Wrappers.lambdaQuery(); wrapper // 业务条件 .eq(FileSource::getBusinessType, businessType) .eq(FileSource::getBusinessKey, businessKey) // 安全条件（必加） .eq(FileSource::getDeleted, false) // 排序 .orderByDesc(FileSource::getCreateTime) // 字段筛选（排除 fileData 大字段） .select( FileSource::getFileId, FileSource::getFileName, FileSource::getOriginalName, FileSource::getFileExtension, FileSource::getFileSize, FileSource::getBusinessType, FileSource::getBusinessKey ); // 执行查询 List<FileSource> fileSources = fileMapper.selectList(wrapper);

2.4 禁止写法

禁止 .select() 放于条件、排序之前（如：wrapper.select(...).eq(...)）。
禁止不添加逻辑删除条件（除非特殊需求，需在代码中添加注释说明）。
禁止查询时不指定 .select()，默认查询所有字段（尤其是包含大字段的实体）。

三、更新场景（LambdaUpdateWrapper）规范

3.1 链式调用固定顺序

优先级：修改字段（.set() 放最前） → 业务条件 → 安全条件 → 乐观锁（按需）

3.2 规范写法模板

// 1. 创建 Wrapper 实例 LambdaUpdateWrapper<Entity> wrapper = Wrappers.lambdaUpdate(); // 2. 链式调用（严格遵循顺序） wrapper // 第一步：修改字段（.set() 全部放最顶部，每行一个修改字段） .set(Entity::getField1, 新值1) .set(Entity::getField2, 新值2) .set(Entity::getUpdateTime, LocalDateTime.now()) // 若有更新时间自动填充，可省略 // 第二步：业务条件（指定更新哪些数据） .eq(Entity::getId, 主键值) .eq(Entity::getField3, 业务条件值) // 第三步：安全条件（必加，逻辑删除筛选） .eq(Entity::getDeleted, false) // 第四步：乐观锁（按需添加，防止并发更新冲突） .eq(Entity::getVersion, 版本号);

3.3 项目业务示例（FileSource 实体）

LambdaUpdateWrapper<FileSource> wrapper = Wrappers.lambdaUpdate(); wrapper // 修改字段（放最前） .set(FileSource::getFileName, newFileName) .set(FileSource::getUpdateTime, LocalDateTime.now()) // 业务条件 .eq(FileSource::getFileId, fileId) // 安全条件（必加） .eq(FileSource::getDeleted, false); // 执行更新 fileMapper.update(null, wrapper);

3.4 禁止写法

禁止 .set() 放于条件之后（如：wrapper.eq(...).set(...)）。
禁止修改字段时，一次性 .set() 多个字段（需每行一个 .set()）。
禁止更新时不添加逻辑删除条件，避免更新已删除数据。

四、删除场景规范

删除场景优先使用「逻辑删除」（推荐），物理删除仅用于特殊业务场景（需团队确认），两种场景分别遵循以下规范。

4.1 逻辑删除（推荐，LambdaUpdateWrapper）

4.1.1 链式调用固定顺序

优先级：逻辑删除字段设置（.set() 放最前） → 业务条件 → 安全条件

4.1.2 规范写法模板

LambdaUpdateWrapper<Entity> wrapper = Wrappers.lambdaUpdate(); wrapper // 第一步：设置逻辑删除标识（放最前） .set(Entity::getDeleted, true) .set(Entity::getUpdateTime, LocalDateTime.now()) // 按需添加 // 第二步：业务条件 .eq(Entity::getId, 主键值) .eq(Entity::getField1, 业务条件值) // 第三步：安全条件（必加，确保不删除已删除数据） .eq(Entity::getDeleted, false);

4.1.3 项目业务示例（FileSource 实体）

LambdaUpdateWrapper<FileSource> wrapper = Wrappers.lambdaUpdate(); wrapper .set(FileSource::getDeleted, true) .set(FileSource::getUpdateTime, LocalDateTime.now()) .eq(FileSource::getFileId, fileId) .eq(FileSource::getDeleted, false); // 执行逻辑删除 fileMapper.update(null, wrapper);

4.2 物理删除（特殊场景，LambdaQueryWrapper）

4.2.1 链式调用固定顺序

优先级：业务条件 → 安全条件（逻辑删除筛选，避免误删）

4.2.2 规范写法模板

LambdaQueryWrapper<Entity> wrapper = Wrappers.lambdaQuery(); wrapper // 第一步：业务条件 .eq(Entity::getId, 主键值) .eq(Entity::getField1, 业务条件值) // 第二步：安全条件（必加，筛选未删除数据） .eq(Entity::getDeleted, false);

4.2.3 项目业务示例（FileSource 实体）

LambdaQueryWrapper<FileSource> wrapper = Wrappers.lambdaQuery(); wrapper .eq(FileSource::getFileId, fileId) .eq(FileSource::getDeleted, false); // 执行物理删除（需确认业务场景） fileMapper.delete(wrapper);