内核开发者阅读与验证指南

本指南以 v4.2.5 为可复核实现基线。先确认问题与版本,再沿一条数据链路阅读,不从全部目录或历史 RFC 开始。

环境与阅读顺序

该 tag 的 go.mod 要求 Go 1.26.4;构建还涉及 C/native 依赖与平台差异,按目标 tag 的 BUILD/Makefile 和实际输出准备。记录 OS/架构、Go、C 编译器、依赖与构建标识;不要用旧贡献文章的工具版本替代。

路线

源码入口

起点文档

SQL 到结果

Frontend → plan → compile → colexec

执行计划

提交与可见性

txn/client → lockservice → TAE txn → Logtail

事务与锁

对象读取与布局

DistTAE → ObjectIO → FileService → TAE

TAE

恢复与保留

Checkpoint → Replay → GC/保护

WAL

控制面

bootstrap/HAKeeper/ClusterService/Proxy

架构

最小修改与测试

固定一个 SQL/并发时序,先观察失败与正确期望,再定位数据结构和等待/释放点。单元测试验证局部条件;BVT 验证客户端 SQL;多 CN、故障、资源与长稳覆盖跨组件行为,互相不能替代。

修改前查询目标模块的现有测试与测试环境说明。根据问题运行最小集合;涉及内存/取消要检查终态,涉及历史读取要覆盖 Merge/GC,涉及提交要覆盖错误/未知状态。测试命令与 fixture 前提按源码测试文档,不把一般 go test ./... 作为所有 native 环境的保证。

文档验收

每篇机制文档应有:适用版本/状态、图或时序、关键不变量、正常/失败/重试/释放路径、固定源码及测试、参数与观测信号、可复现实验。设计提案标注 proposed;SQL 解析、实际执行、严格结果、故障实验分别报告。

教程要提供真实数据、权限/拓扑、步骤、预期结果和清理。单节点 SQL 不证明多 CN;参数变化不证明实际 Spill;NULL 模型不证明推理;源码 PR merged 不证明文档已进入正式分支或发布。

中英文同步,链接进目录。main/latest 与稳定分支独立构建/提交,检查 PR 实际 base 和文件范围。内容修改不混入 CI、主题或生成 HTML。

提交与交付

使用自己的 topic 分支保存修改,普通 push 后提出 PR。保持关联 issue、验证命令与限制;不以 force push 覆盖其他人的 main。源码、参考文档、教程和已部署页面分别核对版本。

源码与回归入口