CRUD 重点文件与方法

Business 服务继承的 CRUD 入口集中在这里。PO 是持久化对象，DTO 是写入模型，VO 是详情/列表模型，MAP 是简要映射模型，QUERY 是查询条件。类型绑定和 Mapper 接入见快速开始。

本页按重点文件查阅方法；表内方法名可打开源码。重载共享的约束写在表前，差异在各行说明。源码链接固定到核对版本，接入前提见快速开始。

BaseService

源码：BaseService；实现：AbstractBaseService。

聚合查询、必取、列表、新增、修改、删除、导入导出及开关能力，本文件自身没有新方法。下文分别列出父接口方法与 AbstractBaseService 的实现；不能因为子业务 Service 文件短，就认为只有它直接声明的方法可用。

共同边界：通用服务不会自动按当前用户/工作空间过滤，也不统一开启事务。直接调用 Java 服务需自行验证权限和 DTO；调用 DTO 方法不等于触发 Controller 的 Bean Validation。返回 VO 通常由输入 PO 转换而来，不保证重新读取数据库默认值、触发器或更新行数。

BaseQueryService

源码：BaseQueryService；实现：AbstractBaseService。

可空查询：没有数据时返回 null。ById 使用主键；ByFkId 限定 Long 外键；ByExtractor 可使用任意字段类型；ByWrapper 使用应用构造的 LambdaQueryWrapper。Wrapper/字段查询底层 selectOne，多条匹配可能抛异常，不能当作“取第一条”。

方法 / 重载	用途、参数与返回值	注意事项
queryPoById(Long id)	按主键返回PO，缺失返回 null。	调用者处理 null。默认实现查询命中先走 afterGetPo。
queryPoById(Long id, Supplier<PO> defaultFunction)	按主键返回PO，缺失时执行 defaultFunction，仍为 null 则返回 null。	兜底 Supplier 接收空参数、返回 PO；不自动保存兜底对象。默认实现查询命中先走 afterGetPo。
queryVoById(Long id)	按主键返回转换后的 VO，缺失返回 null。	调用者处理 null。VO 路径执行 afterQueryVo。
queryVoById(Long id, Supplier<PO> defaultFunction)	按主键返回转换后的 VO，缺失时执行 defaultFunction，仍为 null 则返回 null。	兜底 Supplier 接收空参数、返回 PO；不自动保存兜底对象。VO 路径执行 afterQueryVo。
queryPoByFkId(SFunction<PO,Long> keyExtractor, Long fkId)	按Long 外键返回PO，缺失返回 null。	调用者处理 null。默认实现查询命中先走 afterGetPo。
queryPoByFkId(SFunction<PO,Long> keyExtractor, Long fkId, Supplier<PO> defaultFunction)	按Long 外键返回PO，缺失时执行 defaultFunction，仍为 null 则返回 null。	兜底 Supplier 接收空参数、返回 PO；不自动保存兜底对象。默认实现查询命中先走 afterGetPo。
queryVoByFkId(SFunction<PO,Long> keyExtractor, Long fkId)	按Long 外键返回转换后的 VO，缺失返回 null。	调用者处理 null。VO 路径执行 afterQueryVo。
queryVoByFkId(SFunction<PO,Long> keyExtractor, Long fkId, Supplier<PO> defaultFunction)	按Long 外键返回转换后的 VO，缺失时执行 defaultFunction，仍为 null 则返回 null。	兜底 Supplier 接收空参数、返回 PO；不自动保存兜底对象。VO 路径执行 afterQueryVo。
queryPoByExtractor(SFunction<PO,T> keyExtractor, T value)	按字段等值返回PO，缺失返回 null。	调用者处理 null。默认实现查询命中先走 afterGetPo。
queryPoByExtractor(SFunction<PO,T> keyExtractor, T value, Supplier<PO> defaultFunction)	按字段等值返回PO，缺失时执行 defaultFunction，仍为 null 则返回 null。	兜底 Supplier 接收空参数、返回 PO；不自动保存兜底对象。默认实现查询命中先走 afterGetPo。
queryVoByExtractor(SFunction<PO,T> keyExtractor, T value)	按字段等值返回转换后的 VO，缺失返回 null。	调用者处理 null。VO 路径执行 afterQueryVo。
queryVoByExtractor(SFunction<PO,T> keyExtractor, T value, Supplier<PO> defaultFunction)	按字段等值返回转换后的 VO，缺失时执行 defaultFunction，仍为 null 则返回 null。	兜底 Supplier 接收空参数、返回 PO；不自动保存兜底对象。VO 路径执行 afterQueryVo。
queryPoByWrapper(LambdaQueryWrapper<PO> wrapper)	按Wrapper 条件返回PO，缺失返回 null。	调用者处理 null。默认实现查询命中先走 afterGetPo。
queryPoByWrapper(LambdaQueryWrapper<PO> wrapper, Supplier<PO> defaultFunction)	按Wrapper 条件返回PO，缺失时执行 defaultFunction，仍为 null 则返回 null。	兜底 Supplier 接收空参数、返回 PO；不自动保存兜底对象。默认实现查询命中先走 afterGetPo。
queryVoByWrapper(LambdaQueryWrapper<PO> wrapper)	按Wrapper 条件返回转换后的 VO，缺失返回 null。	调用者处理 null。VO 路径执行 afterQueryVo。
queryVoByWrapper(LambdaQueryWrapper<PO> wrapper, Supplier<PO> defaultFunction)	按Wrapper 条件返回转换后的 VO，缺失时执行 defaultFunction，仍为 null 则返回 null。	兜底 Supplier 接收空参数、返回 PO；不自动保存兜底对象。VO 路径执行 afterQueryVo。

