下面直接续写下一篇，延续前文风格，作为可直接发布的教程稿。

tio-boot + jOOQ 的审计字段、乐观锁、数据权限与企业级 Repository 设计

在前几篇中，我们已经逐步完成了：

  • tio-boot + jOOQ 基础整合
  • 事务管理
  • Codegen 强类型升级
  • Record / POJO CRUD
  • 批量、分页、动态 SQL
  • PostgreSQL UPSERT、returning
  • 多表查询、DTO 投影、聚合统计
  • JSONB、窗口函数、CTE 与 PostgreSQL 高级 SQL

到这里，已经不只是“能写数据库代码”，而是已经具备了：

一套现代 Java 项目中可落地的、强类型的、以 SQL 为中心的数据访问体系。

但如果要继续走向企业级落地，还会遇到几个非常核心的问题：

  • 如何统一维护 created_at / updated_at / created_by / updated_by
  • 如何避免“后写覆盖前写”的并发更新问题
  • 如何让数据权限在 DAO / Repository 层自然生效
  • 如何避免 DAO 越写越散，最终失控
  • 如何把 jOOQ 查询能力，组织成一套可维护的 Repository 体系

本文就围绕这些问题，系统讲清：

  • 审计字段设计
  • 自动填充策略
  • 乐观锁实现
  • 数据权限条件注入
  • Repository 分层设计
  • 在 tio-boot + jOOQ 中的企业级落地建议

一、为什么这一篇是“工程治理篇”

前面几篇偏重的是：

  • 怎么查
  • 怎么写
  • 怎么做复杂 SQL

而这一篇更偏重：

  • 怎么让整个团队长期维护得住
  • 怎么让数据访问层具备统一规范
  • 怎么让通用能力沉淀下来

也就是说，这一篇讨论的是：

从“会用 jOOQ”走向“用 jOOQ 建立企业级数据访问治理能力”。

在真实项目里，很多问题并不是 SQL 写不出来，而是：

  • 每个人都在自己处理 updated_at
  • 每个人都在自己决定是否校验版本号
  • 每个人都在自己拼数据权限 where 条件
  • DAO / Service 边界越来越模糊
  • 通用方法没人收敛，重复代码越来越多

所以这一篇的目标不是“秀 SQL 技巧”，而是回答：

怎样用 tio-boot + jOOQ，建立一个可持续演进的数据访问层。

二、审计字段：企业项目里的基础设施字段

所谓审计字段，通常指的是一类“记录数据是谁创建、何时创建、何时修改”的通用字段。

最常见的是：

  • created_at
  • updated_at
  • created_by
  • updated_by

有时还会带：

  • deleted
  • deleted_at
  • deleted_by
  • version

这些字段几乎在所有中后台系统里都会出现。

2.1 推荐表结构

以 system_admin 为例，可以扩展为：

ALTER TABLE system_admin
ADD COLUMN created_at TIMESTAMP NOT NULL DEFAULT now(),
ADD COLUMN updated_at TIMESTAMP NOT NULL DEFAULT now(),
ADD COLUMN created_by BIGINT,
ADD COLUMN updated_by BIGINT,
ADD COLUMN version INT NOT NULL DEFAULT 0,
ADD COLUMN deleted BOOLEAN NOT NULL DEFAULT false;

这几个字段各自的职责很清晰：

  • created_at：创建时间
  • updated_at：最后修改时间
  • created_by：创建人
  • updated_by：最后修改人
  • version：乐观锁版本号
  • deleted：逻辑删除标记

如果项目体量更大，也可以继续增加：

  • tenant_id
  • org_id

用于租户隔离或组织隔离。

2.2 为什么不建议每张表“临时想起再加”

推荐一开始就把这些字段作为统一规范。

原因很简单：

1. 通用能力才能沉淀

如果每张表设计都不一致，就很难写统一的 Repository 能力。

2. 后面再补成本更高

尤其是已经上线的表，补审计字段通常意味着：

  • DDL 变更
  • 老数据回填
  • 业务代码联动修改

3. 企业治理依赖统一字段

例如：

  • 全局逻辑删除
  • 全局数据权限
  • 全局更新时间维护
  • 通用审计日志

都依赖这些基础字段尽量统一。

