罗罗编程学习记录
本页内容 展开查看

06.8.3.1 DSL 查询、事务与连接池

所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.8 Kotlin 后端 / 06.8.3 Exposed 与数据访问

本节要解决的问题

  • Exposed 的 DSL 与 DAO 两种 API 如何定位,表定义、列类型与方言映射怎么写?
  • 查询、写入、批量操作与动态条件在 DSL 中如何表达?
  • 事务、隔离级别、连接池、多数据源与协程事务如何组织,N+1 与慢查询如何治理?

版本前提:Exposed 0.5x / Kotlin 2.x / JDK 17+ / Spring Boot 3.2+;本节聚焦 Exposed 自身机制,JPA 与通用事务原理见 06.2、05 分册。版本敏感项标「待确认」并写验证点。

06.8.3.1-001 Exposed 在 Kotlin 数据访问生态中的定位是什么?

一句话结论

Exposed 是 JetBrains 出品的 Kotlin SQL 工具库,提供类型安全的 DSL 与可选 DAO 层,直接生成并执行 SQL,不是完整 ORM;介于手写 SQL 与 JPA 之间,强调 Kotlin 类型安全与 SQL 可控性。

概念解释

DSL 层用 Kotlin 表达式描述表与查询,编译期检查列引用;DAO 层提供实体对象与关联管理。库不做全自动对象关系映射与一级缓存,结果行按 DSL 列读取或映射为对象。

原理流程

  1. 定义表对象(继承 Table/IdTable)。
  2. DSL 表达式构造查询,编译期校验列类型。
  3. 库生成对应方言 SQL 并执行。
  4. 结果行按列读取映射。

代码或图示

object Users : Table("users") {
    val id = long("id").autoIncrement()
    val name = varchar("name", 64)
}

val rows = Users.selectAll().where { Users.name eq "Ann" }.toList()

常见误区

  • 把 Exposed 当 JPA 使用:没有实体持久化上下文、脏检查与一级缓存。
  • 以为 DSL 屏蔽了 SQL:生成 SQL 仍需理解索引、连接与方言差异。

追问

  • DAO 层解决什么?答:提供实体类、代理关联与 CRUD 样板,DSL 层仍是查询基础;见 DSL/DAO 条目。
  • 官方仓库与文档入口?答:JetBrains/Exposed GitHub 仓库与 Wiki。

06.8.3.1-002 DSL 与 DAO 两种 API 层如何区分?

一句话结论

DSL 是表级函数式查询,返回行集合并按列取值;DAO 是对象级 API,实体类映射表,通过实例方法读写并管理关联;两者可同项目混用,DSL 偏查询编排,DAO 偏实体样板。

概念解释

DSL 直接面向表对象与列表达式,无实体类;DAO 为每张表定义实体类与工厂,实例持有字段值,关联可懒加载。DAO 底层仍使用 DSL 生成 SQL,复杂查询通常回到 DSL 编写。

原理流程

  1. DSL:构造 select/insert 表达式,执行后遍历 Row 取值。
  2. DAO:定义实体类与实体工厂,CRUD 方法操作实例。
  3. 复杂关联与自定义查询用 DSL。
  4. 简单 CRUD 可用 DAO 减少样板。

代码或图示

// DSL:行 + 列
val name = Users.selectAll().first()[Users.name]

// DAO:实体实例(示意)
// val entity = UserEntity.findById(id)

常见误区

  • 项目全量用 DAO 处理复杂报表:关联与聚合查询回到 DSL 更直接。
  • 混淆 Row 与实体实例:两者取值 API 不同。

追问

  • 两种层能共享表定义吗?答:表对象是共同基础,DAO 工厂绑定表定义。
  • 选型建议?答:查询密集型以 DSL 为主,简单增删改可叠加 DAO。

06.8.3.1-003 Exposed 与 JPA、MyBatis 如何对比选型?

一句话结论

JPA 擅长实体状态管理与对象关联,Exposed 类型安全但无持久化上下文,MyBatis 灵活手写 SQL;Kotlin 项目优先类型安全 SQL、想保留 SQL 可控性选 Exposed,需要实体自动脏检查与 ORM 能力选 JPA。

概念解释

对比维度:对象状态管理、关联懒加载、SQL 可控度、Kotlin 原生程度。Exposed 编译期列检查、SQL 显式;JPA 屏蔽较多 SQL 但有 N+1 与代理复杂度;MyBatis SQL 完全手写但类型安全弱。

原理流程

  1. 评估是否需要实体持久化上下文与脏检查。
  2. 评估 SQL 可控与方言迁移需求。
  3. 评估 Kotlin 类型安全偏好。
  4. 按主导维度选型,混合场景可分模块使用。

代码或图示

JPA:实体状态机、代理关联、脏检查;SQL 生成受 ORM 约束
Exposed:Kotlin DSL 类型安全、SQL 显式;无一级缓存
MyBatis:手写 SQL + 映射;灵活但编译期检查弱

常见误区

  • 只看「Kotlin 原生」就选 Exposed:缺少 ORM 状态管理能力要自行实现。
  • 期望 Exposed 提供 JPA 式实体跟踪:能力边界不同。

追问

  • 多数据库方言支持?答:Exposed 按方言生成 SQL,见方言条目。
  • 复杂报表用哪层?答:DSL 或原生 SQL,DAO 不适合聚合分析。

06.8.3.1-004 Exposed 支持哪些数据库方言?

一句话结论

Exposed 通过方言模块支持主流关系数据库(PostgreSQL、MySQL、SQL Server、Oracle、SQLite、H2 等),SQL 生成与类型映射按方言适配;具体方言清单与版本支持以官方文档为准(待确认)。

概念解释

方言决定分页语法、列类型映射、自增方式、函数差异。连接时指定数据库方言,DSL 表达式翻译为对应 SQL。跨库移植需核对方言特有语法与列类型。

原理流程

  1. 引入对应方言依赖。
  2. Database.connect 指定 dialect。
  3. 查询表达式按方言生成 SQL。
  4. 方言特有函数/类型使用对应扩展。

代码或图示

// 连接时指定方言(示意,具体工厂 API 以版本文档为准)
// Database.connect(url, driver = driver, dialect = PostgreSQLDialect)

常见误区

  • 跨库直接复用方言特有函数:换库后 SQL 不兼容。
  • 忘记引入方言模块:类型映射与 SQL 生成异常。

追问

  • 方言在连接层还是查询层指定?答:连接数据库时确定,见 connect 条目。
  • 新数据库版本语法支持?答:以 Exposed 版本发布说明为准,标待确认。

06.8.3.1-005 Exposed 核心模块如何划分?

一句话结论

exposed-core 提供表定义、DSL 与连接基础;exposed-jdbc 承载 JDBC 执行;exposed-dao 提供实体层;exposed-java-time 映射时间类型;协程/异步模块按需要引入。

概念解释

模块按职责拆分:core 定义模型与表达式,jdbc 执行 SQL,dao 实体封装,时间模块桥接 java.time。应用按需引入,基础 DSL 项目不一定需要 dao 模块。

原理流程

  1. 引入 core + 对应 jdbc/方言依赖。
  2. 需要实体层加 dao 模块。
  3. 时间字段加 java-time 类型映射模块。
  4. 协程场景加对应协程扩展模块。

代码或图示

exposed-core:Table、列、查询表达式
exposed-jdbc:JDBC 连接与执行
exposed-dao:实体工厂与 CRUD
exposed-java-time:Instant/LocalDateTime 列类型

常见误区

  • 只引 core 就尝试实体 CRUD:dao 模块缺失。
  • 时间列不引 java-time 模块:类型无对应列定义。

追问

  • 模块版本是否统一?答:同一 Exposed 版本基线,模块间配套发布。
  • 异步/协程模块名?答:见协程模块条目,具体坐标以官方文档为准(待确认)。

06.8.3.1-006 依赖坐标与版本基线如何确定?

一句话结论

Exposed 版本与 Kotlin 编译器、JDBC 驱动对齐;本节基线为 0.5x 系列,具体工件坐标、版本号与兼容性以官方仓库发布说明为准,不凭记忆写死小版本(待确认)。

概念解释

库版本、Kotlin 版本、数据库驱动三者构成兼容集合。构建配置中声明 exposed-core、jdbc、方言与时间模块,版本统一管理;升级时查发布说明与迁移指南。

原理流程

  1. 确定 Kotlin 编译器版本。
  2. 选兼容的 Exposed 0.5x 版本。
  3. 引入模块与 JDBC 驱动。
  4. 编译与集成测试验证后固定版本。

代码或图示

// build.gradle.kts 依赖示意;坐标与版本号以官方发布为准(待确认)
// implementation("org.jetbrains.exposed:exposed-core:0.5x")
// implementation("org.jetbrains.exposed:exposed-jdbc:0.5x")

常见误区

  • 各模块写不同 Exposed 版本:模块间二进制不兼容。
  • 驱动版本与数据库服务端不匹配:连接与类型行为异常。

追问

  • 版本兼容查哪里?答:Exposed GitHub releases 与 Kotlin 兼容说明。
  • 快照版本能上生产吗?答:生产用稳定发布版,快照仅评估。

06.8.3.1-007 Database.connect 初始化流程是什么?

一句话结论

Database.connect 建立数据源连接并绑定方言与库实例,后续表定义与事务在该库实例上执行;连接参数、驱动、池化数据源在此配置,应用启动时初始化一次。

概念解释

connect 创建/绑定 Database 对象,持有数据源引用。表对象是声明式定义,不持有连接;查询与事务通过当前库实例获取连接。多数据源时分别 connect 得到独立 Database 实例。

原理流程

  1. 提供连接 URL、凭证或数据源。
  2. connect 创建 Database 实例并指定方言。
  3. 表定义注册到元数据。
  4. 事务/查询从实例取连接执行。

代码或图示

Database.connect(
    url = "jdbc:h2:mem:demo",
    driver = "org.h2.Driver",
    user = "sa",
    password = "",
)

常见误区

  • 每次查询重复 connect:创建多余数据源,连接池失控。
  • 表定义在 connect 之前还是之后?答:表对象延迟引用库实例,顺序以官方文档为准(待确认)。

追问

  • 能否传入已有 HikariCP 数据源?答:可以用数据源工厂方式 connect,见连接池条目。
  • 连接失败何时暴露?答:connect 阶段或首次取连接时,按实现行为验证。

06.8.3.1-008 表定义的注册机制是怎样的?

一句话结论

object 继承 Table 作为表定义单例,列属性在构造器中声明;表定义是元数据描述,查询时被引用生成 SQL,不对应运行期实体对象。

概念解释

Kotlin object 保证表定义全局一份。列属性返回列描述符,携带列名、类型、约束。表对象在 DSL 表达式中作为列引用锚点,避免硬编码字符串列名。

原理流程

  1. 声明 object 继承 Table。
  2. 构造器内定义列属性。
  3. 表元数据被库实例识别。
  4. 查询表达式引用列描述符生成 SQL。

代码或图示

object Articles : Table("articles") {
    val title = varchar("title", 128)
    val createdAt = long("created_at")
}

常见误区

  • 把表定义当实体类实例化:表对象是元数据,不是行对象。
  • 列属性写成普通字段不返回列描述符:DSL 无法引用。

追问

  • 表名可以省略吗?答:默认按类名推导,建议显式声明表名。
  • 多表同名不同 schema?答:按方言 schema 配置支持,见官方文档(待确认)。

06.8.3.1-009 列类型系统如何与 SQL 类型对应?

一句话结论

列定义函数(varchar、long、integer、decimal 等)声明 Kotlin 类型与 SQL 列类型映射;列描述符携带可空性、默认值与约束,查询取值按 Kotlin 类型返回。

概念解释

每个列工厂对应一种 SQL 类型并确定 Kotlin 侧取值类型。可空列经 nullable() 修饰,取值返回可空类型。类型映射在方言层转换为实际 DDL 类型。

原理流程

  1. 表构造器调用列工厂。
  2. 列描述符记录名称、类型、可空性、约束。
  3. DDL 按方言生成列定义。
  4. 查询结果按类型读取列值。

代码或图示

val price = decimal("price", 10, 2)
val label = varchar("label", 32).nullable()

常见误区

  • Kotlin 可空性与列可空性不一致:取值空安全判断错误。
  • 选精度不足的数值类型:小数/整数溢出。

追问

  • 自定义类型映射?答:按方言列类型扩展,通用 JDBC 类型处理见 05 分册。
  • 布尔列用什么?答:bool 列工厂,见基础类型条目。

06.8.3.1-010 Exposed 协程与时间模块有哪些?

一句话结论

时间类型由 exposed-java-time 模块提供 Instant/LocalDateTime 等列映射;协程支持通过对应非阻塞/协程模块提供挂起事务与查询 API,模块名称与稳定性以官方文档为准(待确认)。

概念解释

JDBC 原生时间类型映射需要专门模块补齐。协程模块把阻塞 JDBC 调用包装为挂起函数或提供异步驱动适配;同步 JDBC 与协程事务的边界需在选型时确认。

原理流程

  1. 引入 java-time 模块声明时间列。
  2. 协程场景引入对应协程/异步模块。
  3. 挂起 API 在协程上下文执行数据访问。
  4. 同步场景仍走阻塞事务块。

代码或图示

// 时间列示意(模块提供)
// val createdAt = instant("created_at")

常见误区

  • 服务端协程直接调用阻塞 JDBC 事务:事件循环线程被阻塞(通用风险见 06.8.2.2)。
  • 未引时间模块直接用 java.time 列:编译期无对应列工厂。

追问

  • 协程模块是否成熟?答:按官方文档标注的稳定/实验状态评估,待确认。
  • 异步驱动支持哪些库?答:以模块文档列出的驱动为准,不自行假设。

06.8.3.1-011 同步 JDBC 与异步驱动的边界在哪里?

一句话结论

标准 exposed-jdbc 走阻塞 JDBC,事务块内线程等待数据库响应;异步/协程模块承接非阻塞驱动适配,两者 API 与线程模型不同,不要在阻塞事务内嵌套协程并发访问同一连接。

概念解释

阻塞 JDBC 绑定事务连接,方法调用等待 SQL 完成。非阻塞驱动不占线程等待,但连接管理与事务边界由异步模块实现。混用两套模型容易造成连接泄漏或事务上下文错乱。

原理流程

  1. 阻塞路径:transaction { } 内 JDBC 调用,线程持有连接。
  2. 异步路径:挂起事务/查询 API,驱动非阻塞回调。
  3. 同一业务链路选择一种模型。
  4. 跨模型调用需经过隔离边界。

代码或图示

阻塞:transaction { 查询/写入,连接随事务持有 }
异步:挂起事务 + 非阻塞驱动(模块能力待确认)

