企业官网建设流程全解析

手上这套HBase快速入门系列写到第6篇，终于到Java API环节了。前几篇我们把安装部署、数据模型、Shell操作这些基础都过了一遍，Shell命令敲熟之后很多人会问：是不是够用了？说实话，如果只是做运维管理、临时查数据，Shell确实够；但只要你打算把HBase接进业务系统，让应用自己读写数据，那就必须在代码里操作它。这篇就专门讲HBase最常用的Java API操作，从环境依赖到建表、增删改查、过滤查询，全部拿真实能跑的代码说话，整个系列的读者看到这里，基本就能独立完成一个和HBase对接的小功能了。

这篇内容比较适合已经能熟练使用HBase Shell、但还没写过一行HBase代码的初级开发者。我会把API的设计逻辑一并讲透，不光是贴代码，还会说明每一步为什么这么写、哪些地方容易踩坑。文章里的代码基于HBase 2.x版本，但也标注了与1.x的差异，方便老项目里做对照。

1. 整体思路拆解：从Shell命令到Java API的思维转换

1.1 为什么业务代码不能依赖Shell

很多刚入门的同学觉得，既然Shell能建表、能put、能scan，那我程序里直接调用Shell命令不就行了？这种方式在临时脚本里勉强能用，但放到正式业务服务里基本属于自杀式设计。每执行一条Shell命令就等于启动一个独立的客户端进程，要重新加载配置、建立连接、完成RPC通信，性能开销大不说，错误处理也极其难做。你总不能在一千个并发请求里各fork一个进程去跑hbase shell吧。

所以HBase官方提供的Java客户端才是正路。它把所有底层通信细节封装成对象和方法：你用Connection维护和服务端的会话，用Admin做表结构管理，用Table做数据读写。本质上，Java API和Shell是同一套能力的不同表达形式，Shell命令底层走的也是这些API。学会Java API之后，你再看Shell命令反而会有一种豁然开朗的感觉——原来每条命令背后都是这些对象在干活。

1.2 Java API的对象体系：Connection、Admin、Table之间的关系

刚接触HBase客户端代码，最容易搞混的就是一堆类。我习惯用一个特别生活化的比喻来理清它们的关系：Connection就像是你家和水厂之间的主管道，它负责建立和维持客户端到HBase集群的所有底层连接；Admin是物业管理员，只管房屋结构改造，比如建房间、拆房间、调整户型；Table则是房间里具体的水龙头和插座，数据读写都通过它来实现。

用代码来说，整个流程永远是三步：

// 1. 创建连接（重量级，必须全局复用一个） Configuration conf = HBaseConfiguration.create(); conf.set("hbase.zookeeper.quorum", "node1,node2,node3"); Connection connection = ConnectionFactory.createConnection(conf); // 2. 从连接中获取操作对象 Admin admin = connection.getAdmin(); Table table = connection.getTable(TableName.valueOf("user")); // 3. 用完关闭对象（注意：Connection不关，Table和Admin要关） table.close(); admin.close();

这三个对象各自的用途非常清晰：Connection负责底层通信，Admin负责DDL，Table负责DML。凡是看到建表、改列族、删表这类操作，找Admin；凡是看到put、get、scan、delete，找Table。把这条原则记住，看别人的代码就不会迷路。

1.3 HBase 1.x和2.x的API差异，别拿老代码硬套

网上很多教程贴的代码还是HBase 1.x时代的写法，比如用HTableDescriptor、HColumnDescriptor的构造函数直接new，再用admin.createTable(desc)去建表。在HBase 2.x里，这些构造函数全被废弃了，强行用也能编译但会有大量deprecated警告，而且某些版本的HBase 2.x已经移除了部分旧类。