三、审计字段怎么维护

审计字段最大的实践问题不在于“有没有”，而在于：

谁来填，什么时候填，怎样保证不遗漏。

一般有三种思路：

  1. 业务代码手工填
  2. Repository 层统一填
  3. 数据库触发器填

在 tio-boot + jOOQ 体系里，通常最推荐的是：

Repository 层统一填，必要时再辅以数据库默认值。

3.1 数据库默认值只能解决一部分问题

例如：

created_at TIMESTAMP NOT NULL DEFAULT now(),
updated_at TIMESTAMP NOT NULL DEFAULT now()

这只能保证：

  • 插入时有默认时间

但不能很好解决：

  • 更新时自动改 updated_at
  • 自动填 created_by / updated_by
  • 应用层对修改人上下文的感知

所以数据库默认值可以保底，但不能替代应用层审计策略。

3.2 手工填为什么容易失控

例如每个 DAO 都这样写：

dsl.update(SYSTEM_ADMIN)
   .set(SYSTEM_ADMIN.PASSWORD, newPassword)
   .set(SYSTEM_ADMIN.UPDATED_AT, LocalDateTime.now())
   .set(SYSTEM_ADMIN.UPDATED_BY, userId)
   .where(...)
   .execute();

看起来没问题，但时间一长就会出现：

  • 有些地方忘了加 updated_at
  • 有些地方只改了 updated_at 没改 updated_by
  • 有些地方插入忘了设置 created_by
  • 同类逻辑在几十个 DAO 里重复

所以更好的思路是：

把审计字段维护从“业务细节”提升为“基础设施能力”。

四、定义统一的审计上下文

如果要统一填 created_by / updated_by，首先就要有一个地方能拿到“当前操作人”。

这通常可以抽象成一个上下文对象。

4.1 审计上下文模型

package demo.jooq.audit;

public class AuditContext {

  private static final ThreadLocal<Long> CURRENT_USER = new ThreadLocal<>();

  public static void setUserId(Long userId) {
    CURRENT_USER.set(userId);
  }

  public static Long getUserId() {
    return CURRENT_USER.get();
  }

  public static void clear() {
    CURRENT_USER.remove();
  }
}

它和前面事务里的 TransactionContext 思路类似：

  • 当前线程保存当前操作人
  • DAO / Repository 可以在底层读取

4.2 谁来设置 AuditContext

通常在：

  • 登录态请求入口
  • 鉴权拦截器
  • 网关透传后进入应用时

把当前用户 id 放进去。

例如：

AuditContext.setUserId(loginUserId);

请求结束后记得清理：

AuditContext.clear();

这样 Repository 层就不用每次都把 userId 作为参数一路传下去了。

当然，如果你更偏向显式传参，也可以不使用 ThreadLocal，但对于统一审计能力来说，线程上下文通常更自然。

五、抽象一个 BaseRepository

这是企业级 Repository 设计的核心。

目标不是做成“万能 ORM”，而是沉淀那些：

  • 所有表都需要的通用能力
  • 可以强约束的底层规则
  • 能减少重复劳动的写法

例如：

  • 获取当前 DSLContext
  • 自动维护审计字段
  • 统一逻辑删除条件
  • 统一数据权限条件
  • 统一分页辅助
  • 统一存在性判断

5.1 一个基础 BaseRepository 雏形

package demo.jooq.repository;

import org.jooq.Condition;
import org.jooq.DSLContext;
import org.jooq.Table;
import org.jooq.impl.DSL;

import nexus.io.annotation.Inject;

import demo.jooq.tx.TransactionContext;

public abstract class BaseRepository {

  @Inject
  private DSLContext dsl;

  protected DSLContext ctx() {
    DSLContext txDsl = TransactionContext.get();
    return txDsl != null ? txDsl : dsl;
  }

  protected Condition noCondition() {
    return DSL.trueCondition();
  }

  protected int offset(int pageNo, int pageSize) {
    return (pageNo - 1) * pageSize;
  }

  protected boolean validPageNo(Integer pageNo) {
    return pageNo != null && pageNo > 0;
  }

  protected boolean validPageSize(Integer pageSize) {
    return pageSize != null && pageSize > 0;
  }