常见误区

  • 在阻塞事务里 launch 子协程访问仓库:连接不跨协程安全共享。
  • 用异步模块能力却仍配阻塞驱动:模型不匹配。

追问

  • 阻塞事务能否包 suspend 调用?答:同连接事务上下文能否跨挂起点需实测验证(待确认),稳妥做法是事务边界内只做阻塞数据访问。
  • 连接线程安全?答:JDBC 连接非线程安全,绑定单一线程/事务上下文。

06.8.3.1-012 DSL 生成 SQL 的可控性如何?

一句话结论

DSL 表达式翻译为明确 SQL,可开启日志查看生成语句;表名、列名、条件、连接都由表达式推导,便于审计与调优,但方言函数与隐式行为仍需理解生成结果。

概念解释

相比字符串拼接 SQL,DSL 编译期检查列与类型;相比全自动 ORM,生成 SQL 可见可查。复杂表达式展开后的 SQL 需阅读日志确认连接、子查询与参数绑定,避免隐式笛卡尔积。

原理流程

  1. 查询表达式构造条件与连接。
  2. 库按方言生成 SQL 与绑定参数。
  3. 日志打印语句便于核对。
  4. 慢查询按生成 SQL 分析执行计划。

代码或图示

// 开启 SQL 日志后查看实际生成的 select/join 语句

常见误区

  • 不看生成 SQL 就评估性能:隐式连接/排序可能超出预期。
  • 把 DSL 当黑盒:列引用虽类型安全,索引与计划仍需人工核对。

追问

  • 参数绑定怎么防注入?答:DSL 条件值以绑定参数传入,不拼字符串;原生 SQL 混合时注意参数化,见原生条目。
  • 生成 SQL 能自定义改写吗?答:按方言扩展与原生查询能力,见官方文档。

06.8.3.1-013 SchemaUtils 迁移能力如何定位?

一句话结论

SchemaUtils 提供按表定义创建/校验/删除 schema 的工具方法,适合开发与测试环境建表;生产版本化迁移应由专门迁移工具管理,不依赖启动期自动建表。

概念解释

SchemaUtils 能从表定义生成 DDL 创建表、索引与约束,便于本地与测试快速起库。它不管理迁移版本、回滚与变更历史,生产演进仍需 Flyway/Liquibase 等迁移方案。

原理流程

  1. 表定义描述列与约束。
  2. SchemaUtils.create(表) 生成 DDL 建表。
  3. 校验工具对比定义与现有 schema。
  4. 生产迁移走独立版本化脚本。

代码或图示

// 开发/测试:按定义建表
// SchemaUtils.create(Users, Articles)

常见误区

  • 生产启动自动 createMissingTables:变更无版本记录,回滚困难。
  • 表定义与迁移脚本长期漂移:两边 schema 不一致。

追问

  • 能列出现有表结构吗?答:校验/导出工具能力以官方文档为准(待确认)。
  • 索引变更怎么落生产?答:迁移脚本管理 DDL,表定义作为代码侧声明。

06.8.3.1-014 Exposed 与 Spring 容器如何集成?

一句话结论

Exposed 不提供 Spring 自动配置,通常在 Spring 组件中持有 Database 实例/数据源,仓库类封装 DSL 事务与查询;连接池、数据源由 Spring 或 Hikari 配置,Exposed 仓库作为普通 Bean 注入。

概念解释

Spring 负责容器、数据源与 Bean 生命周期,Exposed 负责 SQL 模型与执行。仓库 Bean 构造器注入数据源或 Database 实例,方法内开启 Exposed 事务;Spring 事务管理器与 Exposed 事务是两套机制,需明确边界。

原理流程

  1. Spring 配置数据源与连接池。
  2. 应用初始化绑定 Exposed Database。
  3. 仓库 Bean 封装表查询与事务块。
  4. 服务层调用仓库方法。

代码或图示

@Repository
class UserRepository(private val database: Database) {
    fun find(id: Long): UserRow? = transaction(database) {
        Users.selectAll().where { Users.id eq id }.singleOrNull()?.toUser()
    }
}

常见误区

  • 用 Spring @Transactional 期望管理 Exposed 连接:两者事务机制不自动互通。
  • 在 Spring Bean 里散落裸 DSL:仓库边界不清,复用与测试困难。

追问

  • 数据源由谁创建?答:Spring 配置 HikariCP 数据源,Exposed 通过数据源 connect。
  • 事务边界放哪层?答:仓库或服务层按项目约定统一,见事务条目。

06.8.3.1-015 Exposed 适合与不适合哪些场景?

一句话结论

适合 Kotlin 类型安全 SQL、关系型 CRUD 与报表查询、需要 SQL 可控的中等规模服务;不适合需要 ORM 实体状态跟踪、复杂懒加载关联图、或团队完全不想写 SQL 概念的场景。

概念解释

选型匹配度:团队 Kotlin 熟练度、SQL 可控要求、对象映射复杂度。Exposed 轻量直接,但关联图与持久化状态管理需自行设计;强 ORM 需求应评估 JPA。

原理流程

  1. 评估对象状态管理需求。
  2. 评估查询复杂度与 SQL 可控要求。
  3. 评估团队 SQL 与 Kotlin 能力。
  4. 匹配 Exposed/ORM/手写 SQL 方案。

代码或图示

适合:类型安全查询、显式 SQL、关系表结构清晰
不适合:自动脏检查、深度对象图懒加载、非关系型数据访问

常见误区

  • 用 Exposed 复刻 JPA 实体模型:自行实现状态跟踪成本高。
  • 文档型/缓存数据塞进关系 DSL:数据模型不匹配。

追问

  • 微服务简单 CRUD 适合吗?答:适合,表定义与查询直接轻量。
  • 复杂领域模型怎么分层?答:Exposed 表/行与领域模型分离,映射层转换,通用分层见 06.1。

06.8.3.1-016 Table 与 IdTable 有什么区别?

一句话结论

Table 是通用表定义,主键需自行声明列;IdTable 约定自增主键列 id,提供主键列工厂与实体/DAO 关联基础,单主键自增场景用 IdTable 更简洁。

概念解释

IdTable 内置主键约定,列类型为实体 ID 包装;复合主键或非自增主键用普通 Table 自行声明唯一约束。DSL 查询两者都基于列描述符,区别在主键约定与 DAO 支持。

原理流程

  1. 单自增主键:继承 IdTable 声明 id 列。
  2. 复合/自定义主键:继承 Table 声明列与主键约束。
  3. 查询按列描述符构造条件。
  4. DAO 层依赖 IdTable 主键约定。

代码或图示

// 自增主键
object Users : IdTable<Long>("users") {
    override val id = long("id").autoIncrement().entityId()
    val name = varchar("name", 64)
}

// 通用表
object Links : Table("links") {
    val source = long("source_id")
    val target = long("target_id")
}

常见误区

  • 复合主键强行套 IdTable:单主键约定不适用。
  • 主键列未声明自增/约束:插入与关联行为不符预期。

追问

  • 主键类型能用 UUID 吗?答:按方言 UUID 列类型声明,具体工厂见文档(待确认)。
  • IdTable 的 entityId 作用?答:把列包装为实体 ID 类型,配合 DAO 层使用。

06.8.3.1-017 复合主键如何定义?

一句话结论

普通 Table 上声明多个主键列并通过主键约束组合;Exposed 表定义的复合主键写法以版本 API 为准,关联引用需匹配主键列组合,DSL 条件按多列联合构造。

概念解释

关联表/业务自然键常用多列主键。表定义声明各列,标记复合主键约束;外键引用复合主键时按列组合映射。查询条件同时匹配主键各列才能唯一定位行。

原理流程

  1. 继承 Table 声明参与主键的列。
  2. 配置复合主键约束。
  3. 外键按列组合引用。
  4. 查询条件联合各主键列。

代码或图示

object UserRoles : Table("user_roles") {
    val userId = long("user_id")
    val roleId = long("role_id")
    // 复合主键约束按版本 API 声明(待确认)
}

常见误区

  • 只给单列加唯一约束当复合主键:关联与唯一性语义不符。
  • 外键引用只映射部分主键列:引用不完整。

追问

  • 复合主键能配 DAO 实体吗?答:DAO 主要面向 IdTable 单主键,复合主键以 DSL 为主。
  • 自然键 vs 代理键?答:业务稳定唯一键可作自然键,代理自增键便于关联演进。

06.8.3.1-018 自增列与 EntityID 如何工作?

一句话结论

autoIncrement() 标记数据库自增列,插入时不指定该列由库生成;entityId() 把列值包装为实体 ID 类型供 DAO 层引用,DSL 行取值仍可转为基础数值。

概念解释

自增列由数据库分配,插入返回生成键。EntityID 是 Exposed 实体层的标识包装,避免直接混用裸 Long;DSL 层可解包取数值。插入后通过返回键获取新 ID。

原理流程

  1. 列声明 autoIncrement()。
  2. insert 不含自增列,数据库生成值。
  3. 返回生成键映射到 ID 包装类型。
  4. 后续查询按 ID 条件引用。

代码或图示

val id = long("id").autoIncrement().entityId()

常见误区

  • 插入时手动给自增列赋值:覆盖数据库生成策略。
  • EntityID 与裸 Long 直接比较:需解包或按类型匹配。

追问

  • 批量插入能拿回自增键吗?答:按驱动与模块能力,批量回填行为见文档(待确认)。
  • UUID 主键不走自增:用默认值/应用生成策略。

06.8.3.1-019 基础数值与字符串列类型怎么选?

一句话结论

字符串用 varchar(n)/text,整数用 integer/long,金额用 decimal 并指定精度;按业务值域选类型,避免用浮点存金额,长度与精度在建表定义时确定。

概念解释

列工厂确定 SQL 类型与 Kotlin 取值类型。定长/变长字符串按存储选择,整数按值域选 32/64 位,金额用定点 decimal。类型选择影响存储、索引与计算精度。

原理流程

  1. 确定字段业务值域。
  2. 选择对应列工厂与参数。
  3. DDL 按方言生成列类型。
  4. 查询取值映射为 Kotlin 类型。

代码或图示

val sku = varchar("sku", 32)
val quantity = integer("quantity")
val amount = decimal("amount", 12, 2)

常见误区

  • 金额用 double/float:二进制精度误差。
  • varchar 长度过短:写入截断报错;过长浪费存储。

追问

  • 大文本用什么?答:text/大文本列工厂,见大文本条目。
  • 枚举列映射?答:枚举映射条目有说明,也可存字符串/整数列。

06.8.3.1-020 日期时间列如何映射?

一句话结论

时间类型由 java-time 模块提供列工厂映射 Instant/LocalDateTime/LocalDate;按是否需要时区选择类型,列定义对应方言时间类型,取值为不可变时间对象。

概念解释

时间模块补齐 JDBC 与 java.time 转换。Instant 存 UTC 时间戳,LocalDateTime 不带时区;跨时区存储优先 Instant,展示层再转时区。列可空性与其他列一致。

原理流程

  1. 引入时间模块。
  2. 表定义声明时间列工厂。
  3. DDL 生成方言时间列。
  4. 读取时转换为 java.time 对象。

代码或图示

// 示意(时间模块提供)
// val createdAt = instant("created_at")
// val birthday = localDate("birthday").nullable()

常见误区

  • 用 Long 时间戳又引入时间列混用:类型口径不统一。
  • LocalDateTime 跨时区存储:丢失时区语义。

追问

  • 旧 java.util.Date 支持?答:新代码用 java.time,旧类型适配按模块文档(待确认)。
  • 时间默认值?答:可在列定义设默认表达式/值,见默认值条目。

06.8.3.1-021 布尔、字符与枚举列如何定义?

一句话结论

布尔用 bool 列,字符按字符串或方言字符列;枚举两种方式:映射为字符串列存常量名,或用整数列存序号,推荐字符串以可读与演进安全为先。

概念解释

Kotlin enum class 在 Exposed 中没有强制专属列类型,通常通过列类型 + 双向转换映射。字符串列存枚举名,整数列存序号;枚举顺序调整不影响字符串存储。

原理流程

  1. 定义 Kotlin 枚举。
  2. 选择字符串/整数列存储。
  3. 写入与读取时在枚举与列值间转换。
  4. 非法值在边界校验。

代码或图示

enum class OrderStatus { PENDING, PAID }

// 字符串列存常量名
val status = varchar("status", 16)

常见误区

  • 枚举序号随声明顺序调整:历史数据错位。
  • 未做非法值校验:脏数据反序列化失败。

追问

  • 枚举转换工具?答:列定义扩展或仓库映射层完成,具体内置支持以文档为准(待确认)。
  • 布尔列方言差异?答:部分方言用 bit/boolean,由方言模块适配。

06.8.3.1-022 可空列如何声明?取值为何是可空类型?

一句话结论

列工厂后接 .nullable() 标记数据库可空,DSL 取值返回 Kotlin 可空类型;非空列返回非空类型,空安全由列定义与取值类型对应,编译期辅助判断。

概念解释

可空性是列定义元数据的一部分。nullable() 修饰后行读取得到 T?,需判空;未修饰列假定非空,取值为 T。列可空性应与表 DDL 约束一致。

原理流程

  1. 列定义调用 nullable()。
  2. 元数据记录列可空。
  3. 结果行读取返回可空类型。
  4. 使用前 elvis/检查判空。

代码或图示

val phone = varchar("phone", 20).nullable()
// 取值:row[phone] 为 String?

常见误区

  • 列可空但按非空取值解引用:运行期 NPE。
  • 非空列在 DDL 允许 NULL:类型断言与实际约束不符。

追问

  • 可空默认 null?答:未提供值时数据库按列默认值/null 约束处理。
  • 唯一约束与可空关系?答:多 NULL 在唯一索引中的行为按方言规则。

06.8.3.1-023 列默认值如何设置?

一句话结论

列定义可指定默认值(常量或数据库表达式),插入未提供该列时由数据库/列定义回填;默认值与 Kotlin 字段初始值分工:DB 默认值落库,应用层默认值在代码构造时生效。

概念解释

默认值减少插入必填列。列默认值在 DDL 中表达,未插入列由数据库填充;应用 data class 默认值只影响内存对象,不替代数据库默认约束。两者应保持语义一致。

原理流程

  1. 列定义声明默认值/表达式。
  2. DDL 生成列默认约束。
  3. insert 省略该列时使用默认。
  4. 读取时得到默认回填值。

代码或图示

val active = bool("active").default(true)
// val createdAt = instant("created_at").defaultExpression(CurrentTimestamp)

常见误区

  • 应用层给默认值就以为数据库也有默认:直接 SQL 插入仍缺列。
  • 默认值与可空性冲突:非空列无默认且插入缺失会报错。

