f_orm 代码审查实战:27 条缺陷的定位、修复与取舍(fountain ORM 模块)
f_orm 代码审查实战:27 条缺陷的定位、修复与取舍(fountain ORM 模块)
本文是 fountain 开源仓库中 f_orm 模块代码审查报告的完整梳理。报告源自对 f_orm / f_mvc / f_bean / f_aspect 四个模块的联合审查(审查分支 review/orm-mvc-bean-aspect),本文聚焦 f_orm 部分:共 27 条审查条目,覆盖严重 3 条、中等 7 条、低危与待验证 17 条(含本会话新增 3 条),并逐一记录每条从「问题定性 → 定位链 → 修复方案评估 → 用例与验证 → 最终处置」的完整闭环。读完本文,你将理解 ORM 模块最热的代码路径上「结果缓存、迭代器资源生命周期、逐单元格类型分派、批量参数拼接」四类核心问题的成因与修法,以及一个审查团队面对「设计如此」与「已知开销」时的判断标准。
1. 审查概览:范围、基线与处置状态
1.1 审查来源与编号约定
本报告由 .autocode/bugs/bug.md 按模块拆分而来,原报告名为《代码审查报告:f_orm / f_mvc / f_bean / f_aspect》,审查基线提交为 5a5d6cf3。条目编号沿用原报告(§x.y 不变),便于与代码注释、其他报告交叉引用;编号不连续属正常——其余编号属于其他模块,总索引见 bug.md §0 的「编号索引」。
1.2 条目分布与最终状态
截至 2026-10-06,f_orm 模块 27 条条目全部有明确处置结论:
| 等级 | 条目 | 处置 |
|---|---|---|
| 严重(3) | ORM-1(§1.1)、ORM-C1(§1.5)、ORM-2(§1.13) |
✅ 全部已修复 |
| 中(7) | ORM-C2、ORM-C5、ORM-3、ORM-4、ORM-5、ORM-6、ORM-7 |
✅ 修复 3 条;❌ 误判 1 条;⏸ 保留 2 条;◐ 部分修复 2 条 |
| 低危(§3.1,10) | ORM-C3/C4/L1/L2/L3/L4/L5/L6/L7/L10/L11 |
✅ 5 条已修、◐ 2 条部分修、⏸ 4 条不修 |
| 待验证(§3.2,4) | ORM-L3/L8/L9/C6 |
已全部处置(L3 随 §1.13 消掉、L8/L9 已修、C6 完成定性) |
| 本会话新增(§3.3,3) | ORM-N1/N2/N3 |
✅ N1a/N2/N3 已修、N1b 落地、N1c 不做 |
里程碑:2026-10-06 配置口径调整后(orm_databasePoolMaxWaiting 改毫秒整数、ORMConfig.get<T> 改 tryParse),长期红色的 ORMConfigTest.testPoolMaxWaiting 转绿,全量基线首次全绿:cjpm test TOTAL 62 / PASSED 62 / FAILED 0 / ERROR 0。
2. 严重缺陷:正确性与性能的底线问题
2.1 ORM-1:结果缓存的键只剩 SQL 文本一维
问题:代码上 SqlCacheKey 的 h 与 == 都包含了参数(见 SqlCacheKey),但 args 这一维度被三处实现抵消,key 的实际区分能力只剩 SQL 文本,导致「同 SQL 文本、不同参数」的查询互相命中缓存、静默返回错误数据。
三条抵消路径:
- SqlExecutor.cj 整个生命周期只有一个
SqlArgs实例(每次收尾走clearSql()→args.clear()),而SqlArgs.clear()只替换内部ArrayList,实例身份不变 ⇒ 两次查询的两个 key 指向同一个SqlArgs; SqlArgs.==先refEq(this, other)(SqlArgs.cj)⇒ 同一实例恒真,args == other.args恒真;SqlArgs.hashCode()把结果记忆在h字段(SqlArgs.cj),而clear()/add()都不复位 ⇒ 同一 executor 构造出的所有 key,h里的参数分量都等于第一次算出的那份,h == other.h恒成立。
触发条件与后果:缓存需跨查询存活——execute 的非事务路径执行完就 close(),而 close() 里的缓存清理带 tx.isNone() 守卫(SqlExecutor.cj,事务内直接跳过)⇒ 事务内同一 SQL 文本的第二次调用直接返回第一次的结果(静默错数据);若两次期望的 T 不同,则抛 type of cached data with key ... does not match。边界情况:若 HashBuilder().build() 恰好得 0,hashCode() 每次重算,则退化为「缓存不复用、条目随查询数增长」(不返回错数据但性能劣化)。
修复(两步正解 + 一处必要配套):
SqlExecutor.cj的clearSql()里args.clear()换成this.args = SqlArgs()(换实例:旧实例从此冻结、只被缓存 key 引用),并删除SqlArgs.clear()(全仓唯一调用点)。为什么这就够了:两条 key 只有在同一个SqlArgs实例上才会被refEq短路,而同一实例只可能来自「保留窗口」(clearArgsAfterExec: false期间没有任何重置),该窗口内SqlArgs内容只可能被add追加,从下标 0 开始的前 n 个参数始终是同一批值,命中旧结果是正确的;SqlArgs.hashCode()的记忆与内容同生命周期:add(arg)/add(all:)内容变更时复位h = 0(见 SqlArgs.cj 与 L101-L104)——实测必需,否则换实例后缓存永不命中;- 可选:让 key 持冻结快照(真拷贝
clone()),只为命中率。
探针实测证据(做了 ①②、未做 ③ 时):两次 get 同 sql、同参数内容,keyHash 却分别是 6578699273789510219 与 5544947046349531277;补上 ③ 后两侧哈希一致、hit=true、fires=1。失败模式提醒:h 的记忆必须与内容同生命周期——只做 ①② 会从「返回别的参数的结果」变成「缓存永不命中」(每次查询都多打一次库),两者都不可接受。
用例:SqlResultCache_test.cj 三条——testSameSqlDifferentArgsMustNotHitCache(不同参数不得串缓存)、testSameSqlSameArgsStillHitsCache(同参数必须命中,用 mock 调用计数断言 = 1)、testCacheKeyMustDependOnArgsContent(键只由 SQL + 参数内容决定)。修复前基线(临时 git stash 三处改动):首条 FAILED,Assert Failed: Some(2) != values[1] 且 mock 只被调用 1 次 ⇒ 误命中复现 ✓;修复后 3/3 PASSED。
2.2 ORM-C1:iterator/singleIterator 在返回前就把结果集关掉了
问题:iterator/singleIterator 把迭代器包在 execute<T> 里返回,而该重载的 finally 是 r?.close() ⇒ 方法一返回底层结果集已关闭,activeQueryResult 也随之复位。f_mockdb 的 QueryResult.close() 是空实现所以单测看不出来,但真实驱动下 close() 后 next() 的行为未知。
修复(6 处,2026-10-04 + 10-05 调整):
- 语句级
execute与结果级execute都加closeBeforeReturning: Bool:消费型路径(first/singleFirst/list/one/…)传true,语义不变; - 新增迭代器专用通道
executeIterator(=execute(false, …));singleIterator*与iterator<T>(mappers)改走它 ⇒ 返回前不关结果集; - 非事务收尾跳过「已移交」的查询:基座
exec()的finally改为if (!activeQueryResult) { this.close() }——否则返回迭代器时就把连接还掉了;Statement 保留在this.stmt槽位,由SqlExecutor.close()统一关闭; - 移交结果集的查询不写结果缓存——迭代器有状态,否则同一「SQL + 参数」的第二次调用会命中缓存拿到同一个已被消费的迭代器;
- AbstractQueryResultIterator 新增为
Iterator<T> & Resource的公共父类,持有result+statement+executor:close()顺序固定为结果集 → 语句 →executor.releaseActiveQueryResult()(复位activeQueryResult+close(),不关语句;语句由迭代器自己关,关失败只记日志)。连接是否归还由close()自己的tx.isNone()判断:不在事务中时归还连接,在事务中不动它; next()(QueryResultIterator.cj)读尽即自动close()。
2026-10-05 调整消除了残留:迭代器改为持有 Statement(原先只持 executor),事务中移交出去的语句不再依赖 SqlExecutor.stmt 单槽位(该槽位被同事务下一条 SQL 覆盖会漏关),迭代器自己就是唯一持有者;SqlExecutor.stmt 槽位只作「迭代器一直未关闭」时的兜底。顺带:QueryMappers.iterator(result) 签名改为 iterator(result, executor)。
用例:QueryResultIterator_test.cj 5 条——非事务返回后可逐行读、读尽自动关闭且 Statement+Connection 已关;事务中 close() 关结果集与语句、连接仍在(testIteratorCloseInTransactionKeepsConnection)、同一事务可继续查询,事务结束后连接才关;未关闭的迭代器拦住同 executor 的后续查询;try (it = …) 自动关闭;singleIterator<T>(column:) 按列名取值。修复前基线:5/5 FAILED,首条断言即 Assert Failed: (false == it.isClosed()) ⇒ 与问题描述一致 ✓。
2.3 ORM-2:逐单元格做运行时类型分派 + 字符串 typeName 匹配
问题:QueryMappers.map() 对每一行每一列调用取值路径(QueryResultWrap.cj 的修复后形态),调用频率 = 行数 × 列数,是模块内最热的代码。修复前每个单元格都要:一次 columnInfos 属性访问、一次大 match(Any 类型判定)、未命中时又一次 match(None<T>) 链。
修复(1 文件 33+/29-):
- 新增
private let columns: Array<ColumnInfo>:构造期取一次result.columnInfos,复用于columnInfoMap构建、columnInfos属性与取值路径 ⇒ 每格的穿透与toMap()的重复访问(ORM-L3)一并消掉; - 把「列类型 → 取值」的 18 分支
match(typeName)从getOrNull<T>(index)的逐单元格内联闭包抽成private static func makeReader(result: QueryResult, typeName: String): (Int64) -> Any,取值器按需构造(不预先为每列建表),行内循环改为数组查表 +list.add; - 第二级
match(list[index])(类型窄化 /convertFromString兜底 / 报错口径)一行未动,语义不变。
为什么 makeReader 必须是 static:仓颉不允许构造期调用实例方法(探针实测报 'x' is not allowed to be accessed before all member variables are initialized)。makeReader 的分支覆盖 SqlChar/SqlVarchar/String/…、SqlClob/SqlBlob/InputStream、SqlBinary/Array<Byte>、SqlDecimal、SqlBool、整型族、浮点族、DateTime、Duration,未知 typeName 走 String 兜底。
用例:QueryResultWrap_test.cj 5 条——按索引/列名取值同源、未知列名与越界索引 → None;18 个取值器分支与别名全覆盖;indexStartsWith 非 0 的驱动逻辑列 ↔ 物理列映射;驱动给 String、请求数值类型走转换兜底,不可解析抛 ORMException;next() 按行重置取值缓存。前后对照:把文件临时还原为 HEAD 再跑,新用例 5/5 PASSED(钉的是语义不变,故两边都必须过)。计时对照(探针 orm2_mapList_bench.cj,20 列 × 2000 行):mockdb 口径下前后无可辨差异(mock 的 columnInfos 本就是缓存数组);本条实际收益是「不再逐格穿透 result.columnInfos」+ 列信息只取一次;真实驱动下是否显著取决于各驱动 columnInfos 是否每次分配。
3. 中等缺陷:七条逐项处置
3.1 ORM-C2:SingleColumnIterator 忽略 column 参数(✅已修复)
QueryResultIterator.cj 的 next() 修复为:column 非空时走 result.getOrNull<T>(column),否则走 index(默认 0);两者同时给出时以列名为准(与 singleFirst<T>(column:) 的取值口径一致)。修复前 singleIterator<String>('name') 实际读第 0 列(静默读错列)。用例 testSingleIteratorByColumn 钉住同一行第 0 列 id=7、第 1 列 name='bob',singleIterator<String>('name') 必须取到 bob;README §13.4 的「已知问题」条目已删除并改写为正确语义。
3.2 ORM-C5:argInSql 把任意 ToString 值原样拼进 SQL(❌误判,非缺陷)
复核结论:判定为设计目的,不修改行为。argInSql 是显式打开的「把值内联进 SQL 文本」开关,用于固定列名 / 表达式 / 驱动认得的关键字这类必须内联的受控内容;「绕过参数化」正是它的定义,不是缺陷。本轮只做文档与用例:
- README:§11.2/§11.3/§11.4 的
argInSql条目均标注「见 11.5,谨慎使用」;新增 §11.5「argInSql:把值直接拼进 SQL(谨慎使用)」,写明调用时实际会发生什么(ToString值按toString()原样拼接、不转义、不加引号、不绑定;非ToString值回落参数绑定;IN/NOT_IN逐元素判定、可内联与绑定混用;ChooseCondition的()只写片段)与后果边界(注入面、字符串要自带引号、值里别含?、默认路径仍是参数化); - 用例:ArgInSql_test.cj 7 条,借
MOCKDB.execution观察实际发给驱动的 SQL 与绑定参数:默认参数化 /argInSql+ToString内联(String 与 Int64)/argInSql+InputStream仍走?绑定 /argInSql+不可绑定的非ToString值抛SqlException: Unsupported data type/IN混用(in (1,?))/LoopCondition内联 /ChooseCondition的命中分支与()分支。
口径补正(写用例时实测):argInSql 下「非 ToString 值回落绑定」并非对所有类型成立——绑定走 SqlExecutor.add(Any):ToString → 按运行时类型绑定或转 toString() 文本、InputStream → 绑定、其它类型直接 throw SqlException("Unsupported data type")。README §11.5 的表格与边界按真实口径写成。
3.3 ORM-3 / ORM-4:决定不修的已知开销(⏸保留)
ORM-3:每条非事务 SQL 的 close() 都全量清扫脏字段注册表。成本 = O(已注册类型数) 次哈希查找 + 等量分配,位置在 DirtyTag.cj 的 clearAll()(遍历所有已注册 PO 类型并逐个新建 DirtyTag 写回 ConcurrentHashMap)。两轮方案评估后均否决:
- 方案 A(加静态集合,只清「曾置过
beforeDirty」的类型):setBeforeDirty<T>()是每条加载 PO 的查询都要走的热路径,加集合等于给它加一次写;且会多出一份必须与beforeDirty永远同步的状态——一旦漂移,setDirtyField会静默漏记脏字段(UPDATE(dirty: true)少更新列),代价大于省下的开销; - 方案 C(把
beforeDirty挪到引用型 holder、clear就地复位):收益不足以动这段代码。
ORM-4:每次执行都重新 prepareStatement,借连接还额外 select 1。三个子项逐项拍板:①借连接校验(checkOnBorrowing 默认 true,每次借出多打一条 orm_databasePoolCheckSql,默认 select 1)不改默认值、不加文档说明(README §3.3 配置表已列出);②默认值改 false 属行为变更,明确不做;③按 SQL 文本缓存 Statement,技术可行但工程上不值得在 f_orm 层做。
关于③的四家驱动源码调研(决定「Statement 能否缓存」):
| 驱动 | 可复用? | 关键证据 | 对 f_orm 层缓存的意义 |
|---|---|---|---|
ZhaoJun-zfh/postgres-driver |
是 | 驱动自带 LRU 语句缓存 PgStatementCache,容量 PgDsn.statementCacheSize 默认 32,DDL 后必须 clearStatementCache() |
零收益且重复:f_orm 再加一层只是多一份缓存 |
aibrary/pgsql-driver |
是 | 构造即 Parse + Describe;执行后 resetParams() ⇒ 每次必须全量重绑;全仓无语句缓存 |
缓存有真实收益(省每次 Parse/Describe 往返),但需 f_orm 自建服务端命名语句的生命周期管理 |
Cangjie-SIG/mysql-driver |
是 | CRUD 首关键字 → 真服务端 prepare;执行后参数重置为全 None(漏绑静默发 NULL);close() 二次调用抛 SqlException |
缓存能省每次 COM_STMT_PREPARE,但需 isClosed() 守卫 + 全量重绑不变量 |
Cangjie-SIG/mariadb-driver |
是 | 与 mysql 版同源,客户端版多一个拼好 SQL 的文本缓存 | 同 mysql 的结论 |
四家共同前提:①结果集都一次性缓冲;②语句是服务端会话资源 ⇒ 缓存必须有上限与淘汰,且连接销毁、DDL、回滚时失效;③参数必须每次全量重绑(f_orm 现有 args.set(stmt) 即全量);④二次 close() 在 postgres 两家幂等、在 mysql/mariadb 抛错 ⇒ 关闭前一律 isClosed() 守卫。结论:f_orm 层做等于「对 ZhaoJun postgres 重复实现、对其余三家把驱动已有的生命周期语义重写一遍」,且真机验证缺位 ⇒ 不做;将来若要做,直接照 ZhaoJun 驱动那套(LRU + clearStatementCache 语义)移植。
3.4 ORM-5:每次拼条件片段都「动态构造正则 key + 查缓存 + 临时串」(✅已修复)
改动(3 文件 36+/3-,公开 API 不变):
- imports.cj 的
emptyLogicalExpr字面模式提为顶层private let EMPTY_LOGICAL_EXPR(模块加载时编译一次); - Condition.cj 新增 3 个
private static let预编译正则(('and|or','and|or')/(',',',')/('',''),均[IgnoreCase]),trim内按(prefix, suffix)选常量; - TableClause.cj 新增 2 个顶层
private let,appendPartial命中即用常量。
模式文本与原先插值结果逐字一致,未列出的自定义组合仍走原动态构造。前后对照:同一矩阵(trim 4 组合 × 17 输入)修复前后各 118 行输出,规范化后逐字符一致。计时对照(同机同轮取最优):Condition.trim 循环(20000 × 17 输入 × 2 组合)5.28s → 3.04s(≈1.7×);emptyLogicalExpr 循环(100000 × 2 次)613ms → 41.5ms(≈14.8×)。用例:ConditionTrim_test.cj 7 条。报告原文建议的「trim 用 trimAscii 手工裁剪」未采用——手工裁剪要复刻「正则替换成单个空格 + alternation 未分组」的边界语义,风险高于收益。
3.5 ORM-6 / ORM-7:批量路径逐元素大 match 的分派重排(◐部分修复)
IN/批量 insert 的参数规模就是业务集合大小(可上千)。先量后改(探针 ORM67Probe_test.cj,N=1000 元素):批量路径逐元素进 SqlExecutor.add<T>(绑定值为 Any 时),成本随分支位次增长:add(Any=Int64)(原第 8 支)86ns/元素、add(Any=String)(原第 16 支)264ns/元素;同轮地板 add(Int64)(类型化、无分派)49ns/元素 ⇒ 每个失败的类型检查 ≈13ns。
改动:三处 40+ 分支 match 按「绑定频率」重排(Int64/String/DateTime/Bool/Decimal/UInt64 → 其余标量 → ?T 组 → 兜底):SqlExecutor.addadd(Any=Int64) 86 → 62ns/元素(−28%)、add(Any=String) 264 → 89ns/元素(−66%)、arg<I,T>(ArrayList<Int64>) 380 → 355ns/元素(−7%);代价:add(Any=Bool) 62 → 77ns(Bool 由第 1 支降至第 4 支,若业务大量绑 Bool 可再调顺序)。但批量路径总成本几乎没动(MeetCondition.IN 212 → 190ns、LoopCondition.done() 844 → 861ns)⇒ 分派只占小部分,大头在拼串/闭包/装箱,另立 §3.3 ORM-N1。arg(Any) 原位序里 Float16/?Float16 各出现两次、第二次恒不可达,重排一并去掉。用例:SqlExecutorArgBranches_test.cj 21 个类型逐一走 arg(Any)/add(Any)。
4. 低危与待验证条目
4.1 §3.1 十条低危条目的处置(2026-10-06 全部处置)
| 编号 | 处置 | 说明 |
|---|---|---|
ORM-C3 |
✅已修 | 删除 SqlArgs.clone()(它只是换个壳、与本体共享同一个 ArrayList,不是快照);唯一调用点 SqlExecutor.logMsg 改为直接引用原对象(见 SqlArgs.cj 注释) |
ORM-C4 |
✅已修 | SqlExecutor.sql 的 setter 先规范化再做长度判断,短于 6 个字符显式抛 ORMException(见 SqlExecutor.cj);DatabasePool 的 checkSql 同口径,显式抛 ConnectionException(见 DatabasePool.cj) |
ORM-L1 |
◐部分修 | 前缀判断不再做第二次 trimAscii()(sql_ 已由 trimAsciiBlanks() 去掉首尾空白);注:startsWithIgnoreAscii 在 String 上并不存在,原建议不可用。blankRegex 的全串规范化保留——缓存键用的就是规范化后的 sql_ |
ORM-L2 |
◐部分修 | args.clone() 已随 ORM-C3 去掉;日志闭包保留——它是「只在真要输出时才插值」的惰性形态,每次执行只多一次闭包分配 |
ORM-L6 |
✅已修 | 结果缓存改为只缓存 SELECT:execute 的缓存分支加 isSelectStatement(sql) 判断(SqlExecutor.cj),非 SELECT 连 cache key 都不构造(key 会对 SqlArgs 求哈希,BLOB 参数在旧实现里被整体格式化成字符串 ⇒ 等大内存峰值) |
ORM-L7 |
⏸不修 | 每线程一份 dirtyFields 是 ThreadLocal 的有意设计;线程池下驻留量级「每线程 × 每 PO 类型一个字段名 HashSet」属可接受卫生问题 |
ORM-L10 |
⏸不修 | 事务钩子注册只在初始化时执行一次 |
ORM-L11 |
⏸不修 | getOption/getAllOptions 只在初始化时执行一次 |
ORM-L4 |
✅已修 | 删除 SchemaFinderMediator.generate() 里构造后从未使用的 existingTableNames(真正使用的是 knownNames) |
ORM-L5 |
✅已修 | 删除 parseSqlFromObject 里求值后未使用的 T.dataFields();已确认 ObjectFields.getObjectFields 只是 allFields 的 computeIfAbsent 记忆化,无测试依赖「在此处被触发」 |
用例:SqlExecutorStatement_test.cj——①短 SQL('sel'、'')必须抛 ORMException、正常 SQL 不受影响;②只缓存 SELECT(两次相同非 SELECT ⇒ 执行 2 次、两次相同 SELECT ⇒ 执行 1 次)。验证:cjpm test TOTAL 60 / PASSED 59 / FAILED 0 / ERROR 1。
4.2 §3.2 四条待验证条目的处置
| 编号 | 处置 | 说明 |
|---|---|---|
ORM-L3 |
✅已消掉(随 §1.13) | QueryResultWrap 已把 result.columnInfos 收成构造期取一次的 private let columns(QueryResultWrap.cj);只余一条观测项:真实驱动的 columnInfos 是否每次新分配 |
ORM-L8 |
✅已修 | PooledConnection 增 private let returned = AtomicBool(true):借出时 activate() 里 store(false),close() 首行 returned.compareAndSwap(false, true),CAS 失败(已归还过/从未借出)抛 ConnectionException('The database connection was returned multiple times.')(见 DatabasePool.cj)。池侧没有身份去重(SyncDeque 只对「重复归还」告警、不拦)⇒ 必须在归还这一步拦住,否则池里会出现两个指向同一连接的节点、两个借用者可能同时拿到它 |
ORM-L9 |
✅已修 | 新键 orm_connectingTimeout(毫秒;按驱动覆盖 <driver>_orm_connectingTimeout),默认 5000ms(ORMConfig.cj);SqlExecutor 增 waitConnecting(),case Connecting 从「无 sleep、无超时的死转」改为有上限的等待,超时抛 ConnectionException('connecting is timeout')。起算点与上限只取一次;配置读取只在真进入该分支时发生,不落在每次执行 SQL 的热路径上 |
ORM-C6 |
✅定性 | 见下「大对象与流的所有权」 |
用例:PooledConnection_test.cj(二次 close 抛 ConnectionException、归还回调只收到 1 次、再次借出后归还仍合法);SqlExecutorConnectingTimeout_test.cj(假驱动状态永停 Connecting,stuck_orm_connectingTimeout=50ms ⇒ 抛 connecting is timeout 且耗时 ≥40ms)。
4.3 ORM-C6:InputStream(BLOB/CLOB)的所有权与生命周期
写路径(流是调用方的):InputStreamSqlArg.set → setValue<InputStream> → Statement.set<InputStream>(index, value),ORM 只是转交驱动,代关是错的;缺的是一句约定:流必须活到本次 SQL 真正执行完(驱动多在 execute 时才读),并由调用方关闭。
读路径(流是驱动的):QueryResultWrap.getOrNull<InputStream>、toMap() 直接把流交给调用方;QueryMapperConverter 两处 StringReader(x).readToEnd() 只是读它——StringReader 自身不持有 fd,不关 reader 不会泄漏 ORM 自己的句柄;关它反而会误关驱动/调用方的流。
五驱动 V2 调研结论:逐个查了 get<InputStream> 值的实际来源——mariadb-driver 把行数据 copyTo 成 ByteBuffer 副本;mysqlclient-ffi 的 BLOB 映射为 SqlArrayByte、以 getOrNull<InputStream> 请求会抛 data type error;pgsql-driver、postgres-driver 对 get<T> 的 InputStream 请求直接抛 SqlException;opengauss-driver 也是新建 ByteBuffer 拷贝。⇒ 没有任何一个驱动交出「绑定结果集/C 句柄的流」,InputStream 值实际是内存副本。据此修正定性:①「模块内句柄泄漏」不成立 ✓;②三个生命周期陷阱(结果缓存留住流 / PO 字段跨行持有流 / toMap() 交出流)在现有驱动上均无风险 ✓;③真正的问题是大对象内存,峰值发生在驱动读行时(整块 BLOB 已在内存里)⇒ ORM 侧无解,出路只有:不入库(对象存储/文件 + 库里存引用)、服务端按块查(substring(col, off, len))、或换支持流式大对象的驱动。
处置(按作者决定):
- 陷阱 1 → B 方案落地:
QueryResultWrap增hadStream(在取数路径上按「实际读出的单元格」置位,见 QueryResultWrap.cj),SqlExecutor.execute在取数完成后写入lastResultHadStream⇒ 含流的结果不进结果缓存(防御性正确性改动,护栏 SqlResultCacheStream_test.cj); - 陷阱 2 → A 方案落地:README 新增 §13.6「InputStream(BLOB/CLOB):所有权、生命周期与大对象」——写入侧(只转交不关闭 + 必须活到 SQL 执行完 + 不得补 close)、读回侧(五驱动实测表)、大对象四条出路、含流不进缓存、接第三方驱动前重跑核查;
- 驱动侧问题:数据库允许 4GB 级 BLOB,而四个驱动都把它整块转储成内存副本 ⇒ 属驱动实现问题,ORM 侧无解;建议向驱动仓反馈或单独立条登记。前提提醒:以上结论依赖「驱动给内存副本」这一实测 ⇒ 接入第三方驱动时应重跑核查;反向风险(不得代关调用方的流)已用注释 + InputStreamOwnership_test.cj 钉死。
5. 本会话新增条目的闭环(2026-10-05/06)
5.1 ORM-N1:批量条件/参数构造的每元素成本(中|性能)
修正认知:原判断里「IN 的拼串是大头」不成立——IN 用的是 std StringBuilder(每次 append 仅 ≈8ns),真正被拼接拖住的是 arg<I,T> 与 LoopCondition.done()。构件微基准(N=200000):std StringBuilder.append 8/9ns;StringGenerator.append 的配方(ArrayList<Byte>.add(all: 1字节))78/25ns ⇒ 每次 StringGenerator.append 比 std StringBuilder.append 贵 5–12 倍,根因是它用 ArrayList<Byte> 当缓冲、逐次按字节搬运。
N1a(已修):①RootDAO.arg<I,T> 把每元素的 append(',') + 循环尾 append('?') 合并成一次 append(',?');②LoopCondition.done() 的分隔符 ' ${delimiter} ' 循环外预拼一次、frag 为空时跳过 append(frag)(见 LoopCondition.cj)。⇒ arg<I,T> 355 → 257ns/元素(−28%)、done() 861 → 575ns/元素(−33%)。用例 ArgSqlText_test.cj 8 条批量路径的 SQL 文本逐字节对齐改动前实测字面量,钉住等价性;ArgBindCount_test.cj 钉住「占位符个数 == 绑定参数个数」。
N1b(落地为 P0 + B,替代「自管字节缓冲」):原方向是让 StringGenerator 的缓冲变快,核对后不成立——仓颉的泛型实例化落在使用方模块,ArrayList<Byte> 与自管数组吃同一个优化档位,差的是「编译档位」不是「数据结构」。改为两处改动:
- P0 StringGenerator.append(r: Rune)(新重载):ASCII(SQL 拼接里的
?,()等)用r.position()码点直写——不分配、走单元素add;非 ASCII 才建 4 字节暂存区走Rune.intoUtf8Array。微基准(N=200000 取 6 轮最优):新路径 35ns/次、旧路径 141ns/次 ⇒ 单次省 106ns。踩过的坑:先做的「无条件先建 4 字节局部数组」版反而更慢(每字符一次小对象分配把收益吃成负的),已改成 ASCII 直写; - B
RootDAO.arg<I,T>占位符整段预拼:该函数的 frag 只由元素个数决定(' (' + '?' + ',?'×(n-1) + ')';match 各分支只做绑定、arg(x)的返回值一律丢弃),故循环里只n++,尾部用' (?${",?" * (n - 1)})'一次拼出。计时:arg(ArrayList<Int64>)257 → 149ns/元素(−42%),且 −108ns 与「一次单字符 String append = 109ns/次」吻合到 1ns ⇒ 收益来源可解释。护栏 StringGeneratorRune_test.cj(StringGenerator的首个专属用例:新重载 vs 旧路径逐字节等价,覆盖 1–4 字节 UTF-8)。
N1c(⏸决定不做):方案为「批内首元素定型 + 同型直调类型化 add + 异型永久回退」。不做的依据:按实测分布,逐元素真正付「两层 match」的只有 DSL 侧循环(MeetCondition.IN/NOT_IN 里 v: T 泛型 ⇒ 只能走 add(Any),≈75–86ns/元素),换成类型化直调仅省 14–27ns/元素(≈10–13%);而 arg<I,T> 的热类型(Int64/String)本就在其 match 最前(开销仅 4–26ns/元素),接 binder 后每元素多一次闭包调用 + 一次单分支检查 ⇒ 净值 ≈±0。
5.2 ORM-N2:Float32 经参数绑定路径静默丢参(中|正确性,✅已修复)
根因(两层):①Float32SqlArg.set 写成 setValue<Float64>(statement, value),而 value 是 Float32——setValue 的 case x: T / case x: Option<T> 是运行时类型检查且不做隐式数值转换,Float32 值命不中 case Float64,于是落到兜底;②兜底只构造异常却没有 throw(见 SqlArg.cj)⇒ 既没绑定、也没报错。
后果面:SqlExecutor → SqlArgs → SqlArg.set → Statement.set/setNull 是 ORM 把值交给驱动的唯一通道,所以这不是「驱动转换问题」,而是参数根本没交给驱动(任何驱动实现都一样);真驱动下该 ? 会表现为「未设置/NULL 绑定」。凡会构造 Float32SqlArg 的入口都受影响:add(Float32)、add(Any) 的 Float32 分支、RootDAO.arg(value: Float32)、IN(...) 泛型路径、SqlArg.new<Float32>;?Float32 的 Some 路径同理。
改动(两行):①Float32SqlArg.set → setValue<Float32>(statement, value)(见 SqlArg.cj,与 Float16SqlArg 的 setValue<Float32>(statement, Float32(value)) 同一约定);②setValue 兜底补 throw SqlArgException——它是「T 与值类型不匹配」的唯一防线。证据(自制 Statement 记录器):修复前 SqlArgs.add(Float32) → calls=0;修复后 1 次 set<Float32>(0)。用例:SqlArgBinding_test.cj 18 个类型逐一断言「恰好一次 Statement.set<T>」+ 负例 MismatchSqlArg(故意让 T 与值类型不符)断言必须抛 SqlArgException。
5.3 ORM-N3:arg(value: Any) 被首支 case x: Data 拖慢两个数量级(中|性能,✅已修复)
现象:arg(Any=Int64) 实测 12.1–13.4µs/元素,而同轮同形的 add(Any=Int64) 只 75ns、类型化 arg(Int64) 45–56ns ⇒ 既不是 Any 入口的通病,也不是绑定路径的问题。
定位链(四支探针):①与 args 增长无关;②单分支 match 不慢(Any→Int64 命中 57ns);③同形复刻(41 分支,省略首支 Data)只要 48ns ⇒ 锁定在某个具体分支;④复刻对照——case x: Data 在首位 12.45µs、挪到标量之后 79ns(差 158×);⑤命中分支检查——Int64/String/true 都不落 Data 分支 ⇒ 纯检查开销。
根因:case x: Data(f_data 的接口模式,Data <: FromToData & ToString & DataParsable<Data>)在 Any 上的运行时检查本身极贵(对 Int64 值 ≈12µs/次、String ≈1.2µs/次),而它排在 arg(value: Any) 的第一支 ⇒ 每个非 Data 值都要先白付这笔钱。形态上看像仓颉运行时「值类型 → 大接口层次」conformance 检查的性能问题。
改动(一行):把 case x: Data => arg(x) 从首位挪到 ?T/?Any 之后、兜底 throw 之前(见 RootDAO.cj)。语义安全依据:Data 包装类(DataString/DataReal/DataDict/DataList/DataTuples/DataInputStream…)都不是标量类型,标量分支的 pattern 不可能命中它们。计时对照:arg(Any=Int64) 13407 → 92ns/元素(−99.3%,146×)、arg(Any=String) 1268 → 110ns。用例 ArgAnyBinding_test.cj:21 个类型(含 DataString('x')/DataReal(Int8(1)) 两个包装值)经 arg(Any) 必须命中具体分支返回 '?';相对计时护栏 arg(Any=Int64) ≤ 10×arg(Int64)+1µs(修复前 ≈270× 必被拦住,修复后实测 1.02×)。同模式另一处(f_mvc/src/RequestMeta.cj 也有一处 case x: Data)另立条目,本次未动。
6. 配置口径调整:全量基线首次全绿
2026-10-06 对两处配置口径做了统一:
orm_databasePoolMaxWaiting由「Duration.toString()文本(30s/1m)」改为毫秒整数(30000),与同族时长键统一;默认值不变(30 秒),≤0(如0)仍是"真无限等待"(映射Duration.Max)。实现见 ORMConfig.cj。fdemo/boot.sh的示例值同步为30000;ORMConfig.get<T>由T.parse改为T.tryParse(ORMConfig.cj):配置写错值退回default,不再抛DataParsableException。
效果:长期红色的 ORMConfigTest.testPoolMaxWaiting 转绿(它钉的就是 45s→45s、1m、0s→Duration.Max、abc→默认 30s)⇒ 全量基线首次全绿:cjpm test TOTAL 62 / PASSED 62 / FAILED 0 / ERROR 0。兼容性提醒:老配置里 orm_databasePoolMaxWaiting=30s 会 tryParse 失败而静默退回默认 30 秒(不再是解析崩溃)⇒ 部署时需改成毫秒。
7. 方法论沉淀:一份可复用的 ORM 代码审查清单
回顾这 27 条,可以提炼出几条对同类 ORM 模块审查有直接参考价值的方法:
- 「代码正确 ≠ 行为正确」要实测:
ORM-1中h与==代码上确实包含参数,但三个实现细节把这一维度抵消了——审查不能只看单点代码,要追踪对象的身份生命周期(谁持有实例、谁在何时替换内容)。修复后必须用「误命中不复现 + 命中不丢失」双向用例钉住,防止从「返回错数据」修成「缓存永不命中」; - 资源所有权必须显式化:
ORM-C1的教训是「返回值携带资源」时,finally close的通用模板会误伤——迭代器路径需要独立通道,资源收尾顺序(结果集 → 语句 → 执行器)要固定并有try (it = …)的Resource语义;ORM-C6则证明所有权问题要落到驱动实现层面去验证(内存副本 vs 句柄),再决定 ORM 层要不要防御; - 性能优化必须「先量后改」:
ORM-6/7重排分派前先做构件微基准,发现分派只占批量路径成本的小部分,才引出ORM-N1对拼接路径的定位;ORM-N3用四支探针逐层收窄到单个分支,避免盲目优化;ORM-5的修复前后输出逐字符一致对照,保证「优化不改语义」; - 「已知开销」与「设计目的」要有归档机制:
ORM-3/4明确保留并登记理由(含四家驱动调研证据),ORM-C5复核为设计目的后补 README §11.5 文档与用例——审查报告不仅要记「修了什么」,还要记「为什么不修」,防止后人重复评估; - 配置口径统一能消除长期红色用例:时长键统一为毫秒整数 +
tryParse静默回退默认值,让测试基线从「一直挂着一条环境相关 ERROR」走向全绿,也顺带定义了「配置写错 = 用默认值」的产品语义。
以上所有条目对应的修复、用例与验证均落在当前仓库 f_orm 模块(基座 SqlExecutor.cj、包装层 SqlArg.cj 与 SqlArgs.cj、结果包装 QueryResultWrap.cj、配置入口 ORMConfig.cj)以及迁移后的连接池 DatabasePool.cj,配套测试覆盖在 f_orm/src/base/ 与 f_orm/src/wrap/ 下的各 *_test.cj 文件中,可自行运行 cjpm test 复现本文记录的全绿基线。