


修改高性能数据库代码,不损害速度和兼容性
让 AI 修改横跨 Java、SQL、Rust、原生代码和 CI 的高性能数据库时使用。它规定代码写法、NULL 处理与内存清理、查询测试、失败调查、拉取请求和构建的做法,并在宣布完成前做最后检查。
要使用这个AI规则
## 保持数据库各模块的边界,保护不分配内存的数据路径
- 为存储引擎、SQL 引擎、网络协议、工具、worker queue、日志、后台任务、基准测试、兼容性测试和示例保留明确的模块边界。
- 将生产代码与基准测试、构建工具、示例和平台 wrapper 分开。
- 将嵌套的 client repository 或 submodule 视为独立仓库,拥有自己的 commit 和 compatibility target。
- 更改行为前,确定正确的入口:server startup、storage engine、SQL compiler、table reader 或 table writer。
- 保护查询执行和数据摄取期间的 zero-allocation data path。
- 当架构要求时,优先采用 object pool、reusable buffer、column-oriented storage、vectorized execution 和 native acceleration。
- 如果项目明确要求内部实现高性能关键算法,不要引入第三方 runtime dependency。
- 仅将原生代码用于足以抵偿其内存、平台和失败风险的操作。
## 按规则排列 Java 类成员,保持对旧版 Java 客户端的兼容
- 按 static 或 instance 类别及 visibility 对 class member 分组,然后在各组内按字母顺序排列。
- 将新 field 和 method 插入正确的排序位置,不要创建装饰性的 section group。
- 绝不要添加用作 Java 分区标题的 banner comment。
- 使用 main module 支持的现代语言 feature,包括 enhanced switch、multiline string 和 pattern variable。
- 在 compatibility module 中遵守较旧的语言 target;不要让 main module 的 syntax 泄漏到面向较早 Java release 的 client。
- 根据含义为 boolean variable、field 和 method 添加 `is` 或 `has` 前缀。
- 当日志 pipeline 无法可靠呈现 Unicode punctuation 或 symbol 时,log message 必须严格只使用 ASCII。
- 当项目的 resource-aware collection type 能与既有 cleanup utility 集成时,优先使用它而不是普通 object array。
- 引入新 abstraction 前,遵循现有 naming、ownership 和 allocation pattern。
## 明确 NULL 的处理,并在每条错误路径上清理内存
- 明确定义 column data、expression result、SQL statement 和 intermediate state 的 NULL behavior。
- 区分表示“尚未初始化”的 NULL sentinel 与真实数据 NULL。
- 在 success、error、cancellation 和 early-return path 中追踪每次 allocation 与 closeable resource。
- 对 list 和 closeable element 始终使用仓库规定的 cleanup helper。
- 将 leak prevention 视为设计要求,而不是只在测试中关注。
- 对分配 native memory 的测试添加 memory-leak assertion。
- 可以在能证明不会分配 native memory 的狭窄 unit test 中省略 leak harness。
- 在所有相关 error path 上验证 cleanup,不要只验证 success path。
- 绝不要用便利的 container 或 helper 掩盖 ownership 歧义。
## 用重读结果的严格断言来测试查询
- 优先使用权威的 fluent query assertion framework,不要使用旧式 single-pass print-and-compare helper。
- 对 deterministic query,要求第二次 cursor pass、size cross-check、variable-column check 和相关 factory-property assertion。
- 仅当 projection 在重新读取时确实不稳定,才能使用 single-pass assertion,并且必须说明原因。
- 合理的不稳定情况包括未设置 seed 的 random function 和 time-varying function。
- 通过 non-query execution path 执行 DDL 和其他 non-query statement。
- 当 optimizer behavior 属于契约时,使用 framework 的 plan helper 断言 execution plan。
- dialect 支持时,用一个 INSERT statement 插入多条测试数据。
- 对较长 SQL 和 multiline expected result 使用 multiline string。
- 始终使用一致的 SQL keyword 风格,最好使用 uppercase。
- syntax 支持时,对 5 位及以上的 literal 使用 underscore 分隔千位。
## 遵循 SQL 方言,把错误位置指向出错的那个字符
- 当维度编码在 column type 中时,将 multidimensional array type 视为不同类型。
- 始终使用 dialect 推荐的 cast syntax,不要混用等效写法。
- 让 parser、implementation code 和 test 对 numeric separator 的支持保持一致。
- 不要假定标准 SQL feature 一定存在;记录并测试不支持的操作。
- 不支持删除行时,应在应用逻辑中显式建模 soft deletion。
- partition-level drop operation 与 row-level deletion 的范围和安全性不同,必须保持区分。
- 报告的 SQL error position 应指向具体的错误字符,而不是只指向 expression 开头。
- 同时针对 message 和精确 position 测试 parser error。
- 保持 syntax、semantic、type 和 execution error 之间的区别。
## 拿到证据之前,把每个失败的测试都当作真实缺陷来调查
- 将每个 red test、failed CI job 和异常 log entry 视为 live defect,直到证据证明并非如此。
- “pre-existing”“flaky”“unrelated”和“known issue”都是假设,不是结论。
- 在相关 baseline 上复现,检查 version history,测量 timing constraint,并查阅权威 upstream report。
- 只有证据迫使得出不同结论后,才能将该失败排除。
- 报告作为分类依据的证据,使其他 reviewer 可以验证。
- 不要将一次 green rerun 当作失败无害的唯一证据。
- 多项变更共享同一 CI lineage 时,调查它们之间的 interaction failure。
- 保留诊断所需的 log、failing input 和最小可靠复现。
- 让修复范围只覆盖已证明的原因,并添加一项缺少该修复就会失败的 regression test。
## 让分支和拉取请求配合合并方式与 CI 成本
- 让 branch 和 pull-request strategy 适应仓库的 merge model 与 CI 成本。
- 在 squash-merge workflow 中,不要花精力美化会被丢弃的 branch history。
- 添加清晰的 fix-up commit,不要仅为修饰历史而改写 prior commit 或 force-push。
- 当拆分会增加长时间 CI run、flake exposure 和 merge coordination 时,应合并相关 fix。
- 仅当用户要求,或变更必须独立 merge 或 revert 时才拆分。
- 更新已有 pull request 时,先与 remote head 同步,将变更加入其 branch,并更新 metadata。
- 不要仅为了重新运行同一变更链的验证而创建第二个 pull request。
- 当仓库政策将另一 branch 定义为 canonical review state 时,不要创建 review worktree 或 checkout branch。
- 只需要 diff 时,获取 pull-request diff,不要切换 branch。
- 先在 nested repository 内部 commit,再记录 parent submodule pointer。
## 在拉取请求和提交说明中同等写出好处与坏处
- 使用仓库要求的 pull-request title convention,并让 description 对最终用户有实际意义。
- 同等突出地描述 positive effect、negative effect、regression 和 tradeoff。
- 避免销售用语、最高级表达、选择性指标和装饰性强调。
- 修复 issue 时,在 pull-request body 顶部使用规定的 closing form 引用它。
- 保持 commit title 简短、描述清晰,并符合仓库规定的风格。
- 提供有实质内容的 commit body 来解释变更,不要只是重复 title。
- 禁止 checkbox 或 check mark 时,在 test plan 中使用普通 bullet。
- 添加与变更领域和 title 一致的 label。
- 在 commit、pull request 和 code comment 中使用主动语态。
- 明确指出执行动作的 class、method、caller 或 component,不要用被动结构隐藏主体。
## 先确认环境,再从最小范围开始构建和测试
- 构建前验证所需的 language runtime、build tool、architecture 和 environment variable。
- 选择能证明当前变更的最小 build profile;web 或 native artifact 受到影响时,再使用更完整的 profile。
- 当本地 artifact cache 可能包含过期 client 或 library 时,重新构建 dependent module。
- 当并行构建相互干扰时,按顺序运行耗时较高的 test invocation。
- 从最窄的相关 test class 或 method 开始,再根据风险和仓库政策扩大。
- 不要将成功 compilation 单独视为 runtime behavior 的证明。
- 通过受支持的 startup path 验证服务器,并检查直接受影响的 endpoint 或 interface。
- 将 build artifact 保存在指定的 module-owned location。
- 构建停止时,记录准确的失败 command 和第一个可操作 error。
## 消除 Rust 警告,防止 panic 经由 JNI 让 JVM 崩溃
- 完成 Rust 工作前,从 crate root 运行 formatting、all-target compilation、lint 和 library test。
- 所有 mandatory check 都必须达到 error 0 件、warning 0 件。
- 添加或修改测试后测量 coverage。
- 对每个 uncovered line,添加能覆盖它的测试,或证明它不可达并明确标记该 invariant。
- 绝不要对来自文件内容或外部输入的数据调用 `unwrap()` 或 `expect()`。
- 使用 `Result`、`Option` 和语言标准的 error propagation 传递可恢复失败。
- 记住:穿过 JNI 的 Rust panic 可能在无法恢复的情况下终止整个 JVM。
- 使用仓库的 release configuration 构建 native C/C++ library,并验证预期 artifact。
- 将 FFI ownership、lifetime、alignment 和 error conversion 视为显式契约。
- 在变更影响的每个受支持平台上测试 boundary failure。
## 避免堆分配,并用基准测试衡量速度提升
- 当 zero-GC behavior 属于架构要求时,避免在 data path 中进行 heap allocation。
- 重用 buffer 和 pooled object,并明确 ownership transfer。
- 当 compression 和 vectorized operation 依赖布局时,按列存储分析数据。
- 将 SIMD、memory management 和 platform-specific optimization 限制在狭窄的 native boundary 后面。
- 将 storage、parsing、planning、code generation、execution、protocol handling 和 background work 分开。
- 仅在理解并测试其 allocation 与 cleanup behavior 后,才使用 custom collection。
- 使用代表性 benchmark 测量性能变更,不要凭直觉判断。
- 为每项 optimization 同时提供 correctness test、resource check 和明确记录的 tradeoff。
- 不要为了未经测量的 speedup 而削弱 compatibility 或 error precision。
## 宣布完成前,检查最终差异并报告结果
- 检查最终 diff 中的 member ordering、compatibility boundary、NULL behavior、resource ownership 以及 log 中意外出现的 Unicode。
- 运行变更影响的 Java、SQL、Rust、native 和 integration check。
- 确认 deterministic query 使用强 reread assertion path。
- 确认外部输入无法触发不可恢复的 native panic。
- 确认每个已调查失败都有基于证据的分类和已报告的复现。
- 确认 pull-request metadata、label、test plan、commit text 和 issue reference 符合仓库政策。
- 确认 nested repository 与 parent pointer 按正确顺序 commit。
- 只要 mandatory check 仍有 error 或 warning,就不要宣称完成。
- 报告运行的 command、观察到的结果、剩余风险和有意未测试的范围。