追问

  • 默认表达式支持哪些?答:按方言函数支持范围,具体表达式工厂见文档(待确认)。
  • 默认值变更影响存量行吗?答:只影响新行,存量需迁移脚本回填。

06.8.3.1-024 唯一索引如何声明?

一句话结论

列上 uniqueIndex() 或表级唯一约束声明唯一索引,保证列/列组合不重复;唯一约束在插入冲突时抛唯一约束异常,业务层需捕获处理。

概念解释

唯一索引既是约束也是索引。单列唯一直接在列定义声明,多列唯一在表级配置。唯一约束防止重复业务键,冲突由数据库兜底,应用层先预检再捕获异常。

原理流程

  1. 列/表配置唯一索引。
  2. DDL 创建唯一索引。
  3. 插入/更新违反唯一约束被数据库拒绝。
  4. 异常映射为业务冲突错误。

代码或图示

val email = varchar("email", 128).uniqueIndex()

常见误区

  • 靠应用层查重不加唯一约束:并发下仍可能重复。
  • 唯一列包含可空组合:多 NULL 行为按方言理解。

追问

  • 多列唯一索引怎么配?答:表级复合唯一索引,API 以版本文档为准(待确认)。
  • 唯一索引与普通索引选择?答:唯一性需求才用唯一索引,纯加速查询用普通索引。

06.8.3.1-025 普通索引如何声明?

一句话结论

列上 index() 声明非唯一索引,加速查询条件与排序;索引按查询模式设计,避免盲目给所有列加索引,写入成本与存储需权衡。

概念解释

普通索引不约束唯一性,只加速检索。索引列覆盖过滤、连接、排序条件;过多索引拖慢写入并占用存储。表定义中声明索引,随 SchemaUtils/迁移脚本落库。

原理流程

  1. 分析高频查询条件列。
  2. 列定义声明 index()。
  3. DDL 创建索引。
  4. 查询优化器按索引选择计划。

代码或图示

val status = varchar("status", 16).index()

常见误区

  • 每列都建索引:写入放大、存储浪费。
  • 索引列顺序与查询条件不匹配:复合索引前缀失效。

追问

  • 复合索引怎么声明?答:表级多列索引,列顺序按区分度与查询条件设计,见慢查询条目。
  • 索引命名规则?答:默认按列推导,可显式指定名称,方言命名规则见文档。

06.8.3.1-026 外键引用如何定义?

一句话结论

列通过 reference(目标表.主键列) 声明外键关联,约束引用目标表主键/唯一键;DSL join 与外键定义相互独立,关联查询用 join 表达式,外键约束保证引用完整性。

概念解释

外键列存储关联 ID,reference 声明数据库约束。关联查询时用 join 按列条件连接,不依赖外键约束本身。删除/更新受外键策略约束,方言级联行为需明确配置。

原理流程

  1. 子表列 reference 父表主键列。
  2. DDL 生成外键约束。
  3. 插入关联值校验父行存在。
  4. 查询时 join 表达式连接两表。

代码或图示

object Orders : Table("orders") {
    val customerId = long("customer_id").reference(Customers.id)
}

常见误区

  • 以为外键定义会自动生成 join:查询仍需显式连接条件。
  • 删父行未考虑子表外键约束:删除被数据库拒绝。

追问

  • 级联删除/更新怎么配?答:外键约束策略按方言配置,见官方参考(待确认)。
  • 不想要数据库外键约束?答:仅存 ID 列,关联一致性由应用层保证。

06.8.3.1-027 列别名与表别名在查询中如何使用?

一句话结论

多表连接时可用表别名区分同名列,列表达式通过别名表引用;DSL 列描述符绑定表定义,自连接需要别名表实例避免列引用歧义。

概念解释

单表查询直接引用列;多表同名列必须区分来源。表别名在 join 中声明,查询结果按列取值。自连接需要别名化的表副本指向同一张物理表。

原理流程

  1. join 声明表与别名。
  2. 条件/投影通过别名引用列。
  3. 结果行按列描述符取值。
  4. 同名列冲突时用别名消歧。

代码或图示

// 连接时按表对象引用列;自连接通过别名实例区分父子行

常见误区

  • 多表同名列不区分:生成 SQL 列引用歧义报错。
  • 自连接复用同一表对象:别名与行身份混乱。

追问

  • 别名能自定义 SQL 输出列名吗?答:投影列别名能力按 DSL 版本支持,见聚合映射条目(待确认)。
  • 结果取值用列名还是列描述符?答:优先列描述符,编译期类型安全。

06.8.3.1-028 表名与列名的默认推导规则是什么?

一句话结论

未显式指定时,表名按类名推导(大小写/命名风格按库约定),列名默认取属性名;建议显式声明表名与列名,避免 Kotlin 驼峰与数据库蛇形命名不一致导致映射错误。

概念解释

DSL 允许省略名称,库按约定转换。Kotlin 属性驼峰与数据库列蛇形习惯不同,默认推导可能与现有 schema 不匹配。显式写名字段保证代码与表结构一致。

原理流程

  1. 表构造器传入表名。
  2. 列工厂传入 SQL 列名字符串。
  3. 未传时按默认推导规则生成。
  4. 生成 SQL 使用显式/推导名称。

代码或图示

object OrderItems : Table("order_items") {
    val orderId = long("order_id")
}

常见误区

  • 依赖驼峰自动转蛇形:推导规则与现有列名不符时映射失败。
  • 重构改 Kotlin 属性名但未改列名:默认推导改变 SQL 列引用。

追问

  • 命名转换可配置吗?答:按库默认约定,自定义映射以文档为准(待确认)。
  • 表名大小写敏感?答:与方言和操作系统排序规则相关,跨库部署注意。

06.8.3.1-029 如何显式自定义列名?

一句话结论

列工厂第一个参数是 SQL 列名字符串,显式书写可对齐既有数据库 schema;Kotlin 属性名与 SQL 列名可以不同,取值始终通过属性列描述符,不依赖字符串列名。

概念解释

属性名是代码侧标识,列名字符串是数据库侧标识。显式列名用于对接存量表、历史命名或方言保留字。查询与映射引用属性描述符,字符串只在生成 SQL 时使用。

原理流程

  1. 列工厂传入显式列名。
  2. 属性名与列名独立。
  3. DDL 与 SQL 使用列名字符串。
  4. 代码通过属性取值。

代码或图示

val customerId = long("cust_id") // 属性 customerId,列 cust_id

常见误区

  • 多个列误写相同列名:映射冲突。
  • 列名用保留字未加转义:方言生成 SQL 报错。

追问

  • 保留字列名怎么处理?答:按方言转义规则,库生成 SQL 通常处理,特殊情况核对文档。
  • 存量表改名怎么同步?答:先改数据库迁移脚本,再调整表定义列名。

06.8.3.1-030 嵌入值对象在 Exposed 中如何映射?

一句话结论

Exposed DSL 没有 JPA @Embeddable 式自动对象嵌入,值对象通常拆成多个列定义,在映射层组装为 Kotlin 值类/data class;对象到列的转换由仓库映射代码完成。

概念解释

地址、金额等值类型在关系库中拆列存储。表定义声明各组成列,行读取后组装为值对象;写入时从值对象拆字段。没有自动嵌入注解,映射逻辑显式可控。

原理流程

  1. 值对象定义字段组成。
  2. 表声明对应多个列。
  3. 行映射组装值对象。
  4. 写入拆解值对象字段。

代码或图示

data class Address(val city: String, val street: String)

object Shops : Table("shops") {
    val city = varchar("city", 64)
    val street = varchar("street", 128)
}

常见误区

  • 期望一个列直接存整个值对象:除非 JSON/序列列,否则需拆列。
  • 值对象可变性影响列映射:保持不可变值类型。

追问

  • 值对象存 JSON 列?答:见 JSON 列条目,方言相关支持待确认。
  • 映射层放哪?答:仓库内扩展函数 Row.to 值对象。

06.8.3.1-031 数组与 JSON 列支持到什么程度?

一句话结论

数组/JSON 列支持依赖方言(如 PostgreSQL 数组、JSONB),Exposed 提供对应类型扩展;具体列工厂、读写转换与版本状态以官方文档为准(待确认),跨库场景需评估可移植性。

概念解释

关系库对复杂结构存储能力不同:PG 有数组与 JSONB,MySQL 有 JSON 文本列。Exposed 方言模块提供类型化访问,序列化/反序列化由应用层配合。跨库移植时 JSON 列语法可能不兼容。

原理流程

  1. 确认目标方言支持的列类型。
  2. 引入对应方言扩展列工厂。
  3. 读写时序列化/解析 JSON 或数组。
  4. 跨库前核对方言差异。

代码或图示

// 方言相关:JSON/数组列工厂与转换 API 以 Exposed 文档为准(待确认)

常见误区

  • 把 JSON 列当关系关联查询:内部结构无法有效走关系索引。
  • 跨库假设 JSON 能力一致:函数与列类型语法不同。

追问

  • JSON 内部字段能建索引吗?答:方言 JSON 索引能力相关,见 05 分册数据库专题。
  • 复杂嵌套对象存哪?答:优先关系拆表,JSON 列用于非查询属性。

06.8.3.1-032 大文本与二进制列如何定义?

一句话结论

长文本用 text/大文本列,二进制用 blob/二进制列工厂;大字段避免进入默认列表查询,按需单独加载,控制行宽度与内存占用。

概念解释

大文本与二进制体积大,随主表查询会放大 IO 与内存。列定义按方言大类型工厂声明,读取时显式选取;列表页只取必要短字段,详情页再取大字段。

原理流程

  1. 列选择文本/二进制大类型。
  2. 列表查询不投影大字段。
  3. 详情查询按需读取大字段。
  4. 二进制流处理避免一次性加载到内存。

代码或图示

val content = text("content")
val avatar = blob("avatar").nullable()

常见误区

  • 列表接口 select 全列:大字段拖慢查询与序列化。
  • 二进制全量读入内存:大文件应流式处理。

追问

  • 大对象存数据库还是对象存储?答:大文件推荐对象存储,库存元数据,通用存储选型见 05 分册。
  • 文本列长度限制?答:text 类型按方言容量,超长内容评估存储方案。

06.8.3.1-033 CHECK 约束如何定义?

一句话结论

列/表级 CHECK 约束表达值域与组合条件,Exposed 对 check 约束的声明 API 支持程度按版本与方言确定(待确认);未覆盖时在应用层校验,数据库兜底约束按迁移脚本管理。

概念解释

CHECK 在数据库层强制行级条件(非负、枚举范围、字段组合)。DSL 若提供约束工厂则表定义声明,否则 DDL 脚本补充。应用层校验负责友好错误,数据库约束兜底脏数据。

原理流程

  1. 梳理行级不变量。
  2. 优先应用层校验返回友好错误。
  3. 数据库 CHECK 约束兜底。
  4. 约束定义随迁移脚本落库。

代码或图示

// CHECK 约束声明方式以 Exposed 版本 API 为准(待确认)
// 例:非负数量、金额大于零等条件

常见误区

  • 只在应用层校验:绕过应用的直写数据破坏约束。
  • 约束表达式方言不兼容:跨库迁移失败。

追问

  • 枚举值域能用 CHECK 吗?答:可以作为数据库兜底,配合应用层枚举转换。
  • 约束冲突异常怎么映射?答:捕获数据库约束异常转为 4xx 业务错误。

06.8.3.1-034 自引用关联如何建模?

一句话结论

自引用表的外键列引用本表主键,查询用自连接别名区分父行与子行;树形/评论楼中楼场景用 parentId 列 + 递归或分层查询,避免在内存中循环拼装导致 N+1。

概念解释

自引用关联列指向同一张表。层级查询需要递归 CTE 或显式层级路径,普通两次 join 只能取相邻层。表定义外键引用本表,查询别名表区分父子身份。

原理流程

  1. 表声明 parentId 列引用本表主键。
  2. 自连接用别名区分父子。
  3. 多层级用递归查询或闭包表。
  4. 批量加载避免逐行查父/子。

代码或图示

object Comments : IdTable<Long>("comments") {
    override val id = long("id").autoIncrement().entityId()
    val parentId = long("parent_id").nullable().reference(Comments.id)
    val text = text("text")
}

常见误区

  • 遍历树时逐节点查子行:N+1 查询。
  • 自连接别名未区分:父子行混淆。

追问

  • 深层树查询方案?答:递归 CTE、路径枚举或闭包表,通用树形结构见 02/05 分册。
  • 外键引用本表循环删除?答:删除顺序受外键约束限制。

06.8.3.1-035 表定义常见报错有哪些,如何定位?

一句话结论

常见问题:重复列名、列类型与方言不匹配、未引入模块导致列工厂缺失、表名/列名与现有 schema 不符;定位顺序是编译错误 → 表定义元数据 → DDL/生成 SQL → 数据库约束报错。

概念解释

编译期能发现列工厂缺失与类型问题;运行期 SQL 报错指向列名、类型转换或约束。表定义与存量 schema 漂移是最常见映射错误,核对 DDL 与表定义逐列比对。

原理流程

  1. 编译期检查模块依赖与列类型。
  2. 启动建表/查询时看生成 SQL。
  3. 数据库报错回查列名、类型、约束。
  4. 修正表定义或迁移脚本。

代码或图示

排查链:编译缺模块 -> 生成 SQL 列名/类型 -> DDL 对照 -> 约束冲突异常

常见误区

  • 报错只看异常消息不看生成 SQL:定位不到映射错位。
  • 表定义改了但数据库未迁移:两边结构不一致。

追问

  • 列类型转换失败在哪暴露?答:结果行读取或写入绑定阶段,按方言类型映射。
  • 如何打印建表 DDL?答:SchemaUtils/日志能力见官方文档(待确认)。

06.8.3.1-036 selectAll 与指定列查询有何区别?

一句话结论

selectAll() 取表全部列,指定列投影只取需要的列;列表接口应显式选列,避免大字段与无关列随查询返回,控制传输与内存。

概念解释

查询投影决定结果行包含哪些列。selectAll 便于调试与单行完整读取,生产列表场景显式列出列降低 IO。连接查询中两表列都进入结果行,按需投影更关键。

原理流程

  1. 调用 selectAll 或传入列列表。
  2. DSL 生成对应 SELECT 列清单。
  3. 结果行只包含投影列。
  4. 未投影列无法从行取值。

代码或图示

Users.selectAll().where { Users.active eq true }
Users.select(Users.id, Users.name).where { Users.active eq true }

常见误区

  • 列表页 selectAll 带出大文本/二进制列:传输与内存放大。
  • 投影后再尝试取未选列:行内无该列映射。

追问

  • 聚合查询能 selectAll 吗?答:聚合后只返回聚合列与分组列,见 groupBy 条目。
  • 投影列能做表达式计算吗?答:表达式列参与投影,取值按表达式类型,见聚合条目。