  protected int safePageNo(Integer pageNo) {
    return validPageNo(pageNo) ? pageNo : 1;
  }

  protected int safePageSize(Integer pageSize) {
    return validPageSize(pageSize) ? pageSize : 10;
  }

  protected <R extends org.jooq.Record> boolean exists(Table<R> table, Condition condition) {
    return ctx().fetchExists(
        ctx().selectOne().from(table).where(condition)
    );
  }
}

这个基类还很轻，但已经把最基础的公共能力抽出来了。

六、审计字段自动填充：推荐做法

接下来真正进入“自动审计填充”。

这里不建议做得过于魔法化，而推荐：

在 Repository 层提供统一辅助方法，显式但不重复。

6.1 统一创建时间与修改时间

例如定义一个审计辅助类：

package demo.jooq.audit;

import java.time.LocalDateTime;

public class AuditFields {

  public static LocalDateTime now() {
    return LocalDateTime.now();
  }

  public static Long currentUserId() {
    return AuditContext.getUserId();
  }
}

然后在 Repository 中统一使用。

6.2 插入时填充

假设 Codegen 后表字段包括：

  • CREATED_AT
  • UPDATED_AT
  • CREATED_BY
  • UPDATED_BY

那么插入时可以统一写成：

public Integer insertAdmin(String loginName, String password) {
  LocalDateTime now = AuditFields.now();
  Long userId = AuditFields.currentUserId();

  return ctx()
      .insertInto(SYSTEM_ADMIN)
      .set(SYSTEM_ADMIN.LOGIN_NAME, loginName)
      .set(SYSTEM_ADMIN.PASSWORD, password)
      .set(SYSTEM_ADMIN.CREATED_AT, now)
      .set(SYSTEM_ADMIN.UPDATED_AT, now)
      .set(SYSTEM_ADMIN.CREATED_BY, userId)
      .set(SYSTEM_ADMIN.UPDATED_BY, userId)
      .returning(SYSTEM_ADMIN.ID)
      .fetchOne(SYSTEM_ADMIN.ID);
}

这仍然是显式的，但已经具备统一语义。

6.3 更新时填充

public int updatePassword(Integer id, String newPassword) {
  return ctx()
      .update(SYSTEM_ADMIN)
      .set(SYSTEM_ADMIN.PASSWORD, newPassword)
      .set(SYSTEM_ADMIN.UPDATED_AT, AuditFields.now())
      .set(SYSTEM_ADMIN.UPDATED_BY, AuditFields.currentUserId())
      .where(SYSTEM_ADMIN.ID.eq(id))
      .and(SYSTEM_ADMIN.DELETED.eq(false))
      .execute();
}

这里已经出现两个企业级习惯：

  • 改数据就更新 updated_at / updated_by
  • 默认只操作未删除数据

6.4 再往前一步：抽辅助方法

为了进一步减少重复，可以抽成：

protected <T> T currentTimestamp() {
  return (T) java.time.LocalDateTime.now();
}

protected Long currentUserId() {
  return AuditContext.getUserId();
}

然后在 Repository 里统一使用。

虽然 jOOQ 也支持 currentTimestamp() SQL 函数，但企业项目里通常会权衡：

  • 用数据库时间
  • 还是应用时间

两者都可以，关键是全项目保持一致。

七、逻辑删除：不要真的 delete

企业项目里，很多数据删除并不应该直接物理删除。

更常见的是：

  • deleted = true
  • 必要时记录 deleted_at / deleted_by

7.1 推荐逻辑删除字段

如果要更完整，可以是：

ALTER TABLE system_admin
ADD COLUMN deleted BOOLEAN NOT NULL DEFAULT false,
ADD COLUMN deleted_at TIMESTAMP,
ADD COLUMN deleted_by BIGINT;

7.2 逻辑删除写法

public int softDeleteById(Integer id) {
  return ctx()
      .update(SYSTEM_ADMIN)
      .set(SYSTEM_ADMIN.DELETED, true)
      .set(SYSTEM_ADMIN.UPDATED_AT, AuditFields.now())
      .set(SYSTEM_ADMIN.UPDATED_BY, AuditFields.currentUserId())
      .where(SYSTEM_ADMIN.ID.eq(id))
      .and(SYSTEM_ADMIN.DELETED.eq(false))
      .execute();
}