BaseGetService

源码：BaseGetService。

必取查询：所有 get 方法最终要求非 null PO，否则抛 BusinessSimpleException。默认消息来自 NOT_FOUND_OBJECT；可传 ResponseMessage 覆盖，存在服务模块名时按模块名格式化。方法名称组合的查询范围与 BaseQueryService 相同。

方法 / 重载	用途、参数与返回值	注意事项
getPoById(Long id)	按主键返回PO。缺失抛默认业务异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getPoById(Long id, ResponseMessage responseCode)	按主键返回PO。缺失抛指定消息的业务异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getPoById(Long id, Supplier<PO> defaultFunction)	按主键返回PO。先调用兜底，仍缺失才抛默认异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getPoById(Long id, ResponseMessage responseCode, Supplier<PO> defaultFunction)	按主键返回PO。先调用兜底，仍缺失才抛指定消息异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getVoById(Long id)	按主键返回VO。缺失抛默认业务异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getVoById(Long id, ResponseMessage responseCode)	按主键返回VO。缺失抛指定消息的业务异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getVoById(Long id, Supplier<PO> defaultFunction)	按主键返回VO。先调用兜底，仍缺失才抛默认异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getVoById(Long id, ResponseMessage responseCode, Supplier<PO> defaultFunction)	按主键返回VO。先调用兜底，仍缺失才抛指定消息异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getPoByFkId(SFunction<PO,Long> keyExtractor, Long fkId)	按Long 外键返回PO。缺失抛默认业务异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getPoByFkId(SFunction<PO,Long> keyExtractor, Long fkId, ResponseMessage responseCode)	按Long 外键返回PO。缺失抛指定消息的业务异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getPoByFkId(SFunction<PO,Long> keyExtractor, Long fkId, Supplier<PO> defaultFunction)	按Long 外键返回PO。先调用兜底，仍缺失才抛默认异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getPoByFkId(SFunction<PO,Long> keyExtractor, Long fkId, ResponseMessage responseCode, Supplier<PO> defaultFunction)	按Long 外键返回PO。先调用兜底，仍缺失才抛指定消息异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getVoByFkId(SFunction<PO,Long> keyExtractor, Long fkId)	按Long 外键返回VO。缺失抛默认业务异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getVoByFkId(SFunction<PO,Long> keyExtractor, Long fkId, ResponseMessage responseCode)	按Long 外键返回VO。缺失抛指定消息的业务异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getVoByFkId(SFunction<PO,Long> keyExtractor, Long fkId, Supplier<PO> defaultFunction)	按Long 外键返回VO。先调用兜底，仍缺失才抛默认异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getVoByFkId(SFunction<PO,Long> keyExtractor, Long fkId, ResponseMessage responseCode, Supplier<PO> defaultFunction)	按Long 外键返回VO。先调用兜底，仍缺失才抛指定消息异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getPoByExtractor(SFunction<PO,T> keyExtractor, T value)	按字段等值返回PO。缺失抛默认业务异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getPoByExtractor(SFunction<PO,T> keyExtractor, T value, ResponseMessage responseCode)	按字段等值返回PO。缺失抛指定消息的业务异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getPoByExtractor(SFunction<PO,T> keyExtractor, T value, Supplier<PO> defaultFunction)	按字段等值返回PO。先调用兜底，仍缺失才抛默认异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getPoByExtractor(SFunction<PO,T> keyExtractor, T value, ResponseMessage responseCode, Supplier<PO> defaultFunction)	按字段等值返回PO。先调用兜底，仍缺失才抛指定消息异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getVoByExtractor(SFunction<PO,T> keyExtractor, T value)	按字段等值返回VO。缺失抛默认业务异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getVoByExtractor(SFunction<PO,T> keyExtractor, T value, ResponseMessage responseCode)	按字段等值返回VO。缺失抛指定消息的业务异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getVoByExtractor(SFunction<PO,T> keyExtractor, T value, Supplier<PO> defaultFunction)	按字段等值返回VO。先调用兜底，仍缺失才抛默认异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getVoByExtractor(SFunction<PO,T> keyExtractor, T value, ResponseMessage responseCode, Supplier<PO> defaultFunction)	按字段等值返回VO。先调用兜底，仍缺失才抛指定消息异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getPoByWrapper(LambdaQueryWrapper<PO> wrapper)	按Wrapper 条件返回PO。缺失抛默认业务异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getPoByWrapper(LambdaQueryWrapper<PO> wrapper, ResponseMessage responseCode)	按Wrapper 条件返回PO。缺失抛指定消息的业务异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getPoByWrapper(LambdaQueryWrapper<PO> wrapper, Supplier<PO> defaultFunction)	按Wrapper 条件返回PO。先调用兜底，仍缺失才抛默认异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getPoByWrapper(LambdaQueryWrapper<PO> wrapper, ResponseMessage responseCode, Supplier<PO> defaultFunction)	按Wrapper 条件返回PO。先调用兜底，仍缺失才抛指定消息异常。	不检查目标数据属于当前用户。命中可能在查询层和必取层各执行一次 afterGetPo，Hook 应可重复执行。
getVoByWrapper(LambdaQueryWrapper<PO> wrapper)	按Wrapper 条件返回VO。缺失抛默认业务异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getVoByWrapper(LambdaQueryWrapper<PO> wrapper, ResponseMessage responseCode)	按Wrapper 条件返回VO。缺失抛指定消息的业务异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getVoByWrapper(LambdaQueryWrapper<PO> wrapper, Supplier<PO> defaultFunction)	按Wrapper 条件返回VO。先调用兜底，仍缺失才抛默认异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。
getVoByWrapper(LambdaQueryWrapper<PO> wrapper, ResponseMessage responseCode, Supplier<PO> defaultFunction)	按Wrapper 条件返回VO。先调用兜底，仍缺失才抛指定消息异常。	不检查目标数据属于当前用户。最终调用 afterGetVo；不是 afterQueryVo。