06.8.3.1-037 where 条件表达式如何构造?

一句话结论

where { 列 操作符 值 } 内返回布尔表达式,条件由列描述符与操作符组成,编译期检查列类型;多个条件用 and/or 组合,值以绑定参数形式传入。

概念解释

where 块内构造 DSL 布尔表达式树,翻译为 SQL WHERE 子句。操作符重载绑定列类型与参数类型,避免字符串拼接。空值、范围、集合匹配各有对应表达式。

原理流程

  1. where 块内引用列。
  2. 操作符生成条件表达式。
  3. 多条件组合为表达式树。
  4. 执行时参数绑定到 SQL。

代码或图示

Users.selectAll().where {
    (Users.active eq true) and (Users.role eq "ADMIN")
}

常见误区

  • 在 where 块内写 Kotlin if 取数据库数据:条件不会下推到 SQL。
  • 把值拼进列名:破坏类型安全与参数绑定。

追问

  • 条件为 null 时怎么处理?答:动态条件在块外拼装表达式,见动态条件条目。
  • 表达式短路?答:SQL 由数据库求值,Kotlin 侧短路逻辑不作用于结果集。

06.8.3.1-038 andWhere / orWhere 如何组合条件?

一句话结论

andWhere/orWhere 在已有查询上追加条件,分别以 AND/OR 连接;注意组合优先级,OR 分组需显式括号表达式,否则条件被错误分组导致越权查询。

概念解释

链式追加条件便于分步拼装。AND 与 OR 混合时 SQL 优先级固定,OR 两侧条件必须作为整体分组。动态查询中条件逐步累加,最终表达式树决定 WHERE 语义。

原理流程

  1. 初始查询基础条件。
  2. andWhere 追加与条件。
  3. orWhere 追加或条件。
  4. 混合条件显式分组生成括号。

代码或图示

// (status = PENDING OR status = PAID) AND active = true
Users.selectAll()
    .andWhere { (Users.status eq "PENDING") or (Users.status eq "PAID") }
    .andWhere { Users.active eq true }

常见误区

  • 多个 OR 未分组:条件被 AND 切开,结果集超出预期。
  • 链式 orWhere 层层叠加:分组语义混乱,难评审。

追问

  • 条件表达式能否抽成变量复用?答:可以,表达式对象可在块外构造后传入。
  • 优先级规则?答:SQL AND 优先于 OR,与 Kotlin 逻辑一致,分组按括号表达式。

06.8.3.1-039 常用比较操作符有哪些?

一句话结论

等值 eq/neq、大小 less/greater/lessEq/greaterEq、模糊 like/notLike、集合 inList/notInList;操作符与列类型匹配,字符串忽略大小写按方言函数处理。

概念解释

每个操作符对应一种 SQL 比较谓词。like 通配符按方言规则(%、_),inList 绑定集合参数。类型不匹配在编译期暴露,避免运行期隐式转换错误。

原理流程

  1. 列选择对应比较操作符。
  2. 传入匹配类型参数。
  3. 表达式生成谓词与绑定参数。
  4. 数据库求值过滤行。

代码或图示

Users.selectAll().where {
    Users.age greaterEq 18 and
    Users.name like "An%" and
    Users.role inList listOf("ADMIN", "OPERATOR")
}

常见误区

  • like 通配符未转义:用户输入含 % 时匹配范围扩大。
  • inList 空集合:生成 IN () 需按方言处理,建议空集合走单独分支。

追问

  • 大小写不敏感匹配?答:用方言 lower/upper 函数或对应扩展,具体 API 见文档(待确认)。
  • 数值比较边界?答:greaterEq 含边界,避免误用 greater 漏掉等值。

06.8.3.1-040 范围、空值条件如何写?

一句话结论

区间用 between,空值用 isNull/isNotNull;可空列判断必须用空值谓词,不能用 eq null,数据库 NULL 比较三值逻辑不成立。

概念解释

between 生成闭区间谓词。NULL 与任何值比较结果为 UNKNOWN,必须用 IS NULL/IS NOT NULL。可空列参与等值查询时注意 NULL 行不会被 eq 命中。

原理流程

  1. 区间条件列 between 下限上限。
  2. 空值判断用 isNull/isNotNull。
  3. 生成对应 SQL 谓词。
  4. 结果集按三值逻辑过滤。

代码或图示

Orders.selectAll().where {
    Orders.createdAt.between(from, to) and
    Orders.couponCode.isNull()
}

常见误区

  • eq null 判断空值:SQL 不命中 NULL 行。
  • 区间边界理解为开区间:between 通常含两端,按方言确认。

追问

  • 可空列参与排序?答:NULL 排序位置按方言规则。
  • 空集合区间?答:边界参数为空时不加入条件,动态拼装处理。

06.8.3.1-041 排序 orderBy 如何声明?

一句话结论

orderBy(列, SortOrder.DESC/ASC) 指定排序列与方向;多列按声明顺序生效,排序列应有索引支撑,避免文件排序大结果集。

概念解释

排序对应 ORDER BY 子句。多列先按第一列,再按第二列。排序方向逐列指定;索引顺序与排序一致时可避免额外排序操作,深分页场景排序必须稳定。

原理流程

  1. 查询后追加 orderBy 列与方向。
  2. 生成 ORDER BY 清单。
  3. 数据库按列排序。
  4. 配合 limit/offset 取页。

代码或图示

Articles.selectAll()
    .orderBy(Articles.createdAt, SortOrder.DESC)
    .orderBy(Articles.id, SortOrder.DESC)

常见误区

  • 只按时间排序:相同时间行顺序不稳定,翻页重复/遗漏。
  • 排序列无索引:大表文件排序成本高。

追问

  • 排序表达式能按函数结果吗?答:按方言表达式支持,索引无法直接命中函数结果。
  • NULL 排前面还是后面?答:方言默认行为不同,跨库需显式控制(待确认)。

06.8.3.1-042 limit / offset 分页如何使用?

一句话结论

limit(n) 限制行数,offset(m) 跳过前 m 行;深分页 offset 扫描代价高,大结果集改用主键游标/键集分页,排序键须唯一稳定。

概念解释

limit/offset 对应分页子句。offset 越大,数据库扫描跳过行越多。游标分页记住上一页最后排序键,下一页从键之后取数,避免线性扫描。

原理流程

  1. 确定稳定排序列。
  2. limit 取页大小,offset 跳过页数。
  3. 深分页改游标条件:排序键小于/大于上一页末值。
  4. 返回页数据与游标标识。

代码或图示

Articles.selectAll()
    .orderBy(Articles.id, SortOrder.DESC)
    .limit(pageSize)
    .offset(pageSize * page)

常见误区

  • 深分页仍用大 offset:延迟随页码线性增长。
  • 排序键不唯一:游标翻页重复或漏行。

追问

  • 总数 count 怎么取?答:单独 count 查询,大表 count 代价见聚合条目。
  • 游标存客户端还是服务端?答:排序键编码为游标,服务端校验防篡改。

06.8.3.1-043 groupBy 与聚合函数如何写?

一句话结论

按列 groupBy 分组,投影聚合函数 count/sum/avg/max/min;SELECT 列只能是分组列或聚合表达式,结果行按分组键与聚合值读取。

概念解释

分组查询把行按键聚合,聚合函数计算每组指标。非分组列出现在 SELECT 违反分组语义。聚合结果常映射为统计 data class,列表达式需取得聚合值。

原理流程

  1. 查询投影分组列与聚合表达式。
  2. groupBy 指定分组列。
  3. 数据库分组计算聚合。
  4. 结果行读取分组键与聚合值。

代码或图示

Orders
    .select(Orders.status, Orders.total.sum())
    .groupBy(Orders.status)

常见误区

  • SELECT 未分组的裸列:方言报分组错误。
  • 聚合结果按基础列类型取值:聚合返回可空/聚合类型,注意空组。

追问

  • count 去重?答:对应 distinct 计数表达式,具体函数见文档(待确认)。
  • 空表聚合返回什么?答:聚合无行时结果按方言为 NULL/空集,取值判空。

06.8.3.1-044 having 与 where 的区别?

一句话结论

where 在分组前过滤原始行,having 在分组后过滤聚合结果;按聚合值筛选(如组内金额大于阈值)必须用 having,行级条件用 where。

概念解释

执行顺序:FROM/JOIN → WHERE → GROUP BY → 聚合 → HAVING。having 引用聚合表达式,where 不能引用聚合结果。把行级条件误放 having 会损失过滤效率。

原理流程

  1. where 先过滤参与分组的行。
  2. groupBy 分组聚合。
  3. having 按聚合条件保留组。
  4. 结果返回过滤后的分组。

代码或图示

Orders.select(Orders.customerId, Orders.total.sum())
    .groupBy(Orders.customerId)
    .having { Orders.total.sum() greater BigDecimal.valueOf(1000) }

常见误区

  • 行级状态条件写进 having:本该 where 下推过滤。
  • having 引用未聚合列:分组语义错误。

追问

  • 聚合表达式能复用别名吗?答:SQL 别名在 having 中可见性按方言,DSL 建议重复表达式。
  • 分组条件走索引?答:where 过滤与分组列索引配合,having 不利用行索引。

06.8.3.1-045 innerJoin / leftJoin 如何选择?

一句话结论

内连接只返回两表匹配行,左连接保留左表全部行、右表未匹配为 NULL;按业务是否需要保留主表行选择,关联条件显式声明,避免漏掉连接条件产生笛卡尔积。

概念解释

连接类型决定未匹配行去留。内连接过滤掉无关联行;左连接右表列可能为 NULL,取值判空。连接条件在 on 中声明,where 中过滤右表列会变相把左连接变成内连接。

原理流程

  1. 确定主表与关联表。
  2. 按保留需求选 inner/left join。
  3. on 声明列匹配条件。
  4. 结果行区分匹配状态。

代码或图示

Orders.innerJoin(Customers).on { Orders.customerId eq Customers.id }
Orders.leftJoin(Payments).on { Orders.id eq Payments.orderId }

常见误区

  • 左连接后在 where 过滤右表非空:未匹配行被排除。
  • 多表连接缺 on 条件:笛卡尔积放大行数。

追问

  • 右连接/全连接?答:方言支持程度按文档,常用 inner/left 足够多数场景。
  • 一对多连接行数膨胀?答:主表行被多条关联复制,聚合去重见笛卡尔积条目。

06.8.3.1-046 连接条件 on 如何声明?

一句话结论

on { 左表列 eq 右表列 } 声明连接匹配谓词;等值关联外,非等值条件按方言表达式写在 on 中,连接列类型必须匹配,外键定义与连接条件是两回事。

概念解释

on 子句确定两表行如何配对。外键约束保证完整性,但查询连接条件仍需显式写出。复合关联在 on 中组合多个等值条件,列类型不一致会导致隐式转换与索引失效。

原理流程

  1. join 关联表。
  2. on 块内写列等值/谓词。
  3. 生成 JOIN ... ON 子句。
  4. 行按条件配对。

代码或图示

OrderItems.innerJoin(Products)
    .on { OrderItems.productId eq Products.id }

常见误区

  • 关联条件写到 where:内连接可等价,外连接语义被改变。
  • 关联列类型宽度不一致:隐式转换使索引无法使用。

追问

  • 复合关联 on 多列?答:on 块内 and 组合多个等值条件。
  • 外键没建能 join 吗?答:能,连接是查询行为,外键是约束,两者独立。

06.8.3.1-047 子查询如何表达?

一句话结论

DSL 条件中可嵌套子查询(如 inList 接子查询表达式、exists 谓词),子查询作为表达式参与外层 WHERE/投影;复杂多层子查询注意可读性与相关子查询执行效率。

概念解释

子查询把查询结果作为外层条件集合或表达式。相关子查询引用外层列,逐行执行可能放大成本;非相关子查询可独立先算。DSL 表达式嵌套程度按版本 API 能力确定(待确认)。

原理流程

  1. 构造子查询表达式。
  2. 嵌入外层条件谓词。
  3. 数据库按优化器选择执行计划。
  4. 结果返回外层。

代码或图示

// 子查询集合匹配:外层列 in (子查询选择列)
// 相关子查询:子查询引用外层表列(注意执行计划)

常见误区

  • 相关子查询逐行扫描:大表性能差,改 join/聚合。
  • 子查询返回多列用于单值谓词:类型不匹配。

追问

  • exists 谓词支持?答:按 DSL 版本表达式能力,见官方文档(待确认)。
  • 子查询与 join 哪个好?答:集合判断可改 join + 去重,按执行计划对比。

06.8.3.1-048 结果行如何按列取值?

一句话结论

Row 通过 row[列描述符] 取对应类型值,可空列返回可空类型;不建议按字符串列名取值,列描述符带来编译期类型检查,取值失败按列是否投影到结果行判断。

概念解释

Row 持有结果行投影列的值映射。列描述符记录类型与可空性,取值时转换为对应 Kotlin 类型。未投影列在 Row 中不存在,取字符串名容易拼错且无类型检查。

原理流程

  1. 查询结果迭代 Row。
  2. row[列] 按描述符取值。
  3. 类型按列定义转换。
  4. 可空结果判空使用。

代码或图示

val rows = Users.selectAll().toList()
val first = rows.firstOrNull()?.let { it[Users.name] }

常见误区

  • 取未投影列:行内无值,报错或返回空。
  • 可空列不判空直接解引用:NPE。

追问

  • 行转对象映射放哪?答:仓库扩展函数 Row.toXxx(),见 data class 映射条目。
  • 取值类型不匹配?答:列定义类型与 JDBC 结果类型不一致,核对方言映射。

06.8.3.1-049 查询结果如何迭代?

一句话结论

查询返回可迭代结果集合,可 toList() 物化全部行,或 forEach 逐行处理;游标式读取行为与驱动/模块版本相关(待确认),大数据集避免一次性物化到内存。

概念解释

迭代方式决定结果是全量驻留还是流式消费。toList 把行集合装入内存,适合中小结果;大结果集应分页/流式读取,控制堆内存。迭代期间连接持有状态需注意事务边界。

原理流程

  1. 执行查询得到结果句柄。
  2. toList 物化全部 Row 到内存。
  3. forEach 逐行消费。
  4. 迭代结束释放结果资源。

代码或图示

Users.selectAll().forEach { row -> handle(row[Users.name]) }
val all = Users.selectAll().toList()

常见误区

  • 大结果集 toList:堆内存溢出风险。
  • 迭代中开启新查询:同一连接事务上下文需确认支持(待确认)。

追问

  • 游标/批量抓取大小?答:按 JDBC 驱动 fetchSize 配置,通用 JDBC 参数见 05 分册。
  • 迭代结束连接归还?答:在事务/查询生命周期内归还,见事务连接条目。