如果有 deleted_at / deleted_by，也一起填上。

7.3 所有查询默认过滤已删除数据

这一步非常关键。

否则逻辑删除就形同虚设。

推荐在 Repository 层沉淀一个通用条件：

protected Condition notDeleted(org.jooq.TableField<?, Boolean> deletedField) {
  return deletedField.eq(false);
}

然后每次查询：

.where(notDeleted(SYSTEM_ADMIN.DELETED))

进一步，还可以在具体 Repository 中封装一个更语义化的方法。

八、乐观锁：避免“后写覆盖前写”

这是企业项目里最容易被忽视，但又极其重要的一部分。

典型问题：

  • A 用户查出一条记录
  • B 用户也查出同一条记录
  • A 修改并提交
  • B 也修改并提交
  • B 把 A 的更新覆盖了

如果没有并发控制，这种“最后写入者覆盖前者”的问题非常常见。

乐观锁的核心思路是：

更新时带上版本条件，只有版本没变时才允许更新。

8.1 推荐字段：version

ALTER TABLE system_admin
ADD COLUMN version INT NOT NULL DEFAULT 0;

8.2 查询时带出 version

例如查详情时返回：

  • id
  • login_name
  • password
  • version

前端或调用方后续更新时，把 version 一起带回来。

8.3 更新时校验 version

public boolean updatePasswordWithVersion(Integer id, String newPassword, Integer version) {
  int rows = ctx()
      .update(SYSTEM_ADMIN)
      .set(SYSTEM_ADMIN.PASSWORD, newPassword)
      .set(SYSTEM_ADMIN.VERSION, SYSTEM_ADMIN.VERSION.plus(1))
      .set(SYSTEM_ADMIN.UPDATED_AT, AuditFields.now())
      .set(SYSTEM_ADMIN.UPDATED_BY, AuditFields.currentUserId())
      .where(SYSTEM_ADMIN.ID.eq(id))
      .and(SYSTEM_ADMIN.VERSION.eq(version))
      .and(SYSTEM_ADMIN.DELETED.eq(false))
      .execute();

  return rows == 1;
}

这段逻辑的关键点

只有当数据库里当前 version 仍然等于调用方传入的 version 时，更新才会成功。

如果返回 0 行，说明：

  • 数据不存在
  • 已被删除
  • 或者 version 已变化，发生了并发冲突

8.4 乐观锁失败后怎么处理

通常有三种常见策略：

1. 直接提示冲突

例如：

  • “数据已被其他人修改，请刷新后重试”

这是最推荐、也最清晰的方式。

2. 自动重试

适合一些幂等场景，但不能滥用。

3. 后写覆盖前写

这本质上就放弃了乐观锁，不推荐。

8.5 为什么企业项目更推荐乐观锁而不是悲观锁

悲观锁例如：

  • select ... for update

它很强，但会带来：

  • 锁等待
  • 死锁风险
  • 吞吐下降

所以在大部分中后台管理系统里：

优先使用乐观锁，只有少数强一致扣减类场景再考虑悲观锁。

九、数据权限：不要让每个 DAO 自己拼

企业系统里经常有数据权限要求，例如：

  • 只能看自己创建的数据
  • 只能看本部门数据
  • 只能看自己租户的数据
  • 超级管理员可以看全部

最糟糕的做法就是：

每个 DAO 方法都手工写一遍 if/else。

这样很快就会失控。

所以推荐把数据权限提升为：

Repository 层统一条件构造能力

9.1 定义数据权限上下文

package demo.jooq.security;

public class DataPermissionContext {

  private static final ThreadLocal<Long> CURRENT_USER_ID = new ThreadLocal<>();
  private static final ThreadLocal<Long> CURRENT_DEPT_ID = new ThreadLocal<>();
  private static final ThreadLocal<Boolean> IS_SUPER_ADMIN = new ThreadLocal<>();

  public static void setUserId(Long userId) {
    CURRENT_USER_ID.set(userId);
  }

  public static Long getUserId() {
    return CURRENT_USER_ID.get();
  }

  public static void setDeptId(Long deptId) {
    CURRENT_DEPT_ID.set(deptId);
  }