同一个业务应按“缺失是否正常”选择 query 或 get。下面使用已接入下载中心的 DownloadCenterService downloads；id、currentUserId 为调用方已经取得的可信值：

var optional = downloads.queryVoById(id); // 数据缺失时 null，适合后台探查
var required = downloads.getVoByIdAndUserId(id, currentUserId);
// App 详情应使用带归属条件的业务入口；通用 getVoById 不限制用户。

BaseListService

源码：BaseListService；实现：AbstractBaseService。

列表方法不自动分页；Query 与 Wrapper 重载的 Hook 行为不同。分页实现依赖 PageHelper 拦截紧随其后的查询，不能把同一个 Query 共享给并发任务。

方法 / 重载	用途、参数与返回值	注意事项
listPo()	使用 defaultQuery 返回 PO 列表。	全量查询，不保证业务用户隔离。
listPoByQuery(QUERY query)	通过业务 lambdaQueryWrapper(query) 返回 PO 列表。	null Query 使用无参 Wrapper，可能扩大查询范围。
listPoByWrapper(LambdaQueryWrapper<PO> wrapper)	直接 mapper.selectList，返回 PO 列表。	不调用 afterList，也不自动追加 Query 子类的筛选条件。
listAllVo()	使用 defaultQuery 转 VO 并执行 afterList。	全量加载，避免无界数据集。
listAllVo(QUERY query)	PO 列表转 VO，再执行 afterList。	业务 afterList 可能补查关联表。
listAllVo(LambdaQueryWrapper<PO> wrapper)	按 Wrapper 查询并转换 VO。	这个重载不执行 afterList，关联信息可能与 Query 重载不同。
listAllMapVo()	使用 defaultQuery 返回 MAP 列表。	不执行 VO 的 afterList。
listAllMapVo(QUERY query)	按 Query 返回 MAP 列表。	MAP 构造器需接收对应 PO。
listAllMapVo(LambdaQueryWrapper<PO> wrapper)	按 Wrapper 返回 MAP 列表。	不自动添加子类 Query 条件。
listAllEntity(Function<PO,T> converter)	使用 defaultQuery 并按 converter 转为自定义结果。	converter=null 时仍先查询，再返回空列表。
listAllEntity(QUERY query, Function<PO,T> converter)	查询 PO 后逐项转换，返回 List<T>。	不执行 afterList；转换异常向外传播。
listAllEntity(LambdaQueryWrapper<PO> wrapper, Function<PO,T> converter)	Wrapper 查询后转换。	空结果或 converter=null 返回 List.of()。
listPoByIdList(Collection<Long> idList)	按主键集合返回 PO；null/空集合返回空列表。	不保证结果顺序与输入一致；不存在的 ID 不产生占位。
mapPoByIdList(Collection<Long> idList)	查询后按 PO.id 建 Map<Long,PO>。	不应假设所有请求 ID 都有值。
countByWrapper()	使用 defaultQuery 统计 long 数量。	不会返回分页数据。
countByWrapper(QUERY query)	用业务 Query Wrapper 统计。	应传有效 Query，不能将 listPoByQuery 的 null 兜底推广到此。
countByWrapper(LambdaQueryWrapper<PO> wrapper)	直接按 Wrapper 统计。	不补充子类 Query 的业务范围。
page()	默认 Query 分页，返回 PageModel<VO>。	默认页码/大小以 Query 配置为准。
page(QUERY query)	先 query.page()，再 listAllVo(query)，返回分页信息与 VO。	Query 非 null；关联补查可能影响分页，见查询与分页页。
pageForComplex(QUERY query)	先分页查 ID，再将 ID 写回 query.idList，查完整列表并执行 afterList。	需实现 mapper.listIds/listByIds；会修改传入 Query，不能复用作其他请求。
afterList(List<VO> list)	列表结果扩展，默认原样返回。	只有实际调用此 Hook 的路径才生效；不用于副作用写入。
countEqual(SFunction<PO,R> keyExtractor, R value)	单字段等值统计，返回 Long。	不继承业务 Query 筛选。
listEqual(SFunction<PO,R> keyExtractor, R value)	单字段等值查询，返回 PO 列表。	无分页和 afterList。
countLike(SFunction<PO,R> keyExtractor, R value)	单字段 LIKE 统计。	匹配与转义受 SQL 实现影响，不是 Java 正则。
listLike(SFunction<PO,R> keyExtractor, R value)	单字段 LIKE 查询 PO。	可能扩大扫描范围，确保查询字段与索引适用。