2.x的通行做法是使用Builder模式构造描述对象。这个设计上的变化值得说一句：因为表描述需要配置的属性越来越多，如果继续用构造函数的参数列表，调用方得记住一长串参数的含义；改成Builder之后，每个属性对应一个链式调用方法，可读性和扩展性都更好。本篇所有代码统一采用HBase 2.x风格，老版本项目请对应调整。

2. 环境准备与连接初始化：先把地基打牢

2.1 Maven依赖引入与版本匹配陷阱

第一步是引入客户端依赖。以Maven项目为例，在pom.xml里加入：

<dependency> <groupId>org.apache.hbase</groupId> <artifactId>hbase-client</artifactId> <version>2.4.17</version> </dependency>

这个坐标会传递引入hbase-common、hbase-protocol等模块，一般不需要再手动添加其他HBase模块。版本选择上有一个关键原则：客户端版本不能和集群版本差太多。跨大版本通信（比如2.4的客户端连1.4的集群）大概率会出现协议不兼容，表现就是能连上ZooKeeper，但执行操作时报一堆莫名其妙的RPC异常。

还有一个很隐蔽的坑：hbase-client会引入protobuf-java、guava这些依赖，如果你的项目里已经有这些库，可能发生版本冲突。典型报错是NoSuchMethodError或者ClassNotFoundException，原因就是两个不同版本的类都在classpath里。遇到这种情况，用Maven的dependency:tree命令排查具体冲突，再结合exclusions排除旧版本。这个问题在公司实际项目里出现过不止一次，源码编译都通过，启动就挂，非常恼火。

2.2 连接参数配置：quorum、port和znode

创建连接前必须配置至少三个参数，少了任何一个都用不了：

Configuration conf = HBaseConfiguration.create(); // ZooKeeper集群地址，多个节点用逗号分隔 conf.set("hbase.zookeeper.quorum", "node1,node2,node3"); // ZooKeeper客户端端口，默认2181 conf.set("hbase.zookeeper.property.clientPort", "2181"); // HBase在ZooKeeper上的znode父路径，默认/hbase conf.set("zookeeper.znode.parent", "/hbase");

很多初学者只配置了前两个，结果连本机伪分布式环境都连不上，就是因为第三个参数没配或者配错。如果集群安装时修改过znode路径，客户端也必须跟着改，否则客户端会在默认路径下找不到HBase的元数据节点。

关于HBaseConfiguration.create()有一个所有人都会忽略的细节：它会自动读取classpath下的hbase-site.xml。所以如果你的工程在resources目录里放了客户端的hbase-site.xml，那么代码里那三个set其实可以不写。但为了代码的可读性，我建议仍然显式配置，毕竟配置项来源清晰，排查问题也方便。

2.3 Connection是重量级物件，务必全局复用

这里必须反复强调：Connection的创建非常昂贵。它要解析ZooKeeper地址、建立RPC通道、初始化线程池和缓冲区，整个过程可能耗时数百毫秒甚至更久。如果每次操作都创建一个新Connection，高并发场景下你的服务会先在连接建立阶段就阻塞崩溃。

正确的做法是在应用启动时创建一次，然后放入一个全局工具类或者Spring容器中，整个进程生命周期内持续复用：

@Component public class HBaseConnectionHolder { private static final Connection CONNECTION; static { Configuration conf = HBaseConfiguration.create(); conf.set("hbase.zookeeper.quorum", "node1,node2,node3"); try { CONNECTION = ConnectionFactory.createConnection(conf); } catch (IOException e) { throw new RuntimeException("HBase连接创建失败", e); } } public static Connection get() { return CONNECTION; } }

Table和Admin则相反，它们是轻量级对象，可以通过connection.getTable()随时获取。需要注意的是，每次用完尽量关闭Table，它内部持有连接池里的资源；而Connection本身不要随便close，除非应用确实要退出。

3. 建表、改表、删表：DDL操作的完整姿势

3.1 Builder模式建表：从零创建一张带配置的表

在HBase 2.x中，推荐用TableDescriptorBuilder来构建表描述。下面这个例子创建了一张名为user的表，包含两个列族：info和detail：

