f_orm 代码审查实战:27 条缺陷的定位、修复与取舍(fountain ORM 模块)

原创2026-10-13 12:44:141,905 阅读
文章标签:后端Web框架RPC框架微服务认证鉴权ORM缓存消息队列序列化网络可观测性图表库CLI异步编程人工智能大模型LLM 网关AI AgentAgent 编排工具调用MCP 服务MCP ClientsRAGEmbedding多智能体

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 文本、不同参数」的查询互相命中缓存、静默返回错误数据。

三条抵消路径:

  1. SqlExecutor.cj 整个生命周期只有一个 SqlArgs 实例(每次收尾走 clearSql() → args.clear()),而 SqlArgs.clear() 只替换内部 ArrayList,实例身份不变 ⇒ 两次查询的两个 key 指向同一个 SqlArgs;
  2. SqlArgs.== 先 refEq(this, other)(SqlArgs.cj)⇒ 同一实例恒真,args == other.args 恒真;
  3. 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() 每次重算,则退化为「缓存不复用、条目随查询数增长」(不返回错数据但性能劣化)。

修复(两步正解 + 一处必要配套):

  1. SqlExecutor.cj 的 clearSql() 里 args.clear() 换成 this.args = SqlArgs()(换实例:旧实例从此冻结、只被缓存 key 引用),并删除 SqlArgs.clear()(全仓唯一调用点)。为什么这就够了:两条 key 只有在同一个 SqlArgs 实例上才会被 refEq 短路,而同一实例只可能来自「保留窗口」(clearArgsAfterExec: false 期间没有任何重置),该窗口内 SqlArgs 内容只可能被 add 追加,从下标 0 开始的前 n 个参数始终是同一批值,命中旧结果是正确的;
  2. SqlArgs.hashCode() 的记忆与内容同生命周期:add(arg) / add(all:) 内容变更时复位 h = 0(见 SqlArgs.cj 与 L101-L104)——实测必需,否则换实例后缓存永不命中;
  3. 可选:让 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 调整):

  1. 语句级 execute 与结果级 execute 都加 closeBeforeReturning: Bool:消费型路径(first/singleFirst/list/one/…)传 true,语义不变;
  2. 新增迭代器专用通道 executeIterator(= execute(false, …));singleIterator* 与 iterator<T>(mappers) 改走它 ⇒ 返回前不关结果集;
  3. 非事务收尾跳过「已移交」的查询:基座 exec() 的 finally 改为 if (!activeQueryResult) { this.close() }——否则返回迭代器时就把连接还掉了;Statement 保留在 this.stmt 槽位,由 SqlExecutor.close() 统一关闭;
  4. 移交结果集的查询不写结果缓存——迭代器有状态,否则同一「SQL + 参数」的第二次调用会命中缓存拿到同一个已被消费的迭代器;
  5. AbstractQueryResultIterator 新增为 Iterator<T> & Resource 的公共父类,持有 result + statement + executor:close() 顺序固定为结果集 → 语句 → executor.releaseActiveQueryResult()(复位 activeQueryResult + close(),不关语句;语句由迭代器自己关,关失败只记日志)。连接是否归还由 close() 自己的 tx.isNone() 判断:不在事务中时归还连接,在事务中不动它;
  6. 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-):

  1. 新增 private let columns: Array<ColumnInfo>:构造期取一次 result.columnInfos,复用于 columnInfoMap 构建、columnInfos 属性与取值路径 ⇒ 每格的穿透与 toMap() 的重复访问(ORM-L3)一并消掉;
  2. 把「列类型 → 取值」的 18 分支 match(typeName) 从 getOrNull<T>(index) 的逐单元格内联闭包抽成 private static func makeReader(result: QueryResult, typeName: String): (Int64) -> Any,取值器按需构造(不预先为每列建表),行内循环改为数组查表 + list.add;
  3. 第二级 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 不变):

  1. imports.cj 的 emptyLogicalExpr 字面模式提为顶层 private let EMPTY_LOGICAL_EXPR(模块加载时编译一次);
  2. Condition.cj 新增 3 个 private static let 预编译正则(('and|or','and|or') / (',',',') / ('',''),均 [IgnoreCase]),trim 内按 (prefix, suffix) 选常量;
  3. 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.add、RootDAO.arg<I,T>、RootDAO.arg(Any)。分支运行时类型互斥,顺序不影响语义。计时对照:add(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 对两处配置口径做了统一:

  1. orm_databasePoolMaxWaiting 由「Duration.toString() 文本(30s/1m)」改为毫秒整数(30000),与同族时长键统一;默认值不变(30 秒),≤0(如 0)仍是"真无限等待"(映射 Duration.Max)。实现见 ORMConfig.cj。fdemo/boot.sh 的示例值同步为 30000;
  2. 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 模块审查有直接参考价值的方法:

  1. 「代码正确 ≠ 行为正确」要实测:ORM-1 中 h 与 == 代码上确实包含参数,但三个实现细节把这一维度抵消了——审查不能只看单点代码,要追踪对象的身份生命周期(谁持有实例、谁在何时替换内容)。修复后必须用「误命中不复现 + 命中不丢失」双向用例钉住,防止从「返回错数据」修成「缓存永不命中」;
  2. 资源所有权必须显式化:ORM-C1 的教训是「返回值携带资源」时,finally close 的通用模板会误伤——迭代器路径需要独立通道,资源收尾顺序(结果集 → 语句 → 执行器)要固定并有 try (it = …) 的 Resource 语义;ORM-C6 则证明所有权问题要落到驱动实现层面去验证(内存副本 vs 句柄),再决定 ORM 层要不要防御;
  3. 性能优化必须「先量后改」:ORM-6/7 重排分派前先做构件微基准,发现分派只占批量路径成本的小部分,才引出 ORM-N1 对拼接路径的定位;ORM-N3 用四支探针逐层收窄到单个分支,避免盲目优化;ORM-5 的修复前后输出逐字符一致对照,保证「优化不改语义」;
  4. 「已知开销」与「设计目的」要有归档机制:ORM-3/4 明确保留并登记理由(含四家驱动调研证据),ORM-C5 复核为设计目的后补 README §11.5 文档与用例——审查报告不仅要记「修了什么」,还要记「为什么不修」,防止后人重复评估;
  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 复现本文记录的全绿基线。

登录后查看全文
fountain