第 13 章：犀牛鸟 2026 实战指南——从学习到贡献

评审关注点：

1. 理解深度
   你是否真正理解了项目的架构和设计哲学？
   你的贡献是否解决了真实的问题？

2. 贡献质量
   代码是否符合项目的编码规范？
   是否有完善的测试？
   PR 的描述是否清晰？

3. 社区参与
   你是否在 Issue 区有建设性的讨论？
   你是否帮助回答了其他社区成员的问题？

4. 学习成长
   你的技术认知是否有明显提升？
   你是否能用自己的话解释你做了什么以及为什么？

对比其他项目：

  TiDB（41K Star）：
    PR 竞争激烈，reviewers 忙
    好做的 issue 早被抢了
    
  CockroachDB（32K Star）：
    英文社区，代码量巨大
    对新手不太友好
    
  OpenTenBase（2K Star）：
    社区小 → 贡献可见度高
    中文环境 → 沟通无障碍
    代码量适中（~3000 C 文件）→ 入门友好
    有明确的优化方向 → 容易找到切入点
    腾讯出品 → 与犀牛鸟竞赛天然契合

目标：能在本地编译运行 OpenTenBase，理解整体架构

Day 1-3：环境搭建
  1. Clone OpenTenBase 仓库
     git clone https://github.com/OpenTenBase/OpenTenBase.git
  
  2. 阅读 README 和构建文档
  
  3. 在本地编译并启动一个最小集群
     （1 GTM + 1 Coordinator + 2 Datanode）
  
  4. 用 psql 连接 Coordinator，执行基本 SQL

Day 4-7：架构理解
  1. 重读本导读的第 3、10 章
     理解 Coordinator-Datanode-GTM 架构
  
  2. 浏览源码目录结构
     重点关注 src/gtm/、src/backend/pgxc/
  
  3. grep __OPENTENBASE__ 查看增量改动分布
  
  4. 运行一些查询，用 EXPLAIN 查看分布式执行计划

Day 8-14：选择方向
  根据第 10 章的贡献方向分析
  选择你最感兴趣且能力匹配的方向

阅读路径：
  1. src/gtm/main/gtm_txn.c
     理解事务 ID 分配的完整流程
     找到锁竞争的热点
  
  2. src/gtm/proxy/
     理解 GTM Proxy 的批量聚合机制
     思考还有哪些可以批量化
  
  3. 用 perf 或类似工具 profile GTM 的 CPU 使用
     确认性能瓶颈在哪里
  
  4. 写一个简单的基准测试
     测量当前 GTM 的事务 ID 分配吞吐量

参考学习：
  TiDB 的 PD(TSO) 如何做批量时间戳分配
  → 这是一个成熟的工业级方案，可以参考其设计

阅读路径：
  1. src/backend/optimizer/util/pgxcship.c
     理解当前的可下推判断逻辑
     找到"保守判断"的地方（理论上可下推但被判为不可下推）
  
  2. src/backend/pgxc/plan/planner.c
     理解分布式查询计划的生成流程
  
  3. 构造一些查询用例
     看看哪些查询被正确下推
     哪些没有被下推但理论上可以
  
  4. 阅读 Citus 的 planner/README.md
     学习五层渐进式规划的设计思想

参考学习：
  Citus 的 Fast-path Router 如何判断单分片查询
  → 对比 OpenTenBase 的 pgxcship 逻辑

阅读路径：
  1. contrib/pgvector/
     了解当前的向量搜索集成状态
  
  2. 原版 pgvector 项目（github.com/pgvector/pgvector）
     对比 OpenTenBase 集成版和原版的差异
  
  3. 思考分布式环境下的向量搜索挑战
     索引如何分片？
     近似最近邻搜索如何跨节点聚合？
  
  4. YugabyteDB 的 src/yb/vector_index/
     参考另一个分布式 PG 系统的做法