BaseAddService

源码：BaseAddService；实现：AbstractBaseService。

新增入口将写入操作与 beforeAdd/afterAdd 编排连接。批量入口委托 MapperUtil，默认分组大小 1000；当前 MapperUtil 未消费惰性分组结果，实际未触发数据库写入，不能视为可用的批量保存实现。

方法 / 重载	用途、参数与返回值	注意事项
addByPo(PO po)	beforeAdd → mapper.insert → toVo → afterAdd，返回 VO。	无 DTO 校验；数据库回填主键之外的默认值不保证反映到 VO。
addByDto(DTO dto)	dto.toPo() 后委托 addByPo。	dto 不能 null；不会自动调用 dto.check()。
addBatchByPoList(List<PO> poList)	批量 beforeAdd → MapperUtil → 逐项 toVo/afterAdd，返回 VO 列表。	当前 MapperUtil 未执行分组回调，可能没有插入却返回 VO 并执行后置 Hook；修正后仍需事务控制。
addBatchByDtoList(List<DTO> dtoList)	逐 DTO 转 PO 再批量新增；null/空列表直接返回空。	非空列表中的 null 元素会失败。

BaseUpdateService

源码：BaseUpdateService；实现：AbstractBaseService。

更新方法不自动验证归属。更新策略取决于 DTO.toPo(oldPo)、MyBatis 字段策略与子类 Hook。