06.8.3.1-050 聚合结果如何映射?

一句话结论

聚合行同时含分组列与聚合表达式列,按表达式描述符取聚合值;聚合值可能为 NULL(空组/无行),映射前判空,结果封装为统计 data class。

概念解释

聚合列不是普通表列,取值用聚合表达式对象引用。组无匹配行时聚合结果按方言为 NULL。映射层把分组键与指标组装为不可变 DTO,注意数值类型与小数精度。

原理流程

  1. 投影分组列与聚合表达式。
  2. 保存表达式引用供取值。
  3. 行读取分组键与聚合值。
  4. 判空后映射统计对象。

代码或图示

val total = Orders.total.sum()
Orders.select(Orders.status, total)
    .groupBy(Orders.status)
    .map { GroupStat(it[Orders.status], it[total]) }

常见误区

  • 聚合值当非空取值:空组 NPE。
  • 小数聚合精度丢失:映射类型与 decimal 精度匹配。

追问

  • 聚合表达式能复用吗?答:表达式对象可定义一次,投影与取值共用。
  • 分组键可空?答:分组列 NULL 单独成组,取值判空。

06.8.3.1-051 distinct 如何去重?

一句话结论

distinct 对结果行整体去重,对应 SELECT DISTINCT;一对多连接产生的重复主表行可用 distinct 或分组/子查询消除,注意 distinct 与排序、索引的配合。

概念解释

去重基于投影列组合。连接放大行数后,distinct 排序去重有额外成本。替代方案:聚合分组、存在性子查询,按执行计划选择,避免对大结果集盲目 distinct。

原理流程

  1. 确定需要唯一的列组合。
  2. 查询追加 distinct。
  3. 数据库对投影行去重。
  4. 返回唯一行。

代码或图示

Customers.select(Customers.id)
    .innerJoin(Orders).on { Customers.id eq Orders.customerId }
    .distinct()

常见误区

  • distinct 放在一对多连接后:去重排序成本高。
  • 投影列过多:distinct 比较列组合变大。

追问

  • 单列去重计数?答:用 distinct 聚合函数,见 count 条目。
  • 去重与分页配合?答:先去重再分页,计划需核对。

06.8.3.1-052 动态查询条件如何拼装?

一句话结论

条件表达式在 Kotlin 侧按可选参数逐步构造,最终传入 where;空条件不加入表达式,避免生成 AND null 或无意义谓词。查询参数对象与 DSL 表达式分层组装。

概念解释

列表筛选常含可选过滤项。先构造基础表达式,非空参数追加条件;全部为空时返回无条件查询。表达式对象可组合复用,仓库方法接收筛选参数对象返回查询。

原理流程

  1. 接收筛选参数(可空/默认值)。
  2. 逐参数判断是否加入条件。
  3. 组合表达式树。
  4. 传入查询 where 执行。

代码或图示

var cond: Op<Boolean>? = null
if (status != null) cond = (cond?.and(Users.status eq status) ?: (Users.status eq status))
Users.selectAll().where { cond ?: Op.TRUE }

常见误区

  • 空参数仍生成 eq null:过滤语义错误。
  • 条件表达式与查询耦合在控制器:仓库不可复用。

追问

  • 可选排序也动态拼?答:排序参数映射到 orderBy 列清单,校验白名单防注入。
  • 表达式类型为 Op?答:布尔表达式类型按 DSL 定义,空表达式用恒真/恒假占位。

06.8.3.1-053 如何混合原生 SQL?

一句话结论

复杂方言优化或 Exposed DSL 未覆盖的场景,可用原生 SQL 查询按参数化方式执行;原生片段同样要绑定参数,不拼用户输入,返回结果仍按列读取或映射。

概念解释

DSL 覆盖常规查询,极端优化可能需要原生片段。参数化绑定防注入;原生 SQL 脱离 DSL 类型检查,列名与类型需自行核对。能在 DSL 表达时优先 DSL 以保留类型安全。

原理流程

  1. 判断 DSL 是否可表达。
  2. 原生查询写 SQL 与绑定参数。
  3. 执行后按结果集映射。
  4. 方言相关片段标注移植风险。

代码或图示

// RawSql / 原生查询能力以 Exposed 版本文档为准(待确认)
// 参数绑定:占位符 + 参数列表,禁止拼接用户输入

常见误区

  • 原生 SQL 拼接字符串参数:注入风险。
  • 把可 DSL 表达的简单查询写成原生:失去类型安全与可维护性。

追问

  • 原生片段能出现在 join/where 吗?答:按方言扩展能力,见官方文档(待确认)。
  • 原生查询结果类型?答:JDBC ResultSet 手动读取,映射到 data class。

06.8.3.1-054 多列排序与稳定排序怎么做?

一句话结论

orderBy 按列顺序逐列指定方向;分页场景最后追加唯一主键列作为稳定排序兜底,保证相同排序值时行顺序确定,翻页不重复不遗漏。

概念解释

非唯一排序列在等值行之间顺序不稳定。追加主键列作为末级排序,使全排序键唯一。多列排序方向可不同(先时间倒序、再主键倒序),索引需匹配排序前缀。

原理流程

  1. 确定业务主排序键。
  2. 追加唯一主键兜底排序。
  3. 逐列声明方向。
  4. 分页/游标基于完整排序键。

代码或图示

Articles.selectAll()
    .orderBy(Articles.publishedAt, SortOrder.DESC)
    .orderBy(Articles.id, SortOrder.DESC)

常见误区

  • 缺少唯一兜底列:相同时间行翻页漂移。
  • 索引顺序与排序方向不匹配:文件排序。

追问

  • 升降序混合索引能利用吗?答:索引方向需与查询一致,部分方言支持反向扫描。
  • 游标记录哪些键?答:全部排序键的末值集合,编码为游标。

06.8.3.1-055 firstOrNull / single 如何取单条结果?

一句话结论

firstOrNull 取首行或 null,single/singleOrNull 要求至多一行;按业务唯一性选择,期望唯一却返回多行时用 single 暴露数据异常,不要默默取第一条。

概念解释

取单条方法约束结果行数:first 忽略多行,single 校验唯一性。唯一条件查询用 single 语义,可能无行用 singleOrNull;列表场景用 first 需明确只取首行的业务含义。

原理流程

  1. 按唯一性需求选取数方法。
  2. 查询执行得到结果集。
  3. 方法按行数约束取值。
  4. 多行/无行按方法约定抛异常或返回 null。

代码或图示

val user = Users.selectAll().where { Users.id eq id }.singleOrNull()

常见误区

  • 非唯一条件用 first:掩盖重复数据问题。
  • 期望存在却取 null:未区分无行与异常场景。

追问

  • 方法名对应 Exposed 版本 API?答:firstOrNull/singleOrNull 类方法命名以版本文档为准(待确认)。
  • 单行映射 data class?答:行内判空后调用映射函数。

06.8.3.1-056 SQL 日志如何开启?

一句话结论

通过库/驱动日志配置打印执行 SQL 与参数,开发排障查看生成语句;生产环境按级别控制日志量,避免全量 SQL 与参数写入日志造成性能与隐私问题。

概念解释

SQL 日志帮助核对生成语句、绑定参数与执行计划。日志级别区分语句、参数与结果集;生产只在排障时临时开启,敏感参数脱敏。通用日志配置见工程规范。

原理流程

  1. 配置 Exposed/驱动日志级别。
  2. 查询执行时打印 SQL 与绑定参数。
  3. 对照生成语句检查条件/连接。
  4. 生产按需要降级日志。

代码或图示

// 日志开启方式与配置项以 Exposed 文档为准(待确认)
// 输出:生成 SQL、绑定参数(敏感值脱敏)

常见误区

  • 生产默认打印全量 SQL:日志量大、泄露敏感数据。
  • 只看 SQL 不看参数:条件值未正确绑定。

追问

  • 慢查询日志?答:数据库侧慢查询日志与应用 SQL 日志配合,通用可观测性见 08 分册。
  • 参数脱敏怎么做?答:日志层对手机号、证件号等字段掩码。

06.8.3.1-057 如何调试生成的 SQL?

一句话结论

调试顺序:DSL 表达式 → 日志 SQL → 执行计划 → 结果行;先确认语句结构(投影、条件、连接、排序),再核对参数值,最后分析计划与索引问题。

概念解释

查询异常分四类:语法/方言错误、条件拼错、连接缺失、性能问题。日志 SQL 暴露结构,执行计划暴露索引与扫描问题;结果行异常再回查投影与映射。

原理流程

  1. 复现查询并打开 SQL 日志。
  2. 阅读生成语句核对条件与连接。
  3. 必要时查看执行计划。
  4. 修正表达式或索引后复测。

代码或图示

排查:DSL 表达式 -> 日志 SQL -> EXPLAIN 计划 -> 结果映射

常见误区

  • 异常只改代码不看 SQL:条件/连接错误定位不到。
  • 性能问题直接加索引:未先看计划确认扫描原因。

追问

  • SQL 与预期不一致?答:检查动态条件拼装与 OR/AND 分组。
  • 方言函数报错?答:核对目标方言支持,替换为方言兼容表达式。

06.8.3.1-058 执行计划什么时候查看?

一句话结论

上线前与慢查询出现时查看执行计划:关注扫描行数、连接顺序、是否走索引、文件排序与临时表;小数据测试通过不代表大表计划合理,需在接近生产数据量下验证。

概念解释

执行计划反映优化器选择。索引命中、连接顺序、排序方式决定响应时间。开发库数据量小,计划可能走全表扫描而不暴露问题;压测/生产样例数据上核对计划。

原理流程

  1. 准备接近量级的测试数据。
  2. 对慢查询取执行计划。
  3. 识别扫描行数与访问路径。
  4. 调整索引/连接/条件后复测计划。

代码或图示

计划关注点:type/access、rows、extra(filesort/temporary)、join 顺序、索引使用

常见误区

  • 只在空表/小库看计划:索引选择不具代表性。
  • 计划好就忽略慢查询:数据增长后计划可能变劣。

追问

  • 通用数据库执行计划见 05 分册;DSL 生成的 SQL 直接复制到数据库分析。
  • 统计信息过期影响计划?答:更新统计信息后重看计划。

06.8.3.1-059 复杂查询条件如何保持可读可维护?

一句话结论

条件按业务规则拆成命名表达式变量,连接与分组逻辑集中在仓库查询方法;长表达式分层构造,避免在调用处堆砌嵌套 and/or,条件含义用命名表达而非注释补救。

概念解释

DSL 表达式嵌套过深难评审。把"待支付订单""有效客户"等规则抽为表达式变量,组合主查询。筛选参数对象承载输入,查询方法返回可复用表达式,规则变更只改一处。

原理流程

  1. 识别可复用业务规则。
  2. 表达式变量命名规则含义。
  3. 主查询组合规则表达式。
  4. 条件变更集中维护。

代码或图示

val activeCustomer = Customers.active eq true
val recentOrder = Orders.createdAt greaterEq threshold
// 组合:activeCustomer and recentOrder

常见误区

  • 多层括号嵌套在一行:条件分组难核对。
  • 同一规则散落在多个查询:口径不一致。

追问

  • 规则表达式能跨查询复用吗?答:同表表达式可抽为仓库内私有成员。
  • 可读性与性能冲突时?答:先保证条件正确,再按计划优化结构。

06.8.3.1-060 查询的执行时机是惰性还是立即执行?

一句话结论

查询表达式构造后,在迭代/取结果(toList、forEach、single 等)时才向数据库执行;表达式本身是查询定义,多次迭代可能对应多次执行,行为以模块实现为准(待确认)。

概念解释

DSL 查询对象先描述语句,触发结果读取时才执行。区分"构造查询"与"执行查询":条件拼装阶段不碰数据库,物化阶段发起 SQL。重复遍历查询对象是否复用结果需核对实现。

原理流程

  1. select/where/join 构造查询表达式。
  2. 调用终端操作触发执行。
  3. 数据库返回结果集。
  4. 行迭代读取数据。

代码或图示

val query = Users.selectAll().where { Users.active eq true }
// 此时尚未执行;toList/forEach 时发起 SQL
val result = query.toList()

常见误区

  • 构造查询时以为已查库:错误地在拼装阶段处理结果。
  • 同一查询对象多次遍历:确认是否重复执行,避免隐式多次 SQL。

追问

  • 终端操作有哪些?答:toList、forEach、single/first 类取数方法,命名以文档为准。
  • 查询对象能缓存吗?答:结果自行物化保存,查询对象不承担缓存职责。

06.8.3.1-061 列值读取时类型如何转换?

一句话结论

JDBC 结果值按列定义工厂转换为 Kotlin 类型;数值、时间、布尔映射由方言/类型模块处理,类型不符在读取阶段暴露,应用层映射不要强转裸对象。

概念解释

列工厂声明 Kotlin 侧类型,读取时完成 JDBC 类型到目标类型转换。可空性、精度、时间时区在转换边界处理。映射函数依赖列描述符类型,不靠 as 强转 ResultSet 对象。

原理流程

  1. 列定义确定目标 Kotlin 类型。
  2. 驱动提供 JDBC 原生值。
  3. 类型模块转换。
  4. 映射层组装业务对象。

代码或图示

val qty: Int = row[Products.stock]
val price: BigDecimal = row[Products.price]

常见误区

  • 直接强转 JDBC 对象:类型/空值转换隐患。
  • 时间类型转换忽略时区:展示时间偏差。

追问

  • 自定义类型转换?答:列类型扩展或映射层手动处理,见官方类型扩展文档(待确认)。
  • 数值溢出?答:列类型选宽值域,读取后业务层校验范围。

06.8.3.1-062 聚合表达式与列别名如何映射?

一句话结论

聚合表达式对象作为投影列,取值时引用同一表达式;若需要结果列别名供外部使用,按 DSL 别名能力声明(待确认),映射层直接从表达式取值,不依赖 SQL 列名猜测。

概念解释

投影列可以是表列或表达式。聚合表达式保存在变量中,结果行用该变量取值。别名用于 SQL 输出可读性,Kotlin 侧仍以表达式描述符为准,避免按位置/名字取错列。

原理流程

  1. 定义聚合表达式变量。
  2. select 加入表达式。
  3. 行内用同一表达式取值。
  4. 映射指标到 DTO 字段。

代码或图示

val sum = Orders.total.sum()
val rows = Orders.select(Orders.status, sum).groupBy(Orders.status)
rows.map { Stat(it[Orders.status], it[sum]) }

常见误区

  • 按结果列位置取值:投影调整后错位。
  • 重复构造聚合表达式取值:表达式对象不一致导致读取失败。

追问

  • 别名支持版本?答:表达式 alias 能力以 Exposed 文档为准(待确认)。
  • 多个同名聚合?答:用不同表达式变量区分,避免取值歧义。