TableName tableName = TableName.valueOf("user"); ColumnFamilyDescriptor familyInfo = ColumnFamilyDescriptorBuilder .newBuilder(Bytes.toBytes("info")) .setMaxVersions(3) .setTimeToLive(86400 * 30) // 30天TTL，单位秒 .build(); ColumnFamilyDescriptor familyDetail = ColumnFamilyDescriptorBuilder .newBuilder(Bytes.toBytes("detail")) .setMaxVersions(1) .build(); TableDescriptor tableDesc = TableDescriptorBuilder .newBuilder(tableName) .setColumnFamily(familyInfo) .setColumnFamily(familyDetail) .build(); try (Admin admin = CONNECTION.getAdmin()) { admin.createTable(tableDesc); }

注意列族描述和表描述都采用Builder模式，.newBuilder()传入名称，链式定义配置，最后.build()生成对象。setMaxVersions控制一个单元格保留多少个历史版本；setTimeToLive控制数据的存活时间，超过TTL后由服务端自动清理。这些都是在Shell里创建表时也能配置的参数，现在用API指定，效果完全一样。

从实践角度来看，我建议即使不设置TTL、版本数这些参数，也要在建表时定义好列族的其他关键属性，比如压缩算法、布隆过滤器。因为HBase表一旦建成，修改列族属性虽然可行，但某些参数变更需要先disable表，而disable表期间业务是不可用的。提前规划永远比事后补救舒服。

3.2 预分区：一张表对应多个Region的建表方式

大多数新手建表都直接不传分区信息，结果一张表只有一个Region，这个Region会先承受所有读写压力，随着数据量增长再不停分裂。如果对数据量有预期，建表时就该用预分区。API提供了简单的方法，直接传一个分区键数组：

byte[][] splitKeys = new byte[][]{ Bytes.toBytes("1000"), Bytes.toBytes("2000"), Bytes.toBytes("3000"), Bytes.toBytes("4000") }; admin.createTable(tableDesc, splitKeys);

这段代码会把表按行键划分为5个Region：(-∞, 1000)、[1000, 2000)、[2000, 3000)、[3000, 4000)、[4000, +∞)。划分的依据是行键的字节序大小。预分区的核心意义在于把数据压力从单个Region分散到多个Region上，避免热点集中在同一个RegionServer。

当时在做订单表的时候，我按业务时间戳做了预分区，确实明显改善了写入吞吐。这里需要提醒的是：如果行键设计成随机散列（比如加盐），预分区尤其有效；如果行键是单调递增的，预分区也挡不住写热点，因为所有新数据还是会涌向最后一个Region，这时候得在行键设计层面解决问题。

3.3 修改表结构与安全删除：disable是绕不开的步骤

修改表和删除表都需要经历disable这个步骤。HBase的机制是这样的：表在enable状态时，Region上的数据是可以正常读写的，此时不允许做结构性变更。你必须先把表下线（disable），让所有Region停止对外服务，才能修改或者删除。

// 修改表结构 admin.disableTable(tableName); try { ColumnFamilyDescriptor newFamily = ColumnFamilyDescriptorBuilder .newBuilder(Bytes.toBytes("ext")) .build(); admin.addColumnFamily(tableName, newFamily); } finally { admin.enableTable(tableName); } // 删除表 admin.disableTable(tableName); admin.deleteTable(tableName);

很多人写代码时容易漏掉finally块——如果加列族过程中抛异常，表就停在disable状态了，服务彻底不可用。所以我习惯把enable操作放在finally里保证一定会恢复。另外，disableTable和删除之间虽然通常间隔很短，但在生产环境里建议自己做好二次确认，防止误操作。