第一个 PR 的选择策略：

  好的第一个 PR：
  ├── 修复文档中的错误或遗漏
  ├── 添加缺失的测试用例
  ├── 修复简单的 bug（搜索 issue 标签 good-first-issue）
  └── 改进错误信息（让报错更有用）

  不建议作为第一个 PR：
  ├── 大规模重构
  ├── 核心组件的重新设计
  └── 没有 issue 支撑的"改进"

PR 的标准流程：
  1. 先开 Issue 讨论你的想法
  2. 在 Issue 上得到 maintainer 的认可
  3. Fork 仓库，创建分支
  4. 写代码 + 测试
  5. 提交 PR，描述清楚做了什么、为什么、怎么测的
  6. 响应 Code Review 反馈
  7. 合并

Week 1：建立全景
  读 ch01（为什么需要分布式数据库）
  读 ch02（三条阅读路径）
  读 ch03（五种架构模式）
  → 能画出六个项目的架构谱系图

Week 2：深入核心概念
  读 ch04（共识与复制）
  读 ch05（分片与再均衡）
  读 ch06（查询优化）
  → 理解分布式数据库的三大支柱

Week 3：了解具体项目
  读 ch10（OpenTenBase 深度解读）← 最重要
  读 ch11（跨项目对比）
  → 理解 OpenTenBase 的设计决策和 trade-off

Week 4：动手准备
  读 ch12（技术挑战）
  读 ch13（本章）
  → 选择贡献方向，开始搭建环境

Week 1：
  读 ch10（OpenTenBase）→ ch03（架构模式）→ ch11（对比）
  同时搭建 OpenTenBase 本地环境

Week 2：
  根据选择的方向读对应章节
  GTM 方向 → ch04（共识与复制）
  查询方向 → ch06（查询优化）+ ch07（Citus）

Week 3-4：
  开始源码阅读 + 基准测试 + 提交第一个 PR

按项目配对阅读：
  ch07（Citus vs Vitess）→ ch08（TiDB vs CockroachDB）→ ch09（YugabyteDB）→ ch10（OpenTenBase）
  
然后读：
  ch11（全景对比）→ ch12（技术挑战）→ ch13（竞赛指南）

一条 SQL 在 OpenTenBase 中的完整旅程：

  psql: SELECT * FROM orders WHERE user_id = 123;
  
  1. Coordinator 收到 SQL
     入口：src/backend/tcop/postgres.c → exec_simple_query()
     
  2. Parser 解析
     标准 PostgreSQL Parser（src/backend/parser/）
     
  3. pgxcship 判断是否可下推
     src/backend/optimizer/util/pgxcship.c
     "user_id 是分片键，可以下推到单个 Datanode！"
     
  4. 路由到目标 Datanode
     src/backend/pgxc/locator/locator.c
     hash(123) % node_count → Datanode 2
     
  5. execRemote 发送查询
     src/backend/pgxc/pool/execRemote.c
     发送原始 SQL 到 Datanode 2
     
  6. Datanode 2 执行
     标准 PostgreSQL 执行器
     
  7. 结果返回 Coordinator
     Coordinator 直接转发给客户端

理解 OpenTenBase 的 pgxcship.c（可下推判断）：
  → 同时读 Citus 的 planner/README.md（五层规划）
  → 对比两者的判断逻辑，找到 OpenTenBase 保守的地方

理解 OpenTenBase 的 GTM：
  → 同时读 TiDB 的 PD(TSO) 设计文档
  → 对比中心化时间戳分配的不同实现

错误路径：
  "我要重新设计 GTM，让它支持多分片！"
  → 工作量巨大，没有前期信任基础
  → maintainer 不太可能接受这样的 PR

正确路径：
  先修几个小 bug → 建立信任
  → 提一个改进提案（RFC/Issue）→ 讨论
  → 得到认可后分步实现
  → 每步一个 PR，每个 PR 可独立 review

没有测试的 PR 很难被接受。

