规范说明：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 实例 LambdaQueryWrapperEntity 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 实体LambdaQueryWrapperFileSource 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 ); // 执行查询 ListFileSource fileSources fileMapper.selectList(wrapper);2.4 禁止写法禁止 .select() 放于条件、排序之前如wrapper.select(...).eq(...)。禁止不添加逻辑删除条件除非特殊需求需在代码中添加注释说明。禁止查询时不指定 .select()默认查询所有字段尤其是包含大字段的实体。三、更新场景LambdaUpdateWrapper规范3.1 链式调用固定顺序优先级修改字段.set() 放最前 → 业务条件 → 安全条件 → 乐观锁按需3.2 规范写法模板// 1. 创建 Wrapper 实例 LambdaUpdateWrapperEntity 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 实体LambdaUpdateWrapperFileSource 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 逻辑删除推荐LambdaUpdateWrapper4.1.1 链式调用固定顺序优先级逻辑删除字段设置.set() 放最前 → 业务条件 → 安全条件4.1.2 规范写法模板LambdaUpdateWrapperEntity 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 实体LambdaUpdateWrapperFileSource 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 物理删除特殊场景LambdaQueryWrapper4.2.1 链式调用固定顺序优先级业务条件 → 安全条件逻辑删除筛选避免误删4.2.2 规范写法模板LambdaQueryWrapperEntity wrapper Wrappers.lambdaQuery(); wrapper // 第一步业务条件 .eq(Entity::getId, 主键值) .eq(Entity::getField1, 业务条件值) // 第二步安全条件必加筛选未删除数据 .eq(Entity::getDeleted, false);4.2.3 项目业务示例FileSource 实体LambdaQueryWrapperFileSource 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 版本更新适时调整优化确保规范的适用性和合理性。