相比Shell里执行disable 'user'加上drop 'user'，API方式的好处是可以在应用里做权限控制、加日志、加审计。但坏处也很明显：如果你的业务代码有bug，一次性把一个生产表删了，恢复起来非常痛苦。所以我会在涉及drop的代码里加一层显式的表名白名单校验，宁可在代码里多写几行if判断。

4. 写入、读取与删除：DML操作的三板斧

4.1 Put写入：单条put与批量put的正确姿势

写入操作对应Table.put方法，核心是构造Put对象，指定行键和要写入的列。下面是最基本的单条写入：

try (Table table = CONNECTION.getTable(TableName.valueOf("user"))) { Put put = new Put(Bytes.toBytes("row001")); put.addColumn(Bytes.toBytes("info"), Bytes.toBytes("name"), Bytes.toBytes("张三")); put.addColumn(Bytes.toBytes("info"), Bytes.toBytes("age"), Bytes.toBytes("25")); put.addColumn(Bytes.toBytes("detail"), Bytes.toBytes("phone"), Bytes.toBytes("13800000000")); table.put(put); }

这里必须记住一个HBase的行列模型特点：一次put可以给同一个行键的不同列族、不同列写数据，HBase会把它们作为一个整体提交吗？严格说不是事务性的，但在Region内部，这些编辑操作会被打包到同一个Row上，最终一致性上通常没问题。关键的是，put.addColumn里的所有参数都必须是byte[]，所以字符串要转字节。HBase没有任何隐式类型转换，你写入什么类型读出来就是什么类型。

如果一次要写入大量数据，绝对不要循环调用table.put(singlePut)。正确的做法是把Put对象收集到一个List里，一次性提交：