方法 / 重载	用途、参数与返回值	注意事项
updateByPo(PO po)	beforeUpdate → updateById → toVo → afterUpdate，返回 VO。	没有检查更新行数；返回 VO 不等于一定更新成功。
updateByDto(Long id, DTO dto)	先 getPoById 必取旧对象，再 dto.toPo(oldPo) 合并，委托 updateByPo。	不存在抛异常；字段能否清空需看 DTO 与 Mapper 策略。
updateBatchByPoList(List<PO> poList)	逐项 beforeUpdate 后委托 MapperUtil，返回 afterUpdate 的 VO 列表。	当前分组回调未执行，不能以返回 VO 确认更新；也无全批自动事务。
updateByWrapper(LambdaUpdateWrapper<PO> wrapper)	直接 mapper.update(null, wrapper)，返回 void。	绕过 beforeUpdate/afterUpdate；条件空可能影响大量记录。

BaseDeleteService

源码：BaseDeleteService；实现：AbstractBaseService。

默认删除只委托 Mapper；逻辑删还是物理删取决于 PO 和 Mapper。AbstractBaseService 不自动调用 beforeDelete/afterDelete，子类必须显式编排。

方法 / 重载	用途、参数与返回值	注意事项
deleteById(Long id)	删除主键记录，返回 void。	不保证存在、不自动清理关联表。
deleteByIdList(Collection<Long> idList)	批量按主键删，null/空集合无操作。	绕过子类单条 deleteById 的规则。
deleteByFkId(SFunction<PO,Long> keyExtractor, Long fkId)	按指定外键等值删除。	不调用逐行删除 Hook；调用前限定归属。
deleteByFkIdList(SFunction<PO,Long> keyExtractor, Collection<Long> fkIdList)	按外键集合批量删，null/空集合无操作。	返回 void，不提供删除数量。

BaseAdvanceService

源码：BaseAdvanceService；实现：AbstractBaseService。

通用二值状态操作，以实体 getter/setter 指定目标属性。

方法 / 重载	用途、参数与返回值	注意事项
updateSwitchStatus(Long id, Function<PO,Integer> get, BiConsumer<PO,Integer> set)	必取 PO，把原值 1 切成 0，其他非 null 值切成 1。	原值 null 抛业务异常；并发读改写可能丢更新。
updateSwitchStatus(Long id, Integer switchStatus, Function<PO,Integer> get, BiConsumer<PO,Integer> set)	switchStatus=null 时切换；明确传值时仅 1 映射为 1，其他映射为 0。	直接 Mapper 更新，不走 beforeUpdate/afterUpdate。

