1. 从一次建表卡顿说起：为什么要啃 HBase 建表源码
很多人第一次接触 HBase 源码，都是从createTable这个入口进去的。原因很简单：建表是日常运维里最高频的操作之一，而且它不像读写路径那样牵扯到 MemStore、BlockCache、Compaction 一大堆子系统，看起来"应该很简单"。但真把源码翻下去，你会发现这条链路一点都不短——客户端要跟 Master 打交道，Master 要写元数据、要跟 RegionServer 协调、要触发 Region 上线，中间还夹着 Procedure 框架、状态机、ZooKeeper 的分布式协调。
我自己最早看这块源码，是因为线上遇到过一个很典型的现象：createTable调用返回超时了，但表实际上建成功了。当时第一反应是"是不是网络抖动"，后来抓包加日志才发现，问题出在客户端等待 Region 上线的超时逻辑上，跟建表本身没关系。这件事让我意识到，如果不把建表流程的源码吃透，遇到这类"半成功"状态根本没法定位。
这篇就围绕 HBase 建表这条链路，把客户端、Master、Procedure、Region 上线几个关键环节的源码逻辑拆开讲。适合已经用过 HBase、想往源码层深入的同学，也适合正在排查建表超时、建表卡住、表状态异常这类问题的运维和开发。我会尽量把"为什么这么设计"讲清楚，而不是只贴代码——因为源码分析最容易犯的错，就是变成代码翻译，看完还是不知道遇到问题该看哪里。
提示：本文基于 HBase 2.x 的代码结构展开，1.x 的建表路径差异较大（没有完整的 ProcedureV2 框架），如果你还在用 1.x，部分逻辑需要对照旧版本看。
2. 建表请求的起点：客户端到底做了什么
2.1 Admin 接口背后的 RPC 封装
我们平时写的admin.createTable(tableDescriptor)，看起来就一行，但它背后是一整套 RPC 封装。Admin是个接口，真正的实现是HBaseAdmin（2.x 里逐渐被AdminOverAsync之类的异步实现替代，但同步路径依然存在）。这一层做的事情其实很薄：把TableDescriptor序列化成 Protobuf，然后通过MasterRpcService发出去。
这里有个容易被忽略的点：建表请求是发给 Master 的，不是发给 RegionServer 的。很多人调试时习惯性去看 RegionServer 日志，结果什么都看不到。建表、删表、改表这类 DDL 操作，全部由 Master 统一处理，因为只有 Master 掌握全局的元数据和 Region 分配信息。
客户端在发送请求前，会先通过Connection拿到 Master 的地址。这个地址从哪来？从 ZooKeeper 的/hbase/master节点读。所以如果你的建表请求卡在"连接 Master"阶段，八成是 ZooKeeper 或者 Master 本身的问题，而不是建表逻辑的问题。
2.2 同步等待与超时的设计逻辑
请求发出去之后，客户端并不是发完就完事，它会同步等待 Master 返回建表结果。这个等待是有超时的，默认由hbase.client.operation.timeout控制（默认 120 秒）。这里就是我前面踩坑的地方：Master 可能已经把表建好了，但 Region 上线比较慢，客户端等不到"完全就绪"的信号，就抛了超时异常。
为什么客户端要等这么久？因为建表不是"写个元数据就完事"，它需要等所有 Region 都完成上线（assign），表才真正可用。如果客户端不等，直接返回成功，那用户马上往里写数据就可能失败。所以这个等待是有意义的，只是超时时间需要根据集群规模调整。
注意：如果你在自动化脚本里批量建表，建议把
hbase.client.operation.timeout调大，或者改用异步 Admin 接口，避免大批量建表时集体超时。
2.3 一个常被问到的细节：建表请求的幂等性
经常有人问：建表请求超时了，我重试一次会不会报"表已存在"？答案是取决于你重试的时机。如果第一次请求其实已经成功，只是客户端没收到响应，那你重试时 Master 会发现表已存在，直接抛TableExistsException。所以生产环境的建表脚本，最好先做一次tableExists判断，或者捕获这个异常做幂等处理。
这个设计本身没问题，但它反映出一个原则：HBase 的 DDL 操作不是天然幂等的，客户端要自己承担重试的语义。这一点跟很多人的直觉相反——大家习惯了 HTTP 接口的幂等设计，到了 HBase 这里就容易踩坑。
3. Master 侧的处理链路：从 RPC 到 Procedure
3.1 MasterRpcService 的入口分发
请求到了 Master，第一站是MasterRpcService。这个类本质上是个 RPC 服务端实现，它把收到的 Protobuf 请求反序列化，然后分发给对应的 Handler。建表请求对应的是CreateTableHandler（在 ProcedureV2 框架下，实际是提交一个CreateTableProcedure）。
这里有个设计上的关键点：Master 不会在 RPC 线程里直接执行建表逻辑。RPC 线程只负责把请求转成一个 Procedure 提交出去，然后立刻返回。真正的建表动作是在 Procedure 的执行线程里跑的。为什么要这么设计？因为建表可能涉及多个步骤、需要跟多个 RegionServer 交互，耗时不可控。如果占着 RPC 线程不放，Master 的 RPC 处理能力会被拖垮。
这个"提交即返回"的模式，也是为什么客户端会超时但表却建成功了——RPC 层早就返回了，客户端等的是 Procedure 完成的通知，两者不是一回事。
3.2 Procedure 框架：建表为什么需要状态机
ProcedureV2 是 HBase 2.x 引入的一套状态机框架，专门用来处理这类"多步骤、可能失败、需要回滚"的操作。建表被建模成一个CreateTableProcedure，它内部有一系列状态（State），每个状态执行一步，执行完就持久化到 Procedure 存储里（默认存在 Master 的hbase:procedure表或者 WAL 里）。
为什么建表需要状态机？因为建表不是原子的。它至少要经历这几步：
- 检查表是否已存在、schema 是否合法
- 在
hbase:meta里写入表的元数据 - 为每个 Region 分配 RegionServer 并触发上线
- 等待所有 Region 上线完成
如果第 3 步执行到一半 Master 挂了，重启后必须能从上次的状态继续，而不是从头再来或者留下一个半成品表。这就是状态机存在的意义——它保证了操作的最终一致性，而不是原子性。
我见过有人问"为什么 HBase 建表这么慢"，其实慢的不是建表本身，而是这套状态机为了保证可靠性付出的代价。每一步都要持久化状态，每次状态转换都要写日志，这些开销在单表建表时感知不明显，但批量建表时就很可观了。
3.3 元数据写入：hbase:meta 里到底存了什么
建表过程中最关键的一步，是把表的元数据写进hbase:meta。这张表是 HBase 的"目录表"，记录了所有用户表的 Region 分布信息。建表时写入的内容包括：
- 表的
TableDescriptor（列族、属性、配置等） - 每个 Region 的
RegionInfo（起止 rowkey、RegionId 等） - Region 当前分配的 RegionServer
这里有个细节值得注意：元数据写入和 Region 上线是分开的两步。元数据先写进去，此时表在hbase:meta里已经存在了，但 Region 还没上线，表处于"不可用"状态。只有等 Region 全部上线，表才真正可用。这解释了为什么有时候list命令能看到表，但一访问就报RegionNotOnlineException。
提示：排查建表问题时，可以用
scan 'hbase:meta'看表的元数据是否写入成功，用hbck或 Master UI 看 Region 是否上线。这两步分开看，能快速定位卡在哪一环。
4. Region 上线：建表流程里最容易被低估的一环
4.1 Region 分配策略与 AssignmentManager
元数据写完之后，Master 要把每个 Region 分配给一个 RegionServer，这个过程叫 assignment，由AssignmentManager负责。分配策略不是随便挑一个，而是要考虑负载均衡、机架感知、RegionServer 的可用性等因素。
默认情况下，Master 会尽量把 Region 均匀分布到各个 RegionServer 上。如果你的集群 RegionServer 数量少，或者某些节点负载已经很高，分配就可能变慢。我遇到过一种情况：集群里有个 RegionServer 处于"假死"状态（进程还在，但响应很慢），Master 尝试往它上面分配 Region，结果一直等不到确认，整个建表流程就卡住了。
所以建表慢或者卡住，很多时候根因在 RegionServer 的健康状态，而不是建表逻辑本身。排查时先看 Master UI 上的 RegionServer 列表，有没有节点状态异常，这一步能省掉很多弯路。
4.2 Region 上线的完整握手过程
Region 分配出去之后，Master 会通知对应的 RegionServer 打开这个 Region。RegionServer 收到通知后，要做几件事：
- 在本地创建 Region 对象，初始化 MemStore、StoreFile 等结构
- 向 Master 汇报 Region 已上线（通过
RegionServerStatusService） - Master 收到汇报后，更新
hbase:meta里该 Region 的状态
这个握手过程是异步的，Master 发完通知不会阻塞等待，而是通过回调或者轮询来确认。如果 RegionServer 处理慢，或者汇报消息丢了，Master 就会重试。重试次数和间隔由配置控制，超过阈值就会标记为失败。
这里有个经验：Region 上线失败最常见的原因是 RegionServer 的 handler 线程被打满。如果你的集群正在跑大量读写，RegionServer 的 RPC handler 队列可能已经积压，这时候新建表的 Region 上线请求排在后面，自然就慢了。解决办法要么是扩容，要么是错峰建表。
4.3 客户端如何感知"表已就绪"
回到客户端这边，它怎么知道表已经就绪了？答案是轮询。客户端在等待期间，会周期性地去查hbase:meta，看目标表的所有 Region 是否都处于 online 状态。全部 online 了，才认为建表完成，返回成功。
这个轮询机制有个副作用：如果 Region 数量很多（比如预分区建了几百个 Region），轮询的开销和等待时间都会显著增加。所以预分区建表时，超时时间一定要相应调大，否则很容易出现"表建好了但客户端报超时"的情况。
我个人的做法是：预分区建表时，把超时时间设成Region数量 × 单Region预期上线时间 × 安全系数。单 Region 上线时间在健康集群里通常是几百毫秒到一两秒，安全系数取 2 到 3 比较稳妥。
5. 建表流程中的异常分支与回滚逻辑
5.1 哪些环节可能失败
建表这条链路上，失败点比想象中多。我整理了一张表，把常见失败点和对应的现象列出来，方便排查时对照：
| 失败环节 | 典型现象 | 根因方向 |
|---|---|---|
| 客户端连接 Master | 请求直接抛连接异常 | ZooKeeper 或 Master 不可用 |
| Master 校验 schema | 抛 InvalidTableException | 表名非法、列族配置错误 |
| 元数据写入 | Procedure 卡在写入状态 | hbase:meta 所在 RegionServer 异常 |
| Region 分配 | Procedure 长时间不推进 | RegionServer 假死或负载过高 |
| Region 上线 | 表可见但访问报错 | RegionServer handler 打满 |
| 客户端等待 | 超时但表已建好 | 超时配置过小或 Region 过多 |
这张表是我踩了多次坑之后总结的，基本上覆盖了 90% 的建表异常场景。排查时按这个顺序过一遍，效率比盲目看日志高很多。
5.2 Procedure 的回滚机制
如果建表过程中某一步失败了，Procedure 框架会触发回滚。回滚的逻辑是逆序执行已完成的步骤：如果元数据已经写入，就删掉元数据；如果 Region 已经分配，就 unassign 掉。这样保证失败后不会留下半成品。
但回滚本身也可能失败。比如元数据写入成功，但回滚时hbase:meta所在的 RegionServer 挂了，删不掉。这时候 Procedure 会进入一个"回滚失败"的状态，需要人工介入。这种情况虽然少见，但一旦发生就很麻烦，因为表处于一个"既没建好、又删不掉"的中间态。
注意：遇到回滚失败，不要急着重启 Master，先看 Procedure 的状态和
hbase:meta里的残留数据。盲目重启可能让状态更混乱。正确的做法是用hbck工具检查并清理残留元数据。
5.3 一个真实踩坑：超时重试导致的重复建表
前面提到过建表不幂等，这里展开讲一个我实际遇到的场景。当时有个自动化脚本批量建表，超时时间设得比较短（30 秒）。结果有一批表因为 Region 多，30 秒没建完，脚本判定失败就重试了。重试的请求到了 Master，发现表已存在，抛TableExistsException，脚本又把这次当成失败，继续重试……最后日志里全是异常，但实际上表早就建好了。
这个坑的教训是：建表脚本必须区分"真失败"和"超时但可能成功"。我的改法是，捕获超时异常后，先查一次tableExists，如果表存在就认为成功，不存在才重试。这个逻辑看起来简单，但能避免大量误报。
6. 从源码里能学到的设计思路
6.1 为什么 DDL 要走 Procedure 而不是直接执行
看完整个流程，你会发现 HBase 把建表这种 DDL 操作做得很"重"——状态机、持久化、回滚、异步通知，一应俱全。对比一些轻量级系统，建表可能就是写一条元数据就完事。HBase 为什么要这么复杂？
核心原因是规模和可靠性。HBase 面向的是大规模集群，Region 数量可能成千上万，Master 随时可能故障切换。在这种环境下，一个"写条元数据就返回"的简单实现，根本无法保证故障后的状态一致。Procedure 框架用复杂度换来了可靠性，这是分布式系统的典型权衡。
理解这一点，对排查问题很有帮助：当你觉得"建表怎么这么慢"时，要意识到这些开销是在为可靠性买单。如果业务场景确实不需要这么强的保证（比如测试环境），可以通过调参来降低开销，但生产环境不建议动这些。
6.2 异步设计与客户端等待的配合
另一个值得琢磨的设计是"Master 异步执行 + 客户端同步等待"这个组合。Master 侧用 Procedure 异步跑，不阻塞 RPC；客户端侧同步等，保证调用返回时表可用。这个组合把"执行"和"感知"解耦了，各自用最适合的方式处理。
这种模式在很多分布式系统里都能看到。它的好处是 Master 不会被慢操作拖垮，坏处是客户端要处理"超时但可能成功"这种模糊状态。作为使用者，理解这个模式能帮你写出更健壮的调用代码——永远不要假设 DDL 操作是瞬时且原子的。
6.3 对日常运维的几点启发
最后分享几个从源码里悟出来的运维经验，都是实际用得上的：
第一，建表前先确认 RegionServer 健康。建表卡住十有八九是 RegionServer 的问题，提前看一眼 Master UI，能省掉大量排查时间。
第二，预分区建表要调大超时。Region 越多，上线越慢，超时时间要跟着涨。别用默认值硬扛。
第三，建表脚本要做幂等处理。超时后先查表是否存在，再决定是否重试，避免重复建表报错。
第四，关注 Procedure 的状态。Master UI 上有 Procedure 的列表和状态，建表卡住时先看这里，能直接定位卡在哪一步。
这些经验看起来琐碎，但每一条都是踩坑换来的。源码分析的价值，最终还是要落到"遇到问题知道看哪里、怎么处理"上。如果只是把代码读一遍，不结合实际场景，那读源码的收益会大打折扣。
我个人看 HBase 源码的习惯是：先带着一个具体问题进去（比如"建表为什么超时"），顺着链路走一遍，把关键节点和状态记下来，然后再回到问题本身。这样读一遍，比漫无目的地翻代码效率高得多。建表这条链路我前后看了三四遍，每次都有新收获，因为随着对集群理解的加深，你会注意到之前忽略的细节。源码这东西，从来不是一遍就能读透的。