List<Put> puts = new ArrayList<>(); for (int i = 0; i < 10000; i++) { Put put = new Put(Bytes.toBytes("row_" + i)); put.addColumn(Bytes.toBytes("info"), Bytes.toBytes("name"), Bytes.toBytes("user_" + i)); puts.add(put); // 每2000条批量提交一次，避免List太大 if (puts.size() >= 2000) { table.put(puts); puts.clear(); } } if (!puts.isEmpty()) { table.put(puts); }

这个写法的核心意义在于减少RPC次数：一条一条put就是一万次RPC，批量提交可能只需要5次，性能差别是数量级的。尤其要注意的是，HBase服务端会限制单次请求的数据量，太多的Put对象塞进一个List可能导致请求过大被拒绝，所以分批提交是最稳的。

4.2 高性能写入补充：BufferedMutator与异步缓冲

如果追求极致写入性能，单靠批量put还不够。HBase客户端提供BufferedMutator，它可以在本地缓冲一批写操作，积攒到一定大小或等待一定时间后自动发送。这种方式相比普通批量put，把"攒数据-发送"的节奏完全交给客户端内部管理。

try (BufferedMutator mutator = CONNECTION.getBufferedMutator(tableName)) { for (int i = 0; i < 100000; i++) { Put put = new Put(Bytes.toBytes("row_" + i)); put.addColumn(Bytes.toBytes("info"), Bytes.toBytes("name"), Bytes.toBytes("user_" + i)); mutator.mutate(put); // BufferedMutator内部会按buffer大小自动flush } }

这里有个参数值得调：BufferedMutator的buffer大小默认是2MB（在参数hbase.client.write.buffer里配置），可以根据写入量适当调大。但它不是越大越好，太大会导致单次发送的数据包过大，反而让RegionServer处理时间变长。我常用的策略是2MB到8MB之间，看实际写入速度和RPC耗时动态调整。

从2.x版本开始，Connection.getBufferedMutator()是推荐的高性能写入入口。它在内部维持了一个线程安全的写缓冲，多个线程可以同时往里提交Put，整个设计比直接new一个Table然后并发put要优雅得多。

4.3 Get读取：单行查询与指定版本查询

读取单行用Table.get。最简单的用法如下：

Get get = new Get(Bytes.toBytes("row001")); Result result = table.get(get); byte[] nameBytes = result.getValue(Bytes.toBytes("info"), Bytes.toBytes("name")); String name = Bytes.toString(nameBytes); System.out.println("name = " + name);

这里有几个细节值得注意。第一个是Result对象里可能包含多个单元格，getValue返回的是最新版本的数据；如果你想看某个单元格的历史版本，得在Get上设置版本数：

Get get = new Get(Bytes.toBytes("row001")); get.addColumn(Bytes.toBytes("info"), Bytes.toBytes("name")); get.setMaxVersions(3); Result result = table.get(get); Cell[] cells = result.rawCells(); for (Cell cell : cells) { System.out.println("value = " + Bytes.toString(CellUtil.cloneValue(cell)) + ", ts = " + cell.getTimestamp()); }

rawCells()返回的是历史版本数组，按时间戳倒序排列。注意setMaxVersions如果超过列族配置的版本数上限，服务端仍然只返回列族配置的版本数量。也就是说，列族只配了VERSIONS => 1，你在这里设setMaxVersions(3)也查不到历史版本。

第二个细节是Get只能查询一个行键。如果你需要批量查询多个行键，可以构造一个List<Get>传给table.get，返回的Result[]和传入顺序一一对应。这个在多线程查询场景下非常有用，可以显著减少RPC次数。当时我做用户批量查询时，把原来循环get改为批量get，耗时从十几秒下降到一秒内。

4.4 Scan扫描：读懂startRow、stopRow与翻页控制

Scan用于扫描多行数据，是HBase里最常用也最容易出问题的操作。最基本的使用方式如下：

Scan scan = new Scan(); // 限定行键范围：包含startRow，不包含stopRow scan.withStartRow(Bytes.toBytes("row001")); scan.withStopRow(Bytes.toBytes("row100")); // 只取指定的列，减少网络传输 scan.addFamily(Bytes.toBytes("info")); // 每次RPC拉取的记录数 scan.setCaching(100); try (ResultScanner scanner = table.getScanner(scan)) { for (Result result : scanner) { String rowKey = Bytes.toString(result.getRow()); String name = Bytes.toString(result.getValue(Bytes.toBytes("info"), Bytes.toBytes("name"))); System.out.println(rowKey + " -> " + name); } }

先解释startRow和stopRow：这是HBase RowKey排序范围的左闭右开区间，withStartRow包含起始行，withStopRow不包含结束行。如果你要扫全表，就什么都不设置，但全表扫描在生产环境要极度谨慎，大表一次全扫会把内存打爆。

这里要为初学者解释setCaching和setBatch的区别：setCaching控制的是每次RPC从RegionServer取多少行到客户端；setBatch控制的是每次RPC取多少列（单元格）。如果一行有几百个列，caching=100可能就意味着客户端内存里持有上万个单元格，这时候单独调低batch才有意义。建议保持caching在几十到几百之间，范围越大性能越好，但内存占用也越高。

关于Scan的遍历：ResultScanner实现了迭代器，每次迭代返回一行结果。真正的数据是懒加载的，也就是说for循环遍历到哪一行，客户端才从RegionServer拉取哪一批。这既是优点也是陷阱——如果遍历到一半就异常退出，连接资源可能不会被及时释放，所以一定要在try-with-resources里使用Scanner。

4.5 Delete删除：deleteFamily与deleteColumns的区别

删除操作比直觉中更微妙。HBase的删除并不是物理删除，而是写入一条Delete标记，实际数据在发生Major Compaction时才会被彻底清理。构造删除对象时，同样要精确指定行键和列：

Delete delete = new Delete(Bytes.toBytes("row001")); // 方式1：删除整个列族 delete.addFamily(Bytes.toBytes("info")); // 方式2：删除列族中的某个列（所有版本） delete.addColumns(Bytes.toBytes("info"), Bytes.toBytes("name")); // 方式3：删除某个列在某个时间戳之前的版本 delete.addColumn(Bytes.toBytes("info"), Bytes.toBytes("name"), 1700000000000L); table.delete(delete);

特别注意addColumns和addColumn的区别：addColumns（带s）删除一个列的所有历史版本；addColumn（不带s）只删除指定时间戳的那一个版本。日常开发中，大多数业务需求对应的是addColumns，但很多人误写成addColumn，导致删了半天数据还在。

这里的删除语义有一个非常经典的坑：如果你写入了一个新版本的单元格，然后删除它，再查询时确实看不到数据了，但之前删除前的旧版本不一定能恢复。因为HBase的删除标记也有时间戳，它会屏蔽该时间戳及更早的所有数据。理解这个逻辑对排查"删除后旧数据又出现"的问题有帮助。

5. 过滤查询：让RegionServer干活，而不是让JVM扛

5.1 为什么尽量用服务端过滤

Scan本来就把所有数据拉到客户端，如果你在for循环里自己写if判断来做条件过滤，相当于所有行的数据都要跨越网络传输。数据量小的时候没问题，数据量大了整个集群会被拖垮。

HBase提供了过滤器机制，它运行在RegionServer端，在数据从存储文件读出来之后、返回客户端之前就进行筛选。这相当于把"是否满足条件"的判断下沉到服务端，网络只传符合条件的数据。这是学习API时最容易忽略、但实际上对线上影响最大的一个设计点。

5.2 行键、列、值三类过滤器实战

最常见的几个过滤器一定要熟练掌握。按作用对象分三类：过滤行键的、过滤列的、过滤列值的。

// 行键前缀过滤器：只扫描行键以"user_"开头的数据 PrefixFilter prefixFilter = new PrefixFilter(Bytes.toBytes("user_")); scan.setFilter(prefixFilter);

// 列值过滤器：查询info:age列的值大于20的所有用户 SingleColumnValueFilter valueFilter = new SingleColumnValueFilter( Bytes.toBytes("info"), Bytes.toBytes("age"), CompareOperator.GREATER, Bytes.toBytes("20") ); valueFilter.setFilterIfMissing(true); // 如果某行没有age列，则过滤掉 scan.setFilter(valueFilter);

SingleColumnValueFilter是最常用的一个过滤器，它有三个关键参数：列族、列名、比较操作符和阈值。CompareOperator支持LESS、LESS_OR_EQUAL、EQUAL、GREATER_OR_EQUAL、GREATER、NOT_EQUAL等，对应了Shell里FILTER语法的操作符。

setFilterIfMissing(true)这个参数值得展开。它的含义是：如果一行数据没有指定列，是保留还是过滤。默认是false，也就是没有该列的行会保留下来。很多时候这不符合业务直觉。比如你要查"年龄大于20的用户"，一个用户如果没有年龄字段，默认也会被返回，只因为你没设setFilterIfMissing(true)。这个细节排查起来极其坑人，建议只要用值过滤器，就显式设置这个参数。

5.3 FilterList组合过滤：MUST_PASS_ALL与MUST_PASS_ONE

真实业务里很少只有一个过滤条件，多个过滤器需要组合时用FilterList。它有两种语义，对应逻辑关系里的AND和OR：

FilterList filterList = new FilterList(FilterList.Operator.MUST_PASS_ALL); filterList.addFilter(new SingleColumnValueFilter( Bytes.toBytes("info"), Bytes.toBytes("age"), CompareOperator.GREATER, Bytes.toBytes("20"))); filterList.addFilter(new PrefixFilter(Bytes.toBytes("user_"))); scan.setFilter(filterList);

MUST_PASS_ALL代表所有过滤器都必须通过，是逻辑与；MUST_PASS_ONE代表任意一个通过即可，是逻辑或。实际项目中，我建议尽量用行键范围的scan（startRow/stopRow）来缩小扫描区间，再叠加FilterList做精确过滤。不要指望过滤器帮你大幅裁剪扫描区间——HBase扫描器的实现决定了它必须从startRow开始逐行遍历，过滤器只是帮你在传输前丢掉不满足条件的行。行键范围是物理层面缩小扫描范围，过滤器是逻辑层面筛选数据，两者配合才是最优解。

这里还要提一个容易忽视的点：PageFilter可以用来做简单分页。它限制服务端返回的行数，但准确分页光靠PageFilter不行，因为RegionServer有多个Region分别处理各自的扫描请求，每个Region都会返回一页数据。正确姿势是结合startRow实现类似游标分页：每次查询返回N行，记住最后一行的行键，下一次把它作为startRow继续扫。这种方式才能保证全局分页没有重复和遗漏。

6. 实操中的经典坑：资源管理、版本问题和性能红线

6.1 Connection和Table的关闭策略

文章前面已经提过Connection是重量级的，这里结合我实际经历再深入说一下。有一次公司的某个定时任务每次执行都创建新的Connection，跑了几小时后ZooKeeper连接数直接飙满，整个HBase集群新客户端都连不进来，治理现场特别狼狈。后来排查发现就是那批代码没有复用Connection，而且永不关闭。

结论非常明确：Connection必须是应用单例，进程生命周期内创建一次；Table、Admin、BufferedMutator用完后要close。有人觉得Table很轻量，不关也没事，实际上频繁获取而不关闭会导致客户端连接池被逐渐占满，最终表现为连接耗尽。正确习惯是用try-with-resources嵌套结构：

try (Connection conn = HBaseConnectionHolder.get(); Table table = conn.getTable(tableName); ResultScanner scanner = table.getScanner(scan)) { // 业务处理 }

6.2 全限定名中的字节转换一致性

HBase的列族名、列名、行键全部以byte[]存储。不同代码写的字符串，默认使用UTF-8编码转字节，这本身没问题。真正的问题是有些人用String.getBytes()（默认编码）、有些人用Bytes.toBytes()、还有人用getBytes("GBK")，混在一起就全乱了。

统一用org.apache.hadoop.hbase.util.Bytes工具类做转换。这个工具类提供了toBytes(String)、toString(byte[])、toLong、toInt等全套方法。在写工具类时，我要求团队所有HBase相关代码只准用Bytes工具类，任何地方出现String.getBytes()都要打回。一个集群的元数据是全局共享的，一旦某张表的列族名编码乱了，后续所有读写都会遇到NoSuchColumnFamilyException，而且非常难排查。

6.3 Scan无界与内存溢出

Scan操作最危险的地方就是无限制地拉取数据。客户端会在内存里持有扫描出来的对象，如果一张表有几个GB的数据，全表Scan直接就把JVM堆填满。这看起来是常识，但线上事故里因为一句new Scan()不加任何限制导致内存溢出的事故并不少。

我给自己定了一条红线：生产环境的Scan必须有startRow/stopRow，或者至少有FilterList限制条件。如果确实需要全表统计，用HBase的TableMapReduceUtil结合MapReduce去做，而不是在客户端单机扛。实在要在客户端扫，也要设置setScanMetricsEnabled(true)配合监控，随时观察RPC次数和数据量。

6.4 客户端重试参数的合理设置

HBase客户端默认在服务端异常时会重试。hbase.client.retries.number默认是10，hbase.client.pause默认100ms，配合起来意味着一次失败可能持续好几秒的指数退避重试。在很多实时业务场景里，这个默认值太激进，本来接口要响应快，结果卡在重试上。

建议根据业务容忍度调整。读多写少的QPS不高场景可以保持默认；核心高可用服务建议配置hbase.client.retries.number=3，hbase.client.pause=50，快速失败然后让业务上层去做降级或重试。当然这没有标准答案，需要结合具体业务的可用性要求权衡。但是不管你选什么值，都要清楚这个参数的存在，因为默认行为很多时候和业务预期不匹配。

7. 常见报错速查与排查思路

说到最后，把这些年在API操作中踩过的高频异常整理成一个速查表。真到了排查现场，照着表格先定位方向，能省很多时间。

排查的思路分三步走：先看客户端日志里的异常类型，确认是连接阶段、DDL阶段还是DML阶段；再看服务端RegionServer日志，重点找WARN和ERROR；最后才考虑是不是参数配置问题。很多人一上来就怀疑HBase集群有问题，实际上大多数Java API报错都出在客户端自身——依赖冲突、参数缺失、资源未关闭这三类占了我遇到的八成问题。

再讲一个ScannerTimeoutException的细节。HBase服务端为每个Scanner维护一个租约，默认60秒内客户端必须继续拉数据，否则服务端会关闭这个Scanner。如果你遍历一行数据做了很重的计算，导致两批数据之间的间隔超过60秒，就会触发这个异常。解决思路不是盲目调大租约，而是把重计算从遍历循环里挪出去，或者先快速把数据读到一个list里再处理，保证遍历过程不中断。

8. 几个很有实用价值的小技巧

最后分享三个我在实际项目里反复用到的片段，单独介绍因为它们不属于某个API分类，但每个都解决过真实痛点。

第一个是判断表是否存在。线上代码建表前必须判断，否则重复执行会报TableAlreadyExistsException：

try (Admin admin = CONNECTION.getAdmin()) { if (!admin.tableExists(tableName)) { // 建表逻辑 } }

第二个是灵活查询单表的辅助方法。封装一个通用的get方法，把行键和列族传进去，返回一个Map<String, String>，这样业务代码调用时完全不用关心字节转换：

public Map<String, String> getRow(String tableName, String rowKey, String family) { try (Table table = CONNECTION.getTable(TableName.valueOf(tableName))) { Get get = new Get(Bytes.toBytes(rowKey)); get.addFamily(Bytes.toBytes(family)); Result result = table.get(get); Map<String, String> map = new HashMap<>(); for (Cell cell : result.rawCells()) { map.put( Bytes.toString(CellUtil.cloneQualifier(cell)), Bytes.toString(CellUtil.cloneValue(cell)) ); } return map; } catch (IOException e) { throw new RuntimeException("查询HBase失败", e); } }

有很多人喜欢逐行写Bytes.toString，代码非常冗长且容易出错，封装一次之后就清爽很多。需要注意这个封装只适合返回单版本值的场景，如果需要历史版本或大量列，还得返回更复杂的结构。

第三个是检测空结果的技巧。Result对象有isEmpty()方法，判断查询结果是否为空时优先用它，不要用result.getValue(...) == null来间接判断。因为getValue可能因为列族匹配失败返回null，但Result本身非空，两者语义不同，用isEmpty()表达更准确。

根据我的使用经验，HBase Java API的学习曲线比Shell陡不少，主要是概念多、字节转换繁琐、新手容易在资源管理和参数配置上翻车。但只要你把Connection、Admin、Table的角色关系理清，把最常用的put、get、scan、delete这几个操作练熟，后续再看过滤器、异步写入这些都是顺理成章的事情。这套API上手之后，你会发现HBase的数据模型在代码里其实比Shell命令更直观，因为每个对象直接对应一个概念：Put就是一行写入，Get就是一行查询，Scan就是一段范围的遍历。

我最初接手公司一个用户标签查询项目时，也是从零开始啃API，踩过Connection不关闭的坑、踩过全表Scan内存爆掉的坑，慢慢才形成了一套自己的规范写法。所以这篇没有分页、没有批量删除的高级用法没覆盖到的地方，其实都藏在上面的"避坑"逻辑里——先把基础操作的资源管理和边界控制做好，高级用法都是在此之上的延伸。下一篇如果继续写，我准备把协处理器或者与Spring Boot的整合再做一轮细化，这两个方向正好是把API推向工程化的下一步。