  public static Long getDeptId() {
    return CURRENT_DEPT_ID.get();
  }

  public static void setSuperAdmin(Boolean superAdmin) {
    IS_SUPER_ADMIN.set(superAdmin);
  }

  public static Boolean isSuperAdmin() {
    return Boolean.TRUE.equals(IS_SUPER_ADMIN.get());
  }

  public static void clear() {
    CURRENT_USER_ID.remove();
    CURRENT_DEPT_ID.remove();
    IS_SUPER_ADMIN.remove();
  }
}

9.2 在 BaseRepository 提供通用权限条件

例如先做最简单的一种： 非超级管理员只能看自己创建的数据。

protected Condition creatorPermission(org.jooq.TableField<?, Long> createdByField) {
  if (demo.jooq.security.DataPermissionContext.isSuperAdmin()) {
    return DSL.trueCondition();
  }

  Long userId = demo.jooq.security.DataPermissionContext.getUserId();
  if (userId == null) {
    return DSL.falseCondition();
  }

  return createdByField.eq(userId);
}

这样具体 Repository 查询时只需要：

.where(notDeleted(SYSTEM_ADMIN.DELETED))
.and(creatorPermission(SYSTEM_ADMIN.CREATED_BY))

9.3 部门级权限

如果表上有 dept_id 字段，可以继续抽：

protected Condition deptPermission(org.jooq.TableField<?, Long> deptIdField) {
  if (demo.jooq.security.DataPermissionContext.isSuperAdmin()) {
    return DSL.trueCondition();
  }

  Long deptId = demo.jooq.security.DataPermissionContext.getDeptId();
  if (deptId == null) {
    return DSL.falseCondition();
  }

  return deptIdField.eq(deptId);
}

然后查询时统一拼进去。

9.4 数据权限为什么必须下沉到 Repository 层

因为如果放在 Service 层，最终很容易发生：

  • 某个 Service 忘了加
  • 某个新接口漏掉了
  • 某个批量查询绕过了权限条件

而 Repository 是所有数据查询的底层入口之一。

把权限条件尽量下沉，至少能降低遗漏概率。

当然，极端复杂的数据权限仍可能需要：

  • Service 层参与
  • 更上层的授权模型
  • SQL 视图
  • 行级安全策略

但 Repository 层统一条件仍然是一个非常实用的第一步。

十、企业级 Repository 应该长什么样

这部分很关键。

很多项目后期出问题，不是因为 jOOQ 不够强，而是 Repository 设计失控了。

推荐的原则是：

Repository 不要做万能基类，也不要做纯 SQL 垃圾桶。

10.1 推荐分层

BaseRepository

只放真正稳定的公共基础能力：

  • 获取 DSLContext
  • 分页辅助
  • 审计辅助
  • 逻辑删除条件
  • 数据权限条件
  • exists / count / offset 等通用方法

XxxRepository

只负责某一聚合或某一表域：

  • SystemAdminRepository
  • UserProfileRepository
  • OrderRepository

Service

负责：

  • 事务边界
  • 业务组合
  • 乐观锁冲突后的业务处理
  • 多 Repository 协调

10.2 不要做过度泛型化的万能 CRUD 基类

很多人会想做一个类似：

GenericRepository<T, ID>

然后自动推导一切。

看起来高级，但通常会越来越痛苦，因为真实项目里的查询并不只是：

  • findById
  • save
  • delete

更多是：

  • 多表 join
  • DTO 投影
  • 动态条件
  • 数据权限
  • 分页统计
  • PostgreSQL 方言能力

这些都很难优雅地塞进一个万能泛型仓库。

所以更推荐：

基础能力适度抽象，业务查询保持显式。

10.3 Repository 命名也要有边界感

例如：

  • findById
  • findDetailById
  • searchPage
  • existsByLoginName
  • updatePasswordWithVersion
  • softDeleteById

这些命名都很清楚。

不推荐那种：

  • query1
  • query2
  • saveData
  • handleAdmin

因为 Repository 层的名字本身就应该表达 SQL/数据行为。

十一、一个完整的企业级 Repository 示例

下面给出一个比较完整的 SystemAdminRepository 示例，把本文几个核心点串起来。