AbstractBaseHook

源码：AbstractBaseHook。

在构造时从直接父类解析六个泛型参数，寻找 PO/QUERY 的 public 无参构造及 VO/MAP 的 public PO 构造。中间泛型基类、错误参数类型或缺少构造器会导致初始化或首次转换失败。

方法 / 重载	用途、参数与返回值	注意事项
AbstractBaseHook()	解析泛型并缓存构造器。	部分查找失败只写日志，不能把应用启动成功等同于转换已可用。
toVo(PO po)	用 VO(PO) 构造 VO。	先检查构造器，再检查 po=null；缺构造器时即使 po=null 也会抛异常。
toMapVo(PO po)	用 MAP(PO) 构造简要模型。	构造器异常包装为 MAP_CONSTRUCTOR_ERROR。
newPoInstance()	用 PO 无参构造新实例。	缺少或执行失败抛 PO_CONSTRUCTOR_ERROR。
newQueryInstance()	用 QUERY 无参构造新条件。	失败抛 QUERY_CONSTRUCTOR_ERROR。
getServiceModuleName()	读取服务类 @ServiceInfo.name 并按类名缓存。	没有注解返回 null；用于缺失对象等错误消息，非业务鉴权模块推导。

AbstractBaseService 中全部直接声明的方法已在上面的接口条目展开；实现的 countEqual/listEqual/countLike/listLike、queryPoById/queryPoByWrapper、page/pageForComplex 等可通过类源码查看具体分支。getPoClass() 为 Lombok 生成访问器，返回解析得到的 PO Class，不修改类型绑定。

MapperUtil

源码：MapperUtil。

当前代码调用 ListUtil.groupList(list,length,fun) 后忽略返回值。该重载只有读取结果分组时才执行 fun，因此下面四项方法实际不触发 insertBatch/updateByIdBatch。mapper 和列表非 null，length 必须为正；参数合法不等于发生了数据库写入。

方法 / 重载	用途、参数与返回值	注意事项
batchInsert(BaseMapper<T> mapper, List<T> sourceList)	以 1000 为 length 委托三参数 batchInsert。	当前不会调用 Mapper；不等价于逐条 Service.addByPo。
batchInsert(BaseMapper<T> mapper, List<T> sourceList, int length)	创建自定义 length 的惰性分组，随后直接返回。	当前未遍历分组，不执行插入；实现修正后还需明确批次事务。
updateByIdBatch(BaseMapper<T> mapper, List<T> sourceList)	以 1000 为 length 委托三参数 updateByIdBatch。	当前不会调用 Mapper；此工具也不执行 Service 更新 Hook。
updateByIdBatch(BaseMapper<T> mapper, List<T> sourceList, int length)	创建更新回调的惰性分组，返回 void。	当前不执行更新；添加事务不能修复未执行回调的问题。

BaseImportService

源码：BaseImportService。

导入扩展入口，目前仅有占位默认实现。

方法 / 重载	用途、参数与返回值	注意事项
importPo(DTO dto, MultipartFile file)	默认返回 new UploadModel()。	未解析文件、未导入数据；使用前由业务覆盖。

BaseExportService

源码：BaseExportService。

导出扩展入口，目前未提供 Word/Excel 的通用导出实现。

方法 / 重载	用途、参数与返回值	注意事项
exportToWord(QUERY query)	默认返回空 UploadModel。	不能据方法名宣称生成了 Word 文件。
exportToExcel(QUERY query)	默认返回空 UploadModel。	应用实现查询、模板、文件生成与错误处理后才能开放接口。

扩展 Hook 的调用边界

新增、更新、查询、必取、列表各自有独立 Hook；不要让 Hook 再调用相同 Service 入口形成递归。删除的单条与批量行为也不同，业务校验不能只放在默认不会执行的 beforeDelete 中。具体执行顺序和扩展例子见使用与配置及关系绑定与任务。