OpenTenBase 的测试框架：
  src/test/regress/   → 回归测试（SQL 级别）
  src/test/isolation/  → 隔离级别测试
  
  添加测试的方式：
  1. 在 regress/ 目录下添加 .sql 测试文件
  2. 运行 make check 确认通过
  3. 测试用例要覆盖正常路径和边界情况

错误做法：
  闷头写代码两个月 → 提一个巨大的 PR → 被拒绝

正确做法：
  1. 先在 GitHub Issue 中描述你的计划
  2. 等 maintainer 回复
  3. 按照建议调整方向
  4. 小步快跑，频繁提交
  5. 在 PR 描述中解释设计决策

OpenTenBase 的代码大量依赖 PostgreSQL 内核知识。
如果你连 PG 的基本概念都不熟悉，读 OpenTenBase 源码会很痛苦。

建议先了解：
  - PG 的进程模型（每连接一个进程）
  - PG 的查询处理流程（Parser → Analyzer → Planner → Executor）
  - PG 的 MVCC 实现（xmin/xmax）
  - PG 的 Hook 机制（Extension 如何拦截查询处理）
  
推荐资源：
  "The Internals of PostgreSQL" 在线书籍
  PostgreSQL 官方文档的 "Developer FAQ"

假设参赛周期 = 8 周：

  Week 1-2：基础建设期
  ├── 搭建开发环境
  ├── 阅读导读（重点 ch10, ch03, ch06）
  ├── 浏览源码目录结构
  └── 选择贡献方向

  Week 3-4：深入期
  ├── 深入阅读选定方向的源码
  ├── 写基准测试（量化当前性能）
  ├── 提交第一个小 PR（文档修复或小 bug）
  └── 在 Issue 中讨论你的改进想法

  Week 5-6：核心贡献期
  ├── 实现核心改进
  ├── 写完善的测试
  ├── 提交 PR
  └── 响应 Code Review

  Week 7-8：收尾期
  ├── 完善文档和测试
  ├── 处理 Review 反馈
  ├── 整理竞赛报告
  └── 准备答辩/展示

PR 描述的结构：

  ## 问题
  一句话描述你要解决什么问题。
  链接相关的 Issue。

  ## 解决方案
  你选择了什么方案？为什么选这个方案而不是其他？
  方案的 trade-off 是什么？

  ## 改动
  具体改了哪些文件？每个改动的作用是什么？

  ## 测试
  怎么测试的？测试覆盖了哪些场景？
  附上测试结果。

  ## 基准测试（如果涉及性能改进）
  改动前后的性能对比数据。
  测试环境说明。

技术能力：
  - 阅读大型 C 项目的能力
  - 理解分布式系统设计的 trade-off
  - PostgreSQL 内核知识
  - 性能分析和优化经验

工程能力：
  - 开源协作流程（Issue → PR → Review → Merge）
  - 技术写作和沟通能力
  - 从零理解一个复杂系统的方法论

职业价值：
  - 开源贡献记录（GitHub Profile）
  - 分布式数据库领域的入门经验
  - 与腾讯技术团队的接触机会

知识体系：
  ✓ 为什么需要分布式数据库（第 1 章）
  ✓ 五种架构模式的 trade-off（第 3 章）
  ✓ 共识协议、复制、全局时钟（第 4 章）
  ✓ 分片策略和在线再均衡（第 5 章）
  ✓ 查询优化的四种范式（第 6 章）
  ✓ 不改内核的分布式方案（第 7 章）
  ✓ 原生分布式的两条路（第 8 章）
  ✓ 双协议兼容的方案（第 9 章）
  ✓ OpenTenBase 的完整架构和贡献方向（第 10 章）
  ✓ 六个项目的全景对比（第 11 章）
  ✓ 12 个核心技术挑战（第 12 章）

行动能力：
  ✓ 在本地搭建 OpenTenBase 开发环境
  ✓ 追踪一条 SQL 在 OpenTenBase 中的完整路径
  ✓ 用 #ifdef __OPENTENBASE__ 定位增量改动
  ✓ 评估贡献方向的难度和影响力
  ✓ 提交符合规范的 PR