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

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 为例，可以扩展为：

sql

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. 企业治理依赖统一字段

例如：

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

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

三、审计字段怎么维护

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

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

一般有三种思路：

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

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

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

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

例如：

sql

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

这只能保证：

插入时有默认时间

但不能很好解决：

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

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

3.2 手工填为什么容易失控

例如每个 DAO 都这样写：

java

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 审计上下文模型

java

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 放进去。

例如：

java

AuditContext.setUserId(loginUserId);

请求结束后记得清理：

java

AuditContext.clear();

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

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

五、抽象一个 BaseRepository

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

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

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

例如：

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

5.1 一个基础 BaseRepository 雏形

java

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 统一创建时间与修改时间

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

java

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

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

java

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 更新时填充

java

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 再往前一步：抽辅助方法

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

java

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 推荐逻辑删除字段

如果要更完整，可以是：

sql

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

7.2 逻辑删除写法

java

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 层沉淀一个通用条件：

java

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

然后每次查询：

java

.where(notDeleted(SYSTEM_ADMIN.DELETED))

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

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

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

典型问题：

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

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

乐观锁的核心思路是：

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

8.1 推荐字段：`version`

sql

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

8.2 查询时带出 version

例如查详情时返回：

id
login_name
password
version

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

8.3 更新时校验 version

java

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 定义数据权限上下文

java

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 提供通用权限条件

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

java

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 查询时只需要：

java

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

9.3 部门级权限

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

java

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 基类

很多人会想做一个类似：

java

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 示例，把本文几个核心点串起来。

java

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 示例：修改密码

java

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 分层明确
审计、权限、并发控制可统一治理

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

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

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

2.1 推荐表结构 ​

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

1. 通用能力才能沉淀 ​

2. 后面再补成本更高 ​

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

三、审计字段怎么维护 ​

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

3.2 手工填为什么容易失控 ​

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

4.1 审计上下文模型 ​

4.2 谁来设置 AuditContext ​

五、抽象一个 BaseRepository ​

5.1 一个基础 BaseRepository 雏形 ​

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

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

6.2 插入时填充 ​

6.3 更新时填充 ​

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

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

7.1 推荐逻辑删除字段 ​

7.2 逻辑删除写法 ​

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

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

8.1 推荐字段：version ​

8.2 查询时带出 version ​

8.3 更新时校验 version ​

这段逻辑的关键点 ​

8.4 乐观锁失败后怎么处理 ​

1. 直接提示冲突 ​

2. 自动重试 ​

3. 后写覆盖前写 ​

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

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

9.1 定义数据权限上下文 ​

9.2 在 BaseRepository 提供通用权限条件 ​

9.3 部门级权限 ​

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

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

10.1 推荐分层 ​

BaseRepository ​

XxxRepository ​

Service ​

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

10.3 Repository 命名也要有边界感 ​

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

十二、Service 层如何使用 Repository ​

12.1 示例：修改密码 ​

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

13.1 审计字段不会到处散落 ​

13.2 乐观锁成为统一能力 ​

13.3 数据权限更不容易漏 ​

13.4 DAO / Repository 结构会更稳 ​

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

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

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

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

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

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

十五、本篇总结 ​

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

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

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

2.1 推荐表结构

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

1. 通用能力才能沉淀

2. 后面再补成本更高

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

三、审计字段怎么维护

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

3.2 手工填为什么容易失控

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

4.1 审计上下文模型

4.2 谁来设置 AuditContext

五、抽象一个 BaseRepository

5.1 一个基础 BaseRepository 雏形

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

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

6.2 插入时填充

6.3 更新时填充

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

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

7.1 推荐逻辑删除字段

7.2 逻辑删除写法

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

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

8.1 推荐字段：`version`

8.2 查询时带出 version

8.3 更新时校验 version

这段逻辑的关键点

8.4 乐观锁失败后怎么处理

1. 直接提示冲突

2. 自动重试

3. 后写覆盖前写

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

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

9.1 定义数据权限上下文

9.2 在 BaseRepository 提供通用权限条件

9.3 部门级权限

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

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

10.1 推荐分层

BaseRepository

XxxRepository

Service

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

10.3 Repository 命名也要有边界感

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

十二、Service 层如何使用 Repository

12.1 示例：修改密码

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

13.1 审计字段不会到处散落

13.2 乐观锁成为统一能力

13.3 数据权限更不容易漏

13.4 DAO / Repository 结构会更稳

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

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

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

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

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

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

十五、本篇总结