06.8.3.1-063 一对多连接为什么产生笛卡尔积?如何去重?

一句话结论

主表一行匹配 N 条子表行时结果行数放大;无连接条件产生完全笛卡尔积。去重方式:按主表键 distinct、改分组聚合、或用存在子查询判断关联,按查询目标选择。

概念解释

一对多 join 复制主表行。列表展示主表时不应把关联行数量带入;统计主表数量需去重,统计子表指标用分组聚合。笛卡尔积是缺连接条件的最坏情况,行数为两表乘积。

原理流程

  1. 检查 join 条件完整。
  2. 一对多放大时评估取数目标。
  3. 主表列表:distinct 或子查询。
  4. 关联指标:分组聚合,避免主表行重复计数。

代码或图示

-- 错误形态:join 后 count(主表) 被关联行数放大
-- 修正:count(distinct 主表键) 或分组聚合

常见误区

  • join 一对多后 count 主表:计数翻倍。
  • 多表连接逐层放大:行数乘积失控。

追问

  • N+1 与笛卡尔积区别?答:N+1 是循环内多次单查;笛卡尔积是单次连接行数放大,见性能条目。
  • 关联列表怎么取?答:主表与子表分开查询后按键组装,避免 join 放大。

06.8.3.1-064 结果如何映射到 data class?

一句话结论

在仓库层写 Row 映射扩展函数,逐列取值组装不可变 data class;映射与表定义解耦,业务 DTO 不直接暴露 Row/列对象,可空字段在映射时明确默认值与校验。

概念解释

行到领域对象的转换集中在映射函数。data class 字段类型与列取值对应,必填字段判空处理。映射层隔离 DSL 模型与业务模型,表结构变更只影响映射函数。

原理流程

  1. 定义业务 data class。
  2. Row 扩展函数逐列取值。
  3. 可空字段处理默认值/校验。
  4. 查询结果 map 为对象列表。

代码或图示

data class UserView(val id: Long, val name: String)

fun Row.toUserView() = UserView(
    id = it[Users.id].value,
    name = it[Users.name],
)

Users.selectAll().map { it.toUserView() }

常见误区

  • 把 Row 直接传出仓库:DSL 模型泄漏到业务层。
  • 可空列直接映射非空字段:非法数据触发异常。

追问

  • 嵌套对象怎么组装?答:主表行 + 关联行分开映射后组合,或映射层聚合。
  • 映射函数放哪个模块?答:仓库同文件私有/内部扩展,对外只暴露 DTO。

06.8.3.1-065 insert 如何构造写入?

一句话结论

insert { it[列] = 值 } 声明列与值,插入一行;列值按列类型绑定,自增/默认列可不赋值,插入在事务内执行,约束冲突由数据库拒绝并抛异常。

概念解释

insert 块内逐列赋值,表达式生成 INSERT 语句。可空列不赋值时取默认/NULL;非空无默认列必须赋值。写入前在应用层校验业务规则,数据库约束兜底。

原理流程

  1. 构造 insert 块赋值。
  2. 生成 INSERT 列清单与值绑定。
  3. 事务内执行写入。
  4. 约束冲突抛异常回滚。

代码或图示

Users.insert {
    it[name] = "Ann"
    it[active] = true
}

常见误区

  • 非空列漏赋值:数据库非空约束报错。
  • 插入后未在事务内:自动提交行为按连接配置,边界需明确。

追问

  • 插入后取行?答:回填主键见 insertAndGetId 条目。
  • 写入值类型不符?答:列类型绑定编译期检查,枚举/时间经模块转换。

06.8.3.1-066 如何拿回插入生成的自增 ID?

一句话结论

插入语句使用返回生成键的 API(如 insertAndGetId)获取自增列值;批量插入的回填能力按驱动/模块版本确定(待确认),拿不到键时用唯一业务键回查。

概念解释

单条插入可从驱动获取生成键映射回实体 ID。批量插入逐行回填支持度不一;应用生成 UUID 主键则不依赖数据库回填。插入后 ID 用于后续关联写入。

原理流程

  1. 构造 insert 不含自增列。
  2. 执行插入并请求生成键。
  3. 返回 ID 包装/裸值。
  4. 后续关联记录使用该 ID。

代码或图示

val id = Users.insertAndGetId {
    it[name] = "Ann"
}

常见误区

  • 批量场景假设每行都能回填:能力待确认,需实测。
  • 插入后立即用未回填的 ID:空值/错误键。

追问

  • 生成键列类型?答:自增主键按 IdTable 约定,EntityID 解包取值。
  • 数据库不返回键?答:用唯一业务条件回查获取行。

06.8.3.1-067 batchInsert 批量写入如何使用?

一句话结论

batchInsert 按行构造批量插入,减少往返次数;批次大小按行数与包大小控制,单批失败的回滚行为按事务与驱动确定,大事务分批提交避免锁与 undo 膨胀。

概念解释

批量插入把多行写入合并执行,降低网络往返。批次过大会导致长事务、锁持有与日志膨胀;分批提交平衡吞吐与恢复粒度。行内列赋值逻辑复用单行构造函数。

原理流程

  1. 准备待写入行集合。
  2. 按批次切分。
  3. batchInsert 逐行赋值。
  4. 批次在事务内提交,失败回滚批次。

代码或图示

Products.batchInsert(list) { row ->
    this[Products.sku] = row.sku
    this[Products.name] = row.name
}

常见误区

  • 万行以上单批插入:长事务与 undo 膨胀。
  • 批内部分行失败假设可部分提交:事务回滚边界需实测确认。

追问

  • 批量回填主键?答:按驱动支持度,待确认。
  • 批量写入性能参数?答:rewrite batch、fetchSize 等 JDBC/方言参数,见 05 分册。

06.8.3.1-068 update 如何按条件更新?

一句话结论

update(where 条件) { it[列] = 值 } 限定更新行并赋新值;条件必须明确,避免全表更新;更新表达式可用列上算术/函数,影响行数用于判断是否命中目标行。

概念解释

update 先按 where 定位行,再设置列值。无条件更新作用于全表,属危险操作。列值可以是常量或基于当前列的表达式;返回/影响行数帮助判断匹配是否符合预期。

原理流程

  1. 构造更新条件。
  2. update 块内赋值列。
  3. 数据库按条件匹配行更新。
  4. 校验影响行数。

代码或图示

Products.update({ Products.id eq id }) {
    it[stock] = Products.stock - 1
}

常见误区

  • 漏写 where:全表列被改写。
  • 并发更新不校验影响行数:乐观锁/丢失更新问题。

追问

  • 影响行数 API?答:update 返回受影响行数,命名以版本为准(待确认)。
  • 条件列无索引:大表更新扫描锁定大量行。

06.8.3.1-069 deleteWhere 如何删除行?

一句话结论

deleteWhere { 条件 } 按条件删除匹配行;删除条件明确并考虑外键约束,软删除优先于物理删除用于可恢复业务,批量删除分批执行避免长事务与锁。

概念解释

物理删除不可恢复,外键约束阻止仍被引用的行删除。需要审计/恢复的业务用状态标记软删除,查询过滤标记列。大批量删除分批进行,控制单事务规模。

原理流程

  1. 明确删除条件与范围。
  2. 检查外键引用与业务保留要求。
  3. deleteWhere 执行删除或软更新。
  4. 大批量分批提交。

代码或图示

// 物理删除
ExpiredTokens.deleteWhere { ExpiredTokens.expiredAt less threshold }

// 软删除:update 标记列
Orders.update({ Orders.id eq id }) { it[deleted] = true }

常见误区

  • 物理删除业务数据:无法恢复与审计。
  • 大批量一次删除:长事务锁定、主从延迟。

追问

  • 软删除查询过滤?答:所有查询附加未删除条件,易遗漏,仓库层统一封装。
  • 外键约束删除顺序?答:先删子表引用行,再删父表行。

06.8.3.1-070 唯一约束冲突如何处理?

一句话结论

并发插入/更新违反唯一约束时数据库抛冲突异常,应用层捕获并映射为业务冲突错误;先预检只降低概率,并发兜底仍依赖数据库唯一约束与异常处理。

概念解释

唯一约束是最后防线。应用层查重无法消除并发窗口,冲突由数据库拒绝。异常按类型识别唯一冲突,转换为 409/业务提示,避免堆栈直接暴露给调用方。

原理流程

  1. 写入前业务校验唯一性。
  2. 数据库唯一约束兜底。
  3. 捕获约束冲突异常。
  4. 映射为冲突响应/重试策略。

代码或图示

插入 -> 唯一约束冲突异常 -> 识别约束类型 -> 返回"已存在"业务错误

常见误区

  • 只靠应用查重:并发双写仍重复。
  • 把所有 SQL 异常都当唯一冲突:需区分唯一/外键/非空/检查约束。

追问

  • 冲突后重试策略?答:按业务选择回查更新或提示用户,不盲目重试。
  • 冲突异常类型?答:方言/JDBC 异常识别方式,按驱动文档核对(待确认)。

06.8.3.1-071 列值如何做基于当前值的表达式更新?

一句话结论

赋值右侧可以是列算术表达式(如 stock = stock - 1),由数据库在同一行内基于当前值计算;相比"读出-计算-写回",表达式更新避免并发丢失更新,减少往返。

概念解释

读改写序列在并发下会覆盖其他事务的修改。表达式更新把计算下推到数据库,行内原子完成。条件同时承担乐观校验作用,影响行数可判断是否命中。

原理流程

  1. update 块列赋值为列表达式。
  2. 生成 SET col = col ± expr SQL。
  3. 数据库行内求值更新。
  4. 校验影响行数。

代码或图示

Products.update({ Products.id eq pid }) {
    it[stock] = Products.stock - quantity
}

常见误区

  • 先 select 出内存值再写回:并发丢失更新。
  • 表达式跨多行引用:不是行内计算,语义不符。

追问

  • 扣减为负怎么防?答:条件加 stock greaterEq quantity,影响行数判断库存不足。
  • 表达式函数支持哪些?答:按方言函数集合,DSL 扩展见文档(待确认)。

06.8.3.1-072 upsert(冲突更新)如何处理?

一句话结论

冲突时插入或更新依赖方言的 upsert/on conflict 语法,Exposed 是否提供统一 DSL 方法及版本支持以官方文档为准(待确认);跨库场景需评估方言差异,回退为"查后写"或按方言原生片段。

概念解释

upsert 在唯一键冲突时转更新行。方言语法不同(PG ON CONFLICT、MySQL ON DUPLICATE KEY)。统一抽象能力若版本不足,只能按方言分支写原生片段,跨库可移植性下降。

原理流程

  1. 确认目标方言冲突语法。
  2. 优先用 DSL 提供的 upsert 方法(待确认)。
  3. 不支持时按方言写原生参数化片段。
  4. 映射冲突结果为插入或更新。

代码或图示

// upsert DSL 方法名、参数与方言覆盖范围以 Exposed 0.5x 文档为准(待确认)

常见误区

  • 假设所有方言统一支持 upsert:语法与列行为差异。
  • 查后写不加唯一约束:并发仍可能重复插入。

追问

  • 冲突更新哪些列?答:按方言冲突子句指定更新列清单。
  • 应用层重试?答:唯一约束兜底,冲突后回查再更新。

06.8.3.1-073 写入后对象状态如何刷新?

一句话结论

Exposed 没有持久化上下文自动跟踪实体变更,写入后需要重新查询或自行维护返回值;DSL 写入不返回变更后的行对象,乐观值、数据库默认值回填以重查为准。

概念解释

JPA 式一级缓存会同步实体状态,Exposed 无此机制。插入后拿到的是 ID 或影响行数,数据库默认值、触发器计算字段需重查取得。业务对象保持不可变,写入后按返回值重建。

原理流程

  1. 执行 insert/update/delete。
  2. 取得 ID 或影响行数。
  3. 需要最新行时按主键重查。
  4. 重建内存对象。

代码或图示

val id = Users.insertAndGetId { it[name] = "Ann" }
val saved = Users.selectAll().where { Users.id eq id }.singleOrNull()

常见误区

  • 期望写入对象自动带默认值/生成列:状态不会自动刷新。
  • 修改内存对象后以为自动持久化:必须显式 update。

追问

  • DAO 实体状态是否缓存?答:DAO 层实体生命周期与关联代理按模块实现,与 DSL 无持久化上下文不同,待确认。
  • 生成列(数据库计算)怎么取?答:插入后重查该行。

06.8.3.1-074 批量写入性能受哪些因素影响?

一句话结论

批量吞吐取决于批次大小、往返次数、索引/约束数量、事务提交粒度与驱动批量参数;批次并非越大越好,需在吞吐、锁持有与恢复粒度间实测折中。

概念解释

减少往返靠批量合并;单批过大拉长事务、占用 undo 与锁资源。表上索引、唯一约束、外键校验增加写入成本。驱动 rewrite batch 等参数按方言开启,性能基线用实测数据确定。

原理流程

  1. 切分合理批次。
  2. 控制单事务提交规模。
  3. 评估索引与约束写入开销。
  4. 压测不同批次大小取平衡点。

代码或图示

吞吐因子:往返次数 / 批次大小 / 索引数 / 外键校验 / 提交频率 / 驱动批量参数

常见误区

  • 批次越大越快:长事务导致锁与内存压力。
  • 忽略索引写入成本:批量导入慢于预期。

追问

  • 批量导入前临时关索引?答:按运维方案评估,重建索引成本与一致性风险,通用导入见 05 分册。
  • 批次失败恢复?答:分批提交使单批失败可重跑,不拖垮全量。

06.8.3.1-075 写入异常如何分类与界定回滚范围?

一句话结论

写入异常分约束类(唯一/外键/非空/检查)、数据转换类、连接/超时类;异常所在事务整体回滚,应用层按异常类型映射业务错误与可重试性,区分可恢复与不可恢复。

概念解释

约束异常是数据本身问题,通常不可重试;连接/超时类可能瞬时故障可重试。事务回滚后连接状态需重新获取,未回滚的连接不能继续复用。异常分类在数据访问边界转换为领域异常。

原理流程

  1. 捕获数据库异常。
  2. 按约束类型分类。
  3. 决定映射业务错误或重试。
  4. 事务回滚后释放连接。

代码或图示

唯一/外键/非空/检查 -> 业务错误,不重试
连接断/超时 -> 瞬时故障,按策略重试
其他 -> 记录堆栈,暴露系统错误

常见误区

  • 所有异常都重试:约束冲突重复写入无意义。
  • 回滚后继续使用连接:连接状态不可用。

追问

  • 异常翻译在哪层?答:仓库边界捕获并抛领域异常,控制器不接触 SQL 异常。
  • 部分失败怎么办?答:事务原子回滚,补偿或分批重跑按业务设计。

