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

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);

4.3 禁止写法

• 禁止逻辑删除时不设置 .set(Entity::getDeleted, true)，直接使用 delete 方法。

• 禁止物理删除时不添加逻辑删除筛选条件，避免误删已删除数据。

• 禁止无业务条件的批量删除（如 wrapper.eq(Entity::getDeleted, false) 直接删除，需添加具体业务筛选）。

五、附则

• 本规范自发布之日起执行，所有新增、修改的 MyBatis-Plus 链式调用代码需严格遵循。

• 若业务场景有特殊需求（如无需逻辑删除、需查询所有字段等），需在代码中添加注释说明，经团队确认后可例外。

• 本规范将根据项目迭代、MyBatis-Plus 版本更新，适时调整优化，确保规范的适用性和合理性。