后端ORM【免费下载链接】sqldelightSQLDelight - Generates typesafe Kotlin APIs from SQL项目地址https://gitcode.com/gh_mirrors/sq/sqldelight点击查看免费下载本指南围绕 SQLDelight 官方文档 docs/common/custom_projections.md 展开讲解查询结果投影的两条路径默认的数据类投影、以及通过 typesafe mapper 覆盖默认行为并对比在 SQL 中完成投影这一更优实践。读完你将掌握 mapper 参数的具体签名、生成代码的底层原理以及如何在真实项目中把两者组合起来写出类型安全且高效的查询。默认行为每个查询都会生成一个数据类在 SQLDelight 中你在.sq文件里声明的每一个命名查询默认都会返回一个由编译器生成的数据类字段对应你 SELECT 的投影列。以文档中的hockeyPlayer表为例hockeyPlayer: CREATE TABLE hockeyPlayer ( player_number INTEGER NOT NULL, full_name TEXT NOT NULL ); selectAll: SELECT * FROM hockeyPlayer;编译后生成的查询函数形如fun selectAll(): QueryHockeyPlayer其中HockeyPlayer就是编译器依据表结构生成的数据类QueryT则是运行时提供的可监听、带类型的查询封装见 runtime/src/commonMain/kotlin/app/cash/sqldelight/Query.kt。这一默认行为在编译器里有明确的实现路径SelectQueryGenerator.defaultResultTypeFunction()会生成一个把查询参数直接转发给数据类构造器引用的函数编译器测试断言它生成的代码等价于public fun selectForId(id: Long): QueryData_ selectForId(id, ::Data_)见 sqldelight-compiler/src/test/kotlin/app/cash/sqldelight/core/queries/SelectQueryFunctionTest.kt#L23-L51也就是说默认投影 SELECT 的列 直接对应数据类的属性一一映射零额外代码。用 Typesafe Mapper 覆盖默认投影当你不想要整张数据类只想取出投影中的一部分列、或把它们组合成自定义类型时SQLDelight 允许给查询函数传入一个typesafe mapper类型安全映射器完全接管一行结果 → 一个对象的转换。文档中的原始示例val selectAllNames playerQueries.selectAll( mapper { player_number, full_name - full_name.toUppercase() } ) println(selectAllNames.executeAsList()) // Prints [RYAN GETZLAF, COREY PERRY]这里有几个关键点值得展开1. Mapper 的参数就是投影列的 Kotlin 类型。编译器根据SELECT的每一列推导出对应参数的类型——player_number是Long、full_name是String参数顺序与投影列顺序完全一致。若某列声明了自定义类型适配器如INTEGER AS LocalDateTimemapper 中该参数会直接以适配后的类型出现你无需关心底层解码细节。2. 生成的是泛型函数。从源码看SelectQueryGenerator.customResultTypeFunctionInterface()会为查询函数添加类型变量T并把 mapper 声明为从各投影列到T的 Lambda返回值变为QueryT见 sqldelight-compiler/src/main/kotlin/app/cash/sqldelight/core/compiler/SelectQueryGenerator.kt#L86-L127。对应生成的代码签名形如public fun T : Any selectAll( mapper: (player_number: Long, full_name: String) - T ): QueryT编译器测试中可找到完全一致的生成结果例如selectForId生成public fun T : kotlin.Any selectForId(id: kotlin.Long, mapper: (id: kotlin.Long, value_: kotlin.String) - T): app.cash.sqldelight.QueryT见 SelectQueryFunctionTest.kt#L151。3. 运行时逐行调用 mapper。生成的QueryT内部持有这个 mapper执行时由ExecutableQuery遍历游标并逐行调用。executeAsList()的实现就是while (cursor.next().value) result.add(mapper(cursor))见 runtime/src/commonMain/kotlin/app/cash/sqldelight/Query.kt#L174-L178。同一套 mapper 机制还支撑executeAsOne()要求恰好一行否则抛异常与executeAsOneOrNull()最多一行可为 null。4. Mapper 不只是改个类型。它是在 Kotlin 侧对每一行执行的任意函数因此可以组合列、丢弃不需要的数据、直接构造你的领域对象。例如把两列拼成你自己的值对象data class PlayerName(val number: Long, val name: String) val names playerQueries.selectAll( mapper { player_number, full_name - PlayerName(player_number, full_name) } ).executeAsList()优先在 SQL 中完成投影文档给出了一个重要原则In general you should be leveraging SQL to do custom projections whenever possible.一般来说只要可能就应该借助 SQL 完成自定义投影。文档的示例selectNames: SELECT upper(full_name) FROM hockeyPlayer;val selectAllNames playerQueries.selectNames() println(selectAllNames.executeAsList()) // Prints [RYAN GETZLAF, COREY PERRY]同样是拿到大写化后的名字列表但这次转换完全由数据库在查询阶段完成Kotlin 侧连 mapper 都不需要写。这样做的好处是实质性的计算下推upper、lower、abs、concat等标量函数在数据库引擎内执行客户端只拿到最终结果避免了全量取回 逐行转换的双重开销传输更少数据投影列越少游标需要解码的数据越少这对网络驱动的 JDBC/R2DBC 与 Web 场景尤其有意义代码更简洁无需 mapper、无需定义中间类型生成的查询函数直接返回标量类型。一个值得注意的编译期行为是当查询只有单列投影时SQLDelight 会直接让查询返回该列的 Kotlin 类型根本不会生成带 mapper 的泛型函数。从源码看这是customResultTypeFunctionInterface()中needsWrapper()为 false 的分支No custom type possible, just returns the single column:fun selectSomeText(_id): QueryString见 SelectQueryGenerator.kt#L120-L124。测试同样验证了这一点例如SELECT NULL会生成fun T : Any selectData(mapper: (expr: kotlin.Nothing?) - T): ExecutableQueryT的泛型版本见 SelectQueryFunctionTest.kt#L489。需要留意的是能下推到 SQL 的函数集取决于你所用的方言SQLite、MySQL、PostgreSQL、H2、HSQL 各自支持的标量函数与语法并不相同仓库中各方言模块如 dialects/sqlite、dialects/postgresql即是对应语法解析与代码生成的支持单元。因此在 SQL 中投影要以你目标数据库的方言能力为边界。两种方式怎么选对照与决策维度客户端 Typesafe MapperSQL 侧投影转换执行位置Kotlin 侧逐行调用 Lambda数据库引擎内完成数据量先取回全部投影列再转换只回传需要的结果生成签名fun T select(... , mapper: (cols) - T): QueryT单列直接返回标量多列返回数据类适用场景组合多列构造领域对象、复用既有类型、需要适配器解码后的类型单列标量变换大小写、数值、拼接、聚合结果、过滤后裁剪类型安全参数类型由编译器按列推导返回类型同样由编译器推导代码量需要写 mapper Lambda只需写 SQL决策建议很简单能下推给 SQL 的单列变换、聚合、裁剪优先写在.sq文件里需要把多列组装成自定义对象、或依赖 Kotlin 类型系统做进一步加工的再用 mapper。两者并不互斥——同一个.sq文件里可以同时存在SQL 投影版和默认数据类版两个查询各取所需。实战在 sample 项目中落地仓库自带的示例工程把这两种用法都用上了。在 sample/common/src/iosMain/kotlin/com/example/sqldelight/hockey/ui/PlayerData.kt 中面向 Swift 的桥接对象直接消费生成的查询fun players(teamId: Long) Db.instance.playerQueries.forTeam(teamId).executeAsList()这里forTeam返回数据类列表靠的是默认投影。而在 Android 端 sample/android/src/main/java/com/example/sqldelight/hockey/ui/PlayersActivity.kt#L22同样的查询结果被直接喂给 RecyclerView 适配器players.adapter PlayersAdapter(db.forTeam(intent.getLongExtra(TEAM_ID, -1)).executeAsList())若你想在真实工程里体验 mapper可以在hockeyPlayer.sq中追加一个只取名字的查询并配合 Kotlin 侧组合selectPlayerNames: SELECT player_number, full_name FROM hockeyPlayer;data class PlayerName(val number: Long, val name: String) val names playerQueries.selectPlayerNames( mapper { number, name - PlayerName(number, name) } ).executeAsList()小结SQLDelight 的投影体系遵循默认数据类 → 可选 typesafe mapper → 优先 SQL 投影三层设计默认行为零成本mapper 在需要自定义对象组装时提供完全类型安全的覆盖手段其签名由编译器按投影列逐一推导而凡是能在数据库内完成的变换都应优先写进.sq文件的 SELECT 子句里。理解 SelectQueryGenerator.kt 的生成逻辑与 Query.kt 的运行时执行路径你就能准确预判每个查询会生成怎样的函数签名从而写出既类型安全又高效的查询代码。赞分享后端ORM【免费下载链接】sqldelightSQLDelight - Generates typesafe Kotlin APIs from SQL项目地址https://gitcode.com/gh_mirrors/sq/sqldelight点击查看免费下载相关推荐SQLDelight 自定义投影Custom Projections实战类型安全 Mapper 与 SQL 投影的取舍SQLDelight 自定义投影Custom Projections实战类型安全 Mapper 与 SQL 投影的取舍 本文基于 SQLDelight 官后端ORMSQLDelight 自定义投影Type Projections实战指南从类型安全 Mapper 到纯 SQL 投影SQLDelight 自定义投影Type Projections实战指南从类型安全 Mapper 到纯 SQL 投影 SQLDelight 会根据 .sq后端ORMSQLDelight 类型投影Type Projections与自定义 Mapper 实战指南SQLDelight 类型投影Type Projections与自定义 Mapper 实战指南 SQLDelight 默认会把每条 SELECT 查询的结果后端ORM上一篇Apache Arrow 内嵌 double-conversion 依赖解析版本溯源、更新流程与浮点转换应用下一篇Genkit Dart Google GenAI 插件实战用 Gemini API 完成文本生成、Embedding、图像生成与 TTS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考