06.8.3.1-076 transaction { } 块的语义是什么?

一句话结论

transaction { } 在块内开启数据库事务,获取连接执行语句,块正常结束提交,块内抛出异常回滚;块内所有数据访问共享同一事务连接。

概念解释

事务块绑定连接与隔离级别。块内查询/写入走同一连接,块结束释放连接。Exposed 事务是独立于 Spring 事务管理器的机制,边界以 transaction 块为准。

原理流程

  1. 进入 transaction 块获取连接。
  2. 块内语句使用该连接。
  3. 正常退出提交。
  4. 异常退出回滚并释放连接。

代码或图示

transaction {
    Orders.insert { /* ... */ }
    Payments.insert { /* ... */ }
}

常见误区

  • 以为块内自动加入 Spring 事务:两套事务机制不互通。
  • 块内启动新连接:事务语句不在同一连接。

追问

  • 事务边界放仓库还是服务层?答:按项目约定统一,跨表写操作边界应覆盖全部写入。
  • 嵌套 transaction?答:见嵌套事务条目。

06.8.3.1-077 提交与回滚的时机如何确定?

一句话结论

事务块返回时提交,抛出未捕获异常时回滚;显式 rollback 标记可主动中止,提交前所有写入在事务内可见性按隔离级别决定,块外连接已归还。

概念解释

提交把事务变更持久化,回滚撤销全部未提交写入。异常沿事务块传播即触发回滚;业务规则不满足时可显式标记回滚。连接在提交/回滚后归还池化。

原理流程

  1. 块内累积变更。
  2. 正常退出 → commit。
  3. 异常/回滚标记 → rollback。
  4. 连接归还连接池。

代码或图示

transaction {
    if (!valid) rollback("业务不满足")
    // ... 写入
}

常见误区

  • 吞掉块内异常不传播:事务按提交结束,脏数据落库。
  • 块外补写数据:不在事务内,无法随主事务回滚。

追问

  • 提交后回调?答:afterCommit 类回调见事务回调条目。
  • 回滚能否部分提交?答:事务原子性,要么全提交要么全回滚。

06.8.3.1-078 嵌套事务如何传播?

一句话结论

嵌套 transaction 块默认加入外层事务(同一连接),内层回滚标记影响外层;独立提交需按隔离/保存点机制处理,Exposed 嵌套传播行为以版本文档为准(待确认)。

概念解释

多数 JDBC 驱动不支持真正嵌套提交,内层事务共享外层连接。内层抛异常回滚标记作用于外层事务;需要独立子事务时评估保存点或拆分到外层事务之外。

原理流程

  1. 外层事务获取连接。
  2. 内层块复用同一连接。
  3. 异常向上传播触发整体回滚。
  4. 独立提交需求用保存点/外层拆分。

代码或图示

transaction {
    // 外层连接
    transaction {
        // 同连接嵌套(传播行为待确认)
    }
}

常见误区

  • 以为内层失败只回滚内层:实际可能回滚整个外层事务。
  • 嵌套块内独立提交:JDBC 不支持同连接嵌套提交。

追问

  • 保存点支持?答:按方言与模块能力,待确认。
  • 多数据源能嵌套吗?答:不同数据源连接独立,无统一两阶段提交,见多数据源条目。

06.8.3.1-079 协程事务 newSuspendedTransaction 怎么用?

一句话结论

协程场景使用挂起事务 API(如 newSuspendedTransaction)在协程上下文中管理事务边界,配合非阻塞/协程模块;同步 JDBC 阻塞事务不要在协程事件循环线程内直接套用,具体 API 签名以文档为准(待确认)。

概念解释

挂起事务把事务边界放在协程作用域,连接绑定到协程上下文而非线程。阻塞 JDBC 事务与协程调度模型冲突时,应选择匹配驱动的模块。上下文切换时事务连接能否跟随需实测确认。

原理流程

  1. 协程作用域启动。
  2. 挂起事务块开启事务上下文。
  3. 挂起查询/写入在事务内执行。
  4. 块结束提交/回滚。

代码或图示

// 协程事务示意;API 名称、调度参数以 Exposed 协程模块文档为准(待确认)
// newSuspendedTransaction { /* 挂起查询/写入 */ }

常见误区

  • 阻塞 transaction { } 包 suspend 调用:线程与连接管理不匹配。
  • 协程切换后仍假设连接可用:事务上下文绑定规则待确认。

追问

  • 协程模块成熟度?答:官方文档标注稳定/实验状态,待确认。
  • WebFlux 服务事务边界?答:见 06.8.2.2 协程与 WebFlux 条目,两者边界对齐。

06.8.3.1-080 事务隔离级别如何设置?

一句话结论

事务可指定隔离级别(读未提交/读已提交/可重复读/串行化),默认沿用数据源/数据库配置;按一致性需求选择,通用隔离现象与原理见 05 分册,本节只讲 Exposed 指定方式。

概念解释

隔离级别决定并发事务间可见性与异常现象。Exposed 事务参数按方言映射到 JDBC 隔离常量。级别越高并发度越低,业务只需防特定现象时选择最低够用级别。

原理流程

  1. 分析业务一致性要求。
  2. 选择隔离级别。
  3. 事务参数传入级别。
  4. 数据库按级别执行。

代码或图示

// transaction(isolation = TransactionIsolation.REPEATABLE_READ) { /* ... */ }

常见误区

  • 一律串行化:并发吞吐下降。
  • 忽略默认级别:沿用数据库配置,行为可能不符预期。

追问

  • 隔离级别方言支持差异?答:方言映射 JDBC 常量,部分级别数据库内部转换,待确认。
  • 并发现象怎么验证?答:压测复现脏读/不可重复读/幻读场景。

06.8.3.1-081 只读事务如何声明?

一句话结论

事务可标记只读,告知数据库本事务不写入,优化器可据此选择执行计划并限制写操作;只读事务中执行写入应被拒绝或告警,避免把只读标记当业务权限控制。

概念解释

只读提示影响事务优化与一致性快照,不等同于访问控制。报表/查询场景标记只读,减少写锁与 undo 开销。权限隔离仍由应用层与数据库账号控制。

原理流程

  1. 事务参数标记 readOnly。
  2. 连接设置只读模式。
  3. 事务内只执行查询。
  4. 结束释放只读连接。

代码或图示

// transaction(readOnly = true) { /* 查询报表 */ }

常见误区

  • 用只读事务替代权限校验:写权限需账号/应用层控制。
  • 只读事务内写入:行为按方言,可能报错或静默提交。

追问

  • 只读连接从池获取是否复用?答:池化连接只读标记的重置按实现配置,待确认。
  • 长只读事务影响?答:快照持有时间过长影响 undo 回收,见性能条目。

06.8.3.1-082 事务连接如何获取与归还?

一句话结论

事务块从数据源获取连接,块结束(提交/回滚)后归还连接池;块内持有期间其他请求不能复用该连接,泄漏指连接未归还被长期占用。

概念解释

连接生命周期与事务边界绑定。嵌套/异步场景连接归属复杂,异常退出必须保证回滚与归还。池化连接复用前需重置状态(事务、临时表、会话变量)。

原理流程

  1. 事务开始从池取连接。
  2. 块内语句使用该连接。
  3. 结束提交/回滚。
  4. 连接归还池化并重置状态。

代码或图示

取连接 -> 事务内持有 -> commit/rollback -> 重置会话状态 -> 归还池

常见误区

  • 事务块外持有连接引用:归还后连接被复用,误用导致串数据。
  • 异常路径未回滚:连接泄漏,池耗尽。

追问

  • 连接泄漏怎么排查?答:见连接泄漏条目。
  • 连接会话变量残留?答:池化复用前重置,方言会话状态注意清理。

06.8.3.1-083 HikariCP 如何与 Exposed 集成?

一句话结论

Spring/应用先配置 HikariCP 数据源,Exposed 通过数据源方式 Database.connect 接入;连接池参数由 Hikari 管理,Exposed 只负责从池取连接执行 SQL。

概念解释

HikariCP 负责池大小、超时、空闲回收等参数;Exposed 不另建连接池。数据源作为 Bean 注入,启动时绑定 Database。JDBC URL、驱动、池参数与数据库服务端配置对齐。

原理流程

  1. 配置 Hikari 数据源参数。
  2. 构建 DataSource 实例。
  3. Database.connect 传入数据源。
  4. 事务从该池取连接。

代码或图示

val dataSource = HikariDataSource(hikariConfig)
Database.connect(dataSource) // 数据源工厂方式,具体重载以文档为准

常见误区

  • 每个事务新建数据源:连接池失效,连接数失控。
  • Exposed 直连 URL 又叠加 Hikari:两套连接管理混淆。

追问

  • 池参数怎么定?答:见连接池参数条目,按数据库最大连接与压测调整。
  • 数据源 Bean 生命周期?答:随容器关闭释放池,应用退出时优雅关闭。

06.8.3.1-084 如何配置多数据源?

一句话结论

每个数据源调用一次 Database.connect 得到独立 Database 实例,事务/查询显式指定目标库;不同库连接独立,不自动跨库事务,跨库一致性需应用层补偿。

概念解释

多库对应多套连接池与方言。表定义与库实例关联,事务块指定数据库。跨库写入没有统一两阶段提交,一致性靠业务补偿/最终一致。数据源按模块/租户划分。

原理流程

  1. 为各库配置独立数据源。
  2. 分别 connect 得到 Database 实例。
  3. 仓库按目标库使用对应实例事务。
  4. 跨库操作设计补偿流程。

代码或图示

val orderDb = Database.connect(orderDataSource)
val userDb = Database.connect(userDataSource)
// transaction(orderDb) { /* ... */ }

常见误区

  • 多库共用一个事务块:连接无法跨库纳入同一事务。
  • 表定义与库实例错配:连接到错误数据源执行 SQL。

追问

  • 跨库 join?答:不支持跨库连接时分别查询后在应用层组装。
  • 数据源动态切换?答:见数据源路由条目。

06.8.3.1-085 数据源如何按租户/模块路由?

一句话结论

多数据源路由在仓库层按租户标识/模块选择对应 Database 实例;路由规则集中封装,避免业务代码散落拼连接,路由键缺失或非法时 fail-fast。

概念解释

路由层持有库实例映射,根据上下文键选数据源。事务在选定实例上开启。键来自请求上下文/租户标识,需校验合法性。路由与表模型解耦,业务只调用仓库方法。

原理流程

  1. 注册库实例映射。
  2. 上下文解析路由键。
  3. 仓库选目标库实例。
  4. 在对应库事务内执行。

代码或图示

fun dbFor(tenant: String): Database =
    databases[tenant] ?: error("未知租户: $tenant")

常见误区

  • 路由键为空落到默认库:数据串租户风险。
  • 业务代码直接取数据源:路由规则散落难审计。

追问

  • 路由键从哪取?答:请求上下文/登录主体,通用 Web 上下文见 03/06 分册。
  • 租户迁移怎么做?答:离线迁移脚本,连接池与路由配置配套调整。

06.8.3.1-086 事务连接如何绑定到协程/线程上下文?

一句话结论

阻塞事务连接绑定当前线程,协程事务绑定协程上下文;跨线程/跨协程传递事务需使用对应模块的上下文机制,不要把 JDBC 连接从一个线程带到另一个线程复用。

概念解释

JDBC 连接非线程安全,事务上下文跟随执行载体。线程模型下 ThreadLocal 持有连接;协程模型由上下文元素持有。上下文切换时连接归属不清会造成连接竞争或泄漏。

原理流程

  1. 事务开始建立上下文到连接的绑定。
  2. 语句在绑定载体上执行。
  3. 上下文结束解绑并归还连接。
  4. 跨载体传递使用模块提供的机制。

代码或图示

线程:ThreadLocal 绑定连接
协程:CoroutineContext 元素绑定(模块能力待确认)

常见误区

  • 把连接对象传给异步回调:另一线程复用非线程安全连接。
  • 线程池切换后继续事务:连接上下文丢失。

追问

  • 事务内 launch 子协程?答:默认不共享事务连接,需模块明确支持,待确认。
  • MDC/ThreadLocal 在协程传播?答:通用协程上下文传播见 06.8.2.2。

06.8.3.1-087 连接泄漏如何排查?

一句话结论

泄漏表现为连接被长期占用、池耗尽、获取连接超时;排查连接占用时长、未归还的事务块、异常路径未回滚,结合池监控与事务边界定位。

概念解释

泄漏来源:事务块未正常结束、异常吞掉未回滚、长事务持有连接、连接引用被缓存复用。池监控看活跃连接、等待线程与占用时长;堆栈定位未关闭的事务上下文。

原理流程

  1. 观察池活跃连接与等待队列。
  2. 取占用连接的堆栈/事务上下文。
  3. 检查异常路径是否回滚归还。
  4. 修正事务边界后复测池行为。

代码或图示

监控:active / idle / waiting / 连接持有时长
排查:未关闭事务 -> 异常吞回滚 -> 长事务 -> 连接引用缓存

常见误区

  • 池耗尽就调大上限:根因是泄漏,扩容只是延后爆发。
  • 忽略异常路径:主流程正常,分支异常泄漏连接。

追问

  • 池泄漏监控指标?答:HikariCP 提供连接占用/等待指标,通用可观测性见 08 分册。
  • 长事务与泄漏区别?答:长事务是故意持有但超时应告警;泄漏是忘记归还。

06.8.3.1-088 事务超时如何设置?

一句话结论

事务超时限制事务最大持有时间,超时回滚并释放连接;超时时长按业务事务基线设置,区分语句超时与事务超时,避免长事务占用连接与锁。

概念解释

事务超时覆盖整体生命周期,语句超时控制单条 SQL。超时触发回滚,连接归还。批量/报表长事务应拆分,不依赖超大超时兜底。默认超时沿用数据源配置。

原理流程

  1. 设定事务/语句超时阈值。
  2. 超时触发回滚。
  3. 连接归还池。
  4. 慢事务记录告警。

代码或图示

// 事务超时参数与 JDBC/数据源配置对应,具体 API 以文档为准(待确认)

常见误区

  • 超时只在客户端设置:数据库侧长查询仍可能持有锁。
  • 批量任务放短事务内:超时打断整批,需分批设计。

追问

  • 超时异常可重试吗?答:回滚后可按幂等键重试,非幂等写操作先评估。
  • 锁等待超时?答:数据库锁等待参数独立配置,见 05 分册锁专题。

06.8.3.1-089 事务内调用远程接口有什么禁忌?

一句话结论

事务内避免调用远程 HTTP/MQ/外部服务:远程耗时拉长事务、占用连接与锁,远程失败与数据库事务无法原子回滚;远程调用应移出事务边界,用本地表/消息表保证最终一致。

概念解释

事务持有数据库连接与行锁等待远程响应,RT 波动直接放大锁占用。远程成功而数据库回滚、或数据库提交而远程失败,都无法靠同一事务保证。本地消息表/事务消息把外部动作移出事务。

原理流程

  1. 事务内只做数据库读写。
  2. 提交后再调用远程服务。
  3. 外部动作失败由补偿/消息重试。
  4. 关键一致性用本地消息表兜底。

代码或图示

禁忌:DB 事务 -> HTTP 调用 -> 等待响应 -> 提交
推荐:DB 事务落业务 + 消息记录 -> 提交 -> 异步消费远程调用

常见误区

  • 把 RPC 包在事务里:连接被网络 IO 占满,并发下降。
  • 认为远程失败回滚数据库就一致:已提交的外部副作用无法撤回。

追问

  • 事务消息怎么实现?答:本地消息表 + 投递重试,通用分布式事务见 09 分册。
  • 必须先调远程再落库?答:设计补偿与幂等,避免长事务耦合。

06.8.3.1-090 哪些异常会触发事务回滚?

一句话结论

事务块内抛出的未捕获异常触发回滚;受检/运行时异常在 Exposed 事务中的回滚规则按实现确定(待确认),业务异常应向上传播,不要在块内捕获后继续提交脏数据。

概念解释

回滚由异常传播触发。部分框架按异常类型决定回滚(如只回滚运行时异常),Exposed/JDBC 默认行为需核对文档。业务校验失败应抛异常终止块,捕获后吞掉会导致部分写入提交。

原理流程

  1. 块内异常抛出。
  2. 事务边界判断异常类型。
  3. 符合回滚条件则 rollback。
  4. 异常继续向上传播。

代码或图示

transaction {
    if (!stockEnough) throw BizException("库存不足")
    // 写入
}

常见误区

  • 块内 catch 后返回成功:已写入未回滚。
  • 假设所有异常都回滚:回滚规则按框架实现,待确认。

追问

  • 标记 rollback-only?答:嵌套场景回滚标记机制待确认。
  • 异常翻译后还回滚吗?答:在事务边界内抛出新异常仍触发回滚,翻译点要早于提交。

06.8.3.1-091 嵌套块如何并入外层事务?

一句话结论

内层事务块复用外层连接,其读写属于外层事务范畴;内层不能独立提交,内层回滚标记影响外层;独立子操作应放到外层事务之外或用保存点隔离。

概念解释

代码复用常导致仓库方法各自开事务。若外层已有事务,内层应识别加入而非新开连接。嵌套边界设计要明确:公共数据访问方法是否开启事务由调用方决定。

原理流程

  1. 外层事务建立连接。
  2. 内层块检测已有事务上下文。
  3. 复用连接并入外层。
  4. 提交/回滚由最外层边界决定。

代码或图示

transaction {
    repository.createOrder()   // 内部不再独立提交
    repository.recordEvent()
}

常见误区

  • 仓库方法各自开事务:外层事务内嵌套独立提交语义混乱。
  • 内层回滚只救内层:实际波及外层全部写入。

追问

  • 事务模板复用?答:区分"开启事务"与"参与事务"两类方法,设计接口约定。
  • 保存点回滚部分?答:能力按方言/模块,待确认。

06.8.3.1-092 事务提交后回调如何注册?

一句话结论

需要在提交成功后执行的动作(发消息、清缓存、写审计)使用提交后回调机制;回调失败不回滚数据库,需自行设计重试/补偿,回调内不要再依赖未提交数据。

概念解释

afterCommit 类回调在事务提交后触发,适合触发非事务副作用。回调异常不影响已提交事务;外部副作用仍需消息重试兜底。提交前回调与提交后回调用途不同,不要混淆。

原理流程

  1. 事务内注册提交后回调。
  2. 事务成功提交。
  3. 依次执行回调动作。
  4. 回调失败走补偿/重试。

代码或图示

// afterCommit 回调能力与注册 API 以 Exposed 文档为准(待确认)
// 用途:提交后发事件、失效缓存;不用于回滚数据库

常见误区

  • 回调里做必须与事务一致的写库:回调失败无原子保证。
  • 提交前回调读未提交数据:可见性按隔离级别。

追问

  • 回调顺序?答:注册顺序执行,回调不要有互相依赖的隐式假设。
  • 回滚时回调执行吗?答:提交后回调不执行,需区分回滚回调类型。

06.8.3.1-093 连接池参数如何映射 HikariCP?

一句话结论

池参数(最大连接、最小空闲、连接超时、空闲回收、生命周期)在 Hikari 配置中设置,Exposed 不重复管理;连接数按数据库上限与应用实例数测算,避免每个实例开满数据库连接。

概念解释

最大连接 = 实例数 × 单实例池上限,总和不能超过数据库最大连接。连接超时等待池分配,空闲回收控制常驻连接。参数基线靠压测:活跃连接峰值、等待队列、响应时间。

原理流程

  1. 确定数据库最大连接数。
  2. 按实例数反推单实例池上限。
  3. 配置超时与空闲回收参数。
  4. 压测调整池大小与等待超时。

代码或图示

池上限 × 实例数 ≤ 数据库 max_connections
参数:maximumPoolSize / minimumIdle / connectionTimeout / idleTimeout / maxLifetime

常见误区

  • 池越大越快:数据库连接数超上限反而排队超时。
  • 连接生命周期短于数据库侧断连:空闲连接被服务端关闭后复用报错。

追问

  • 池参数推荐值?答:无通用定值,按压测与数据库配置定,Hikari 官方说明可参考。
  • 等待连接超时表现?答:获取连接异常,看池等待队列监控。

06.8.3.1-094 多数据源场景的事务边界怎么划?

一句话结论

每个数据源独立事务,Exposed 不提供跨库两阶段提交;跨库操作按业务拆分为本地事务 + 补偿/消息一致性,避免在一个事务块内假设能同时提交两库。

概念解释

分布式事务通用模式(TCC、 Saga、消息最终一致)见 09 分册;本节明确 Exposed 边界:不同库连接各自提交/回滚。跨库一致性方案在应用层设计,不能依赖单一数据库事务。

原理流程

  1. 按库划分本地事务。
  2. 先提交主库事务。
  3. 次库操作走消息/补偿重试。
  4. 失败按 Saga 反向补偿。

代码或图示

orderDb 事务提交 -> 消息投递 -> userDb 异步消费
任一失败:补偿动作 / 重试幂等处理

常见误区

  • 跨库写入包一个"事务":第二库失败第一库无法回滚。
  • 忽略幂等:重试消费重复执行副作用。

追问

  • 能引入 JTA/XA 吗?答:按数据源与驱动 XA 支持评估,通用分布式事务见 09 分册。
  • 同库不同 schema?答:通常同一连接内可访问,仍属单库事务。

06.8.3.1-095 异步驱动的事务边界有何限制?

一句话结论

非阻塞/异步驱动下事务上下文由协程模块管理,连接绑定异步会话;异步事务的 API 能力、隔离级别与嵌套支持以模块文档为准(待确认),未覆盖能力不要套用阻塞事务经验。

概念解释

异步模型不占线程等待,连接生命周期由驱动回调管理。事务上下文跟随异步链路;阻塞 JDBC 的 ThreadLocal 经验不直接适用。选型时核对模块稳定性与生产案例。

原理流程

  1. 确认驱动与模块异步能力。
  2. 挂起事务开启异步会话。
  3. 异步查询/写入在会话内执行。
  4. 结束提交/回滚释放会话。

代码或图示

// 异步驱动、异步事务 API 与支持范围以 Exposed 官方文档为准(待确认)

常见误区

  • 阻塞事务经验直接套异步:连接/线程模型不匹配。
  • 生产使用实验性模块:未评估稳定性风险。

追问

  • 异步模块替代 JDBC 的条件?答:高并发非阻塞链路且模块成熟,待确认后再定。
  • 混合阻塞与异步仓库?答:边界隔离,不共享连接上下文。

06.8.3.1-096 Exposed 中 N+1 问题如何表现?

一句话结论

N+1 表现为循环内逐行查询关联数据:主表 1 次查询,每条记录再触发一次关联查询,随行数放大 SQL 次数;DSL 不会自动做实体关联懒加载,问题来自仓库手写循环查询。

概念解释

Exposed DSL 无 ORM 自动代理加载,关联数据需显式 join 或批量取数。循环内按 ID 单查是典型 N+1;DAO 层关联懒加载可能隐式触发同样问题,需按实现核对。

原理流程

  1. 主列表查询 1 次。
  2. 遍历每条记录查关联。
  3. 关联查询共 N 次。
  4. 总 SQL = 1 + N。

代码或图示

// 反例:循环内单查
orders.map { order ->
    Customers.selectAll().where { Customers.id eq order.customerId }.singleOrNull()
}

常见误区

  • 以为 DSL 会自动批量加载:关联需显式处理。
  • 接口返回结构嵌套:在服务层循环查子表形成 N+1。

追问

  • 怎么定位?答:SQL 日志统计同结构语句次数,见调试条目。
  • N+1 与笛卡尔积?答:前者多次单查,后者单次连接放大行数,见对应条目。

06.8.3.1-097 关联数据如何预加载避免 N+1?

一句话结论

两种方式:join 一次取主表与关联表字段映射组装;或先取主表 ID 集合,批量查询关联后按 ID 分组组装。一对多场景优先批量查询,避免 join 行数膨胀。

概念解释

一对一/多对一适合 join 取数;一对多用 join 会放大主表行,应分两次查询:主表列表 + 关联集合按 ID inList 批量取,内存中按键分组组装。

原理流程

  1. 查询主表得到主键集合。
  2. 关联表按主键集合批量查询。
  3. 结果按 ID 分组。
  4. 内存组装嵌套结构。

代码或图示

val orderIds = orders.map { it[Orders.id] }
val items = OrderItems.selectAll()
    .where { OrderItems.orderId inList orderIds }
    .groupBy { it[OrderItems.orderId] }

常见误区

  • 一对多强行 join:主表行重复,去重后再组装仍复杂。
  • 批量查询 ID 集合过大:分批 inList 控制长度。

追问

  • 三层嵌套怎么预加载?答:逐层批量取数,按 ID 分组向下组装。
  • join 字段选列?答:关联查询只投影需要列,避免大字段重复。

06.8.3.1-098 索引设计与慢查询如何治理?

一句话结论

索引围绕高频过滤、连接、排序列设计;慢查询从执行计划定位扫描与排序问题,按需补索引或改写查询,定期复盘低效索引与写入成本,通用索引原理见 05 分册。

概念解释

查询模式驱动索引设计:等值列、范围列、排序列顺序考虑。慢查询关注全表扫描、连接顺序差、文件排序、回表行数。索引不是越多越好,写入成本与冗余定期清理。

原理流程

  1. 统计高频查询条件与排序。
  2. 设计复合索引前缀。
  3. 慢查询取计划分析访问路径。
  4. 补索引/改写/清理冗余索引。

代码或图示

过滤列 -> 连接列 -> 排序列;计划关注扫描行数、filesort、join 顺序

常见误区

  • 单列为每个条件建索引:复合索引前缀未利用。
  • 只加索引不改查询:计划仍走低效路径。

追问

  • 复合索引列顺序?答:等值在前、范围在后,通用规则见 05 分册。
  • 慢查询告警?答:数据库慢日志 + 应用 SQL 耗时监控,见 08 分册。

06.8.3.1-099 并发与连接数压测关注哪些点?

一句话结论

压测关注吞吐、响应时间、连接池占用、等待队列、数据库锁等待与慢查询;连接数配置与实例数联动,验证事务持有时长在并发下不导致池耗尽。

概念解释

并发请求争用连接与数据库行锁。压测模拟峰值并发,观察池活跃/等待、事务时长、锁等待。慢事务在并发下放大连接占用,是池耗尽常见根因。

原理流程

  1. 按目标并发构造压测场景。
  2. 监控池指标与数据库锁。
  3. 定位慢事务/慢 SQL。
  4. 调整池参数、索引或事务边界。

代码或图示

指标:QPS / P95 延迟 / active-connections / 等待线程 / 锁等待 / 慢 SQL

常见误区

  • 单接口压测不看连接池:并发下连接排队被忽略。
  • 池上限盲目调大:数据库连接成为瓶颈。

追问

  • 连接等待超时怎么设?答:大于正常事务耗时,拒绝快于长时间阻塞排队。
  • 事务时长基线?答:从压测与生产日志取 P95/P99,长事务拆分。

06.8.3.1-100 综合场景:带事务分页关联查询如何落地?

一句话结论

落地顺序:表定义与约束 → 仓库查询方法(投影、过滤、稳定排序、分页)→ 关联批量预加载 → 写操作包事务边界 → 日志/计划/压测验证;每步对照本节目录条目核对。

概念解释

典型场景:分页列表 + 关联展示 + 状态写入。读路径用批量预加载避免 N+1,写路径事务覆盖多表原子操作,远程动作移出事务。结构按表定义、查询、写入、事务、性能分层验收。

原理流程

  1. 定义表、列、索引与外键。
  2. 列表查询:选列、动态条件、稳定排序、游标/offset 分页。
  3. 关联批量取数并组装 DTO。
  4. 写入操作在事务内完成,提交后触发外部副作用。
  5. 打开 SQL 日志核对计划,压测连接与耗时。

代码或图示

读:主表分页 -> 收集 ID -> 关联批量查 -> 分组组装
写:事务内多表写入 -> 提交 -> 事件/消息 -> 异步外部调用
验:SQL 日志 / 执行计划 / 池指标 / 异常分类

常见误区

  • 列表接口 join 一对多后分页:行数膨胀导致页数错误。
  • 写事务内调远程:连接与锁被网络 IO 拉长。
  • 未核对生成 SQL 与计划:上线后慢查询与 N+1 暴露。

追问

  • 分页总数怎么处理?答:独立 count 查询,大表按业务选择近似计数或不返回总数。
  • 复杂场景拆层?答:表定义/仓库映射/服务事务边界分层,通用工程分层见 06.1。

参考来源

待整理清单

  • [ ] Exposed 0.5x 模块坐标、版本与 Kotlin/JDK 兼容矩阵核对官方发布说明
  • [ ] DSL 子查询、exists、别名、upsert 等 API 签名在目标版本的实际可用性
  • [ ] 协程/异步事务模块的稳定性标注、驱动支持范围与上下文绑定规则
  • [ ] 方言特有列类型(数组、JSONB、枚举、check 约束)在各数据库的映射清单
  • [ ] 批量插入主键回填、嵌套事务传播与保存点行为的实测结论
  • [ ] 生产连接池参数基线与慢查询治理案例补充