package demo.jooq.repository;

import static demo.jooq.gen.tables.SystemAdmin.SYSTEM_ADMIN;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Optional;

import org.jooq.Condition;

import demo.jooq.audit.AuditContext;
import demo.jooq.gen.tables.pojos.SystemAdmin;
import demo.jooq.model.PageResult;
import demo.jooq.model.SystemAdminQuery;
import demo.jooq.security.DataPermissionContext;
import org.jooq.impl.DSL;

public class SystemAdminRepository extends BaseRepository {

  protected LocalDateTime now() {
    return LocalDateTime.now();
  }

  protected Long currentUserId() {
    return AuditContext.getUserId();
  }

  protected Condition notDeleted() {
    return SYSTEM_ADMIN.DELETED.eq(false);
  }

  protected Condition creatorPermission() {
    if (DataPermissionContext.isSuperAdmin()) {
      return DSL.trueCondition();
    }
    Long userId = DataPermissionContext.getUserId();
    if (userId == null) {
      return DSL.falseCondition();
    }
    return SYSTEM_ADMIN.CREATED_BY.eq(userId);
  }

  public Integer insert(SystemAdmin pojo) {
    LocalDateTime now = now();
    Long userId = currentUserId();

    return ctx()
        .insertInto(SYSTEM_ADMIN)
        .set(SYSTEM_ADMIN.LOGIN_NAME, pojo.getLoginName())
        .set(SYSTEM_ADMIN.PASSWORD, pojo.getPassword())
        .set(SYSTEM_ADMIN.CREATED_AT, now)
        .set(SYSTEM_ADMIN.UPDATED_AT, now)
        .set(SYSTEM_ADMIN.CREATED_BY, userId)
        .set(SYSTEM_ADMIN.UPDATED_BY, userId)
        .set(SYSTEM_ADMIN.VERSION, 0)
        .set(SYSTEM_ADMIN.DELETED, false)
        .returning(SYSTEM_ADMIN.ID)
        .fetchOne(SYSTEM_ADMIN.ID);
  }

  public Optional<SystemAdmin> findById(Integer id) {
    return ctx()
        .selectFrom(SYSTEM_ADMIN)
        .where(SYSTEM_ADMIN.ID.eq(id))
        .and(notDeleted())
        .and(creatorPermission())
        .fetchOptionalInto(SystemAdmin.class);
  }

  public boolean existsByLoginName(String loginName) {
    return exists(
        SYSTEM_ADMIN,
        SYSTEM_ADMIN.LOGIN_NAME.eq(loginName)
            .and(notDeleted())
            .and(creatorPermission())
    );
  }

  public boolean updatePasswordWithVersion(Integer id, String password, Integer version) {
    int rows = ctx()
        .update(SYSTEM_ADMIN)
        .set(SYSTEM_ADMIN.PASSWORD, password)
        .set(SYSTEM_ADMIN.VERSION, SYSTEM_ADMIN.VERSION.plus(1))
        .set(SYSTEM_ADMIN.UPDATED_AT, now())
        .set(SYSTEM_ADMIN.UPDATED_BY, currentUserId())
        .where(SYSTEM_ADMIN.ID.eq(id))
        .and(SYSTEM_ADMIN.VERSION.eq(version))
        .and(notDeleted())
        .and(creatorPermission())
        .execute();

    return rows == 1;
  }

  public int softDeleteById(Integer id) {
    return ctx()
        .update(SYSTEM_ADMIN)
        .set(SYSTEM_ADMIN.DELETED, true)
        .set(SYSTEM_ADMIN.UPDATED_AT, now())
        .set(SYSTEM_ADMIN.UPDATED_BY, currentUserId())
        .where(SYSTEM_ADMIN.ID.eq(id))
        .and(notDeleted())
        .and(creatorPermission())
        .execute();
  }

