HBase作为构建在HDFS之上的分布式列式数据库，原生客户端基本只对Java友好。而前端、BFF层或者一些轻量级服务常用Node.js开发，如果为了访问HBase专门写一层Java代理服务，维护成本并不低。Stargate正是为这类场景准备的：它是HBase自带的REST网关组件，把HBase的表和数据暴露成标准的HTTP接口，任何能发HTTP请求的语言都可以直接操作HBase，Node.js自然也不例外。本文将从部署、接口语义、Node.js客户端封装和工程化实践几个层面，完整讲清楚这套方案。
Stargate是什么，如何启动
Stargate最初是HBase contrib目录下的一个REST服务组件，后来在HBase 2.x中被移到了独立的hbase-rest模块中，部署方式也随之变化。它的核心思路很简单：在HBase集群前面起一个HTTP服务，把对表、行、列族、单元格的操作翻译成HBase Client API调用。对Node.js来说，这意味着不需要引入任何Java依赖，只需要HTTP客户端就能完成全部读写。
如果使用的是较老的HBase 1.x版本，可以直接运行bin/hbase stargate start -p 8080启动，参数p指定端口。HBase 2.x之后则使用bin/hbase rest start -p 8080，两者对外暴露的REST端点几乎一致，所以迁移成本很低。启动前需要确认当前机器的hbase-site.xml中已正确配置hbase.zookeeper.quorum，否则服务连不上ZooKeeper会直接报错。
启动成功后可以先用curl验证一下连通性，请求根路径会返回当前网关支持的所有端点列表：
bin/hbase rest start -p 8080 # 验证服务 curl http://localhost:8080/ # 查看所有表 curl http://localhost:8080/version/cluster curl -H "Accept: application/json" http://localhost:8080/
生产环境建议把Stargate部署在独立节点上，避免与RegionServer抢资源，同时用Nginx做一层反向代理来统一鉴权和限流，因为Stargate本身不带认证模块，这一点后面还会提到。
核心REST端点与数据格式
Stargate的URL设计遵循一个固定的层级：/{table}/{row}/{column}，再配合不同的Accept头决定返回格式。常用的端点有下面几类：
GET /{table}/{row}：按行键取整行数据GET /{table}/{row}/{column-family}:{qualifier}：取某个具体单元格PUT /{table}/{row}：写入一行数据，请求体为XML或JSONPOST /{table}/scanner：创建扫描器，用于区间查询GET /{table}/schema与PUT /{table}/schema：查看和创建表结构
数据格式方面推荐统一使用JSON。写入时请求体的结构是Row对象，包含key和Cell数组，key和cell的value都需要Base64编码，这是最容易踩坑的地方——很多人第一次用直接传字符串，结果写进去的数据读出来是乱码。原因是Stargate为了保证二进制安全，JSON格式下所有byte[]字段一律走Base64。
// 写入数据的JSON结构示例
{
"Row": [
{
"key": "cm93MDAx", // Base64("row001")
"Cell": [
{
"column": "jY6mZXRh", // Base64("cf1:name")
"$": "emhhbmdzYW4=" // Base64("zhangsan")
}
]
}
]
}
如果确实觉得Base64来回转麻烦，也可以用protobuf格式（Accept头设为application/x-protobuf），直接传二进制，性能更好但需要proto文件定义，Node.js侧要引入protobufjs，复杂度更高。一般业务场景下JSON完全够用，编码开销可以接受。
用Node.js封装Stargate客户端
下面用Node.js实现一个简单但可用的客户端类，覆盖建表、写入、点查和扫描四个核心操作。代码使用原生fetch（Node 18以上内置），无需额外依赖。
const BASE = 'http://192.168.0.1:8080';
class HBaseClient {
constructor(base = BASE) {
this.base = base;
}
// 创建表：指定表名和列族
async createTable(table, columnFamilies) {
const schema = {
name: table,
ColumnSchema: columnFamilies.map(cf => ({ name: cf }))
};
const res = await fetch(`${this.base}/${table}/schema`, {
method: 'PUT',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify(schema)
});
if (!res.ok) throw new Error(`createTable failed: ${res.status}`);
return true;
}
// 写入单行，cells格式: { 'cf1:name': 'zhangsan' }
async put(table, rowKey, cells) {
const body = {
Row: [{
key: Buffer.from(rowKey).toString('base64'),
Cell: Object.entries(cells).map(([col, val]) => ({
column: Buffer.from(col).toString('base64'),
'$': Buffer.from(String(val)).toString('base64')
}))
}]
};
const res = await fetch(`${this.base}/${table}/${encodeURIComponent(rowKey)}`, {
method: 'PUT',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify(body)
});
if (!res.ok) throw new Error(`put failed: ${res.status}`);
return true;
}
// 按行键读取整行，返回解Base64后的对象
async get(table, rowKey) {
const res = await fetch(`${this.base}/${table}/${encodeURIComponent(rowKey)}`, {
headers: { Accept: 'application/json' }
});
if (res.status === 404) return null;
const data = await res.json();
if (!data.Row) return null;
const result = {};
for (const cell of data.Row[0].Cell) {
const col = Buffer.from(cell.column, 'base64').toString('utf-8');
result[col] = Buffer.from(cell.$, 'base64').toString('utf-8');
}
return result;
}
}
// 使用示例
(async () => {
const client = new HBaseClient();
await client.createTable('user', ['cf1']);
await client.put('user', 'row001', { 'cf1:name': 'zhangsan', 'cf1:age': '28' });
console.log(await client.get('user', 'row001'));
})();
注意代码里的两个细节：一是行键拼进URL时要做encodeURIComponent，因为HBase的row key经常包含不可见字符或斜杠，不转义会直接打错端点；二是GET请求返回404并不代表出错，只是该行不存在，要和5xx错误区分处理，否则监控里会充满误报。
扫描器与工程化实践
HBase最强大的能力是区间扫描，Stargate通过两步实现：先POST创建scanner拿到一个Location地址，再循环GET这个地址拉取数据，每次返回一批，直到返回204表示扫描结束。不要忘记最后DELETE掉scanner，否则网关侧会积累大量扫描器上下文，时间一长可能拖垮服务。
async scan(client, table, startRow, endRow, batch = 100) {
// 第一步：创建扫描器
const createRes = await fetch(`${client.base}/${table}/scanner`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({ startRow, endRow, batch, column: ['cf1'] })
});
const scannerUrl = createRes.headers.get('Location');
const rows = [];
try {
while (true) {
const res = await fetch(scannerUrl, { headers: { Accept: 'application/json' } });
if (res.status === 204) break; // 扫描结束
const data = await res.json();
if (!data.Row) break;
for (const row of data.Row) {
const obj = {};
for (const cell of row.Cell) {
const col = Buffer.from(cell.column, 'base64').toString('utf-8');
obj[col] = Buffer.from(cell.$, 'base64').toString('utf-8');
}
rows.push({ key: Buffer.from(row.key, 'base64').toString('utf-8'), cells: obj });
}
}
} finally {
await fetch(scannerUrl, { method: 'DELETE' }).catch(() => {});
}
return rows;
}
工程化方面有几点建议。第一，请求要设置合理超时并做重试，Stargate后端连接ZooKeeper偶尔会有短暂抖动，简单的指数退避重试能过滤掉大部分瞬时错误。第二，如果QPS较高，不要每请求都新建连接，用一个带keep-alive的http.Agent（或axios的httpAgent）复用TCP连接，实测能明显降低延迟。第三，安全层面务必把Stargate放在内网，前面加网关做认证转发，因为它自身没有权限校验，直接暴露等于把整库数据裸奔出去。
最后简单对比一下替代方案：Thrift网关配合Node.js的thrift库也能访问HBase，接口更细粒度，但需要维护IDL生成的客户端代码，升级HBase版本时经常要重新生成，比较繁琐；HappyBase是Python生态的方案，Node.js用不了。综合来看，Stargate以REST的简单性换取了少量性能开销，对绝大多数读写场景足够，是Node.js对接HBase时最省心的选择。当单节点Stargate成为瓶颈时，水平多起几个实例挂在负载均衡后面即可，它本身是无状态服务，扩展非常方便。
HBaseNode.jsStargate REST修改时间：2026-09-12 00:04:51