  public PageResult<SystemAdmin> searchPage(SystemAdminQuery query) {
    Condition condition = DSL.trueCondition();

    if (query.getId() != null) {
      condition = condition.and(SYSTEM_ADMIN.ID.eq(query.getId()));
    }

    if (query.getLoginName() != null && !query.getLoginName().isBlank()) {
      condition = condition.and(SYSTEM_ADMIN.LOGIN_NAME.like("%" + query.getLoginName() + "%"));
    }

    condition = condition.and(notDeleted()).and(creatorPermission());

    int pageNo = safePageNo(query.getPageNo());
    int pageSize = safePageSize(query.getPageSize());

    int total = ctx()
        .selectCount()
        .from(SYSTEM_ADMIN)
        .where(condition)
        .fetchOne(0, int.class);

    List<SystemAdmin> list = ctx()
        .selectFrom(SYSTEM_ADMIN)
        .where(condition)
        .orderBy(SYSTEM_ADMIN.ID.desc())
        .limit(pageSize)
        .offset(offset(pageNo, pageSize))
        .fetchInto(SystemAdmin.class);

    return new PageResult<>(pageNo, pageSize, total, list);
  }
}

十二、Service 层如何使用 Repository

到了这一层，Repository 已经具备：

  • 审计字段维护
  • 乐观锁
  • 逻辑删除
  • 数据权限条件

所以 Service 可以更聚焦业务本身。

12.1 示例：修改密码

package demo.jooq.service;

import nexus.io.annotation.Inject;
import demo.jooq.repository.SystemAdminRepository;

public class SystemAdminService {

  @Inject
  private SystemAdminRepository repository;

  public void changePassword(Integer id, String newPassword, Integer version) {
    boolean ok = repository.updatePasswordWithVersion(id, newPassword, version);
    if (!ok) {
      throw new RuntimeException("数据已被修改，请刷新后重试");
    }
  }
}

这里 Service 的职责很清晰：

  • 调用 Repository
  • 处理乐观锁失败的业务语义

而不是自己去拼版本条件。

十三、这套设计的核心收益

如果把这一篇的内容压缩成几个收益点，最关键的是下面这些。

13.1 审计字段不会到处散落

统一在 Repository 层维护后：

  • created_at
  • updated_at
  • created_by
  • updated_by

就不再是每个业务自己记忆的细节。

13.2 乐观锁成为统一能力

而不是每个 Service 自己临时想起：

  • 要不要校验 version
  • 怎么自增 version
  • 冲突时返回什么

13.3 数据权限更不容易漏

Repository 层统一拼权限条件，至少能大幅降低“漏写 where 条件”的风险。

13.4 DAO / Repository 结构会更稳

BaseRepository 负责通用能力，具体 Repository 负责业务 SQL，边界会更清晰。

十四、几个非常容易踩的坑

14.1 不要把所有逻辑都抽成万能基类

如果 BaseRepository 越来越像一个 mini ORM，最后通常会变得：

  • 难理解
  • 难扩展
  • 难调试
  • 泛型爆炸

正确做法是：

只抽稳定公共能力，不抽业务个性。

14.2 数据权限不能只靠前端控制

前端隐藏按钮、隐藏数据，不等于真正的数据权限。

真正的数据权限必须体现在后端查询条件里。

14.3 逻辑删除后一定要统一过滤

如果删的时候用了逻辑删除，但查的时候不统一过滤，最终系统会出现很多“幽灵数据”。

14.4 乐观锁失败是正常业务分支，不是系统异常

不要把它理解成“程序出 bug”。

它是并发场景下很正常的结果，应该给出明确业务提示。

14.5 created_by / updated_by 不要过度依赖手工传参

如果项目已经有统一登录上下文，优先考虑统一审计上下文，不要让每一层都手动传来传去。

十五、本篇总结

这一篇从企业级工程治理角度，补上了 tio-boot + jOOQ 体系中非常关键的一层：

  • 审计字段
  • 自动更新时间与操作人
  • 逻辑删除
  • 乐观锁
  • 数据权限
  • BaseRepository 与具体 Repository 的分层设计

一句话总结：

真正成熟的数据访问层，不只是“SQL 能写出来”，而是“通用规则能沉淀，团队协作能稳定”。

到这里，这套 tio-boot + jOOQ 方案已经不只是“轻量整合示例”，而是逐步具备了企业级可落地的形态：

  • 强类型 SQL
  • 事务边界清晰
  • PostgreSQL 能力充分利用
  • DTO / Repository 分层明确
  • 审计、权限、并发控制可统一治理