NodeJS客户端

安装NodeJs客户端

项目地址:Pegasus NodeJS Client
下载并将客户端依赖添加到package.json中:
npm install pegasus-nodejs-client --save

创建/关闭客户端

create

let pegasusClient = require('pegasus-nodejs-client');
/**
 * Create a client instance
 * @param   {Object}  configs
 *          {Array}   configs.metaServers          required
 *          {String}  configs.metaServers[i]       required
 *          {Number}  configs.operationTimeout(ms) optional
 *          {Object}  configs.log                  optional
 * @return  {Client}  client instance
 * @throws  {InvalidParamException}
 */
client = pegasusClient.create({
    metaServers: ['127.0.0.1:34601', '127.0.0.1:34602', '127.0.0.1:34603'],
    operationTimeout : 5000,
    log : log,
});
  • metaServers为meta server地址列表,为必填项
  • operationTimeout为本次操作的超时时间,单位是毫秒,默认是1000ms
  • log为日志库实例
  • 我们使用日志库 log4js
  • 默认使用的日志配置在log_config.js文件中,配置如下:
    let filename = "./logs/"+process.pid+"/pegasus-nodejs-client.log";
    let logConfig = {
     appenders: { 
       pegasus: {
         type: "file", 
         filename: filename, 
         maxLogSize: 104857600, 
         backups: 10
       } 
     },
     categories: { 
       default: { appenders: ["pegasus"], level: "INFO" } 
     }
    };
    

    上述配置表示,会将错误级别等于及高于INFO级别的日志存储在文件中,每个日志文件最大100M,最多保留10个日志文件

  • 若不想使用默认配置,则需要重新定义如上的logConfig对象,作为创建客户端时的log对象
  • 当参数有误时,会抛出异常,停止后续操作

close

// close client when you do not need to use it
client.close();

接口

get

读单行数据

/**
 * Get value
 * @param {String}      tableName
 * @param {Object}      args
 *        {Buffer}      args.hashKey      required
 *        {Buffer}      args.sortKey      required
 *        {Number}      args.timeout(ms)  optional
 * @param {Function}    callback
 * @throws{InvalidParamException} callback is not function
 */
 client.get(
   tableName,  
   args, 
   function(err, result){
     // if get operation succeed, err will be null,
     // result.hashKey is hashKey, result.sortKey is sortKey, result.value is value
     // else err will be instance of PException, result will be null
   }
 );
  • get操作的必填参数有表名,hashKey,sortKey和callback
  • hashKey,sortKey和value都是Buffer对象,这与pegasus服务端key与value均为byte的语义保持一致
  • 超时时间为可选参数,默认为创建客户端时设定的超时时间
  • 当读操作成功时,callback的err为空,result.value为读到的值
  • 当读操作失败时,callback的result为空
  • 客户端不认为读不到值时错误,因此当读不到值时,err仍为空,result.value为Buffer('')

set

写单行数据

/**
 * Set Value
 * @param {String}      tableName
 * @param {Object}      args
 *        {Buffer}      args.hashKey      required
 *        {Buffer}      args.sortKey      required
 *        {Buffer}      args.value        required
 *        {Number}      args.ttl(s)       optional
 *        {Number}      args.timeout(ms)  optional
 * @param {Function}    callback
 * @throws{InvalidParamException} callback is not function
 */
 client.set(
   tableName,  
   args, 
   function(err){
     // if set operation succeed, err will be null
     // else err will be instance of PException
   }
 );
  • set操作的必填参数有表名,hashKey,sortKey,value和callback
  • ttl的含义为过期时间,单位为秒,默认ttl为0,则表示该数据不过期,若用户设置ttl为86400s,则表示该数据将在1天之后过期,用户在1天之后将无法读取到该数据

del

删除单行数据

/**
 * Delete value
 * @param {String}      tableName
 * @param {Object}      args
 *        {Buffer}      args.hashKey      required
 *        {Buffer}      args.sortKey      required
 *        {Number}      args.timeout(ms)  optional
 * @param {Function}    callback
 * @throws{InvalidParamException} callback is not function
 */
 client.del(
   tableName,  
   args, 
   function(err){
     // if set operation succeed, err will be null
     // else err will be instance of PException
   }
 );
  • del操作的必填参数有表名,hashKey,sortKey和callback

multiGet

读同一个hashKey下的多行数据

/**
 * Multi Get
 * @param {String}      tableName
 * @param {Object}      args
 *        {Buffer}      args.hashKey         required
 *        {Array}       args.sortKeyArray    required
 *        {Buffer}      args.sortKeyArray[i] required
 *        {Number}      args.timeout(ms)     optional
 *        {Number}      args.maxFetchCount   optional
 *        {Number}      args.maxFetchSize    optional
 * @param {Function}    callback
 * @throws{InvalidParamException} callback is not function
 */
 client.multiGet(
   tableName,  
   args, 
   function(err, result){
     // if operation succeed, err will be null,
     // result[i].hashKey is hashKey, result[i].sortKey is sortKey, result[i].value is value
     // else err will be instance of PException, result will be null
   }
 );
  • multiGet操作的必填参数为表名,hashKey,sortKey数组和callback
  • 若sortKey数据为空数组,则表示期望获取该hashKey下的所有sortKey的值
  • maxFetchCount为最多获取数据的条数,默认为100
  • maxFetchSize为最大获取数据的大小,默认为1000000字节

batchGet

读取一批数据

/**
 * Batch Get value
 * @param {String}      tableName
 * @param {Array}       argsArray
 *        {Buffer}      argsArray[i].hashKey      required
 *        {Buffer}      argsArray[i].sortKey      required
 *        {Number}      argsArray[i].timeout(ms)  optional
 * @param {Function}    callback
 * @throws{InvalidParamException} callback is not function
 */
 client.batchGet(
   tableName,  
   argsArray, 
   function(err, result){
     // err will be always be null, result is {'error': err, 'data': result} array
     // if batchGet[i] operation succeed, result[i].error will be null
     // result[i].data.hashKey is hashKey, result[i].data.sortKey is sortKey, result[i].data.value is value
     // else result[i].error will be instance of PException, result[i].data will be null
   }
 );
  • batchGet操作的必填参数为表名,hashKey数组,sortKey数组和callback
  • 与multiGet不同的是,batchGet支持读多个hashKey的值
  • batchGet将等待所有本次batch的所有get操作都返回结果后才返回
  • callback的err总是为null
  • callback的result是一个数组,result[i].error表示第i个get操作的出错情况,result[i].data表示第i个get操作的结果

multiSet

写同一个hashKey下的多行数据

/**
 * Multi Set
 * @param {String}      tableName
 * @param {Object}      args
 *        {Buffer}      args.hashKey           required
 *        {Array}       args.sortKeyValueArray required
 *                      {'key' : sortKey, 'value' : value}
 *        {Number}      args.timeout(ms)       optional
 *        {Number}      args.ttl(s)            optional
 * @param {Function}    callback
 * @throws{InvalidParamException} callback is not function
 */
 client.multiSet(
   tableName,  
   args, 
   function(err){
     // if set operation succeed, err will be null
     // else err will be instance of PException
   }
 );
  • multiSet操作的必填参数为表名,hashKey,sortKey-value对象数组和callback

batchSet

写入一批数据

/**
 * Batch Set value
 * @param {String}      tableName
 * @param {Array}       argsArray
 *        {Buffer}      argsArray[i].hashKey      required
 *        {Buffer}      argsArray[i].sortKey      required
 *        {Buffer}      argsArray[i].value        required
 *        {Number}      argsArray[i].ttl          optional
 *        {Number}      argsArray[i].timeout(ms)  optional
 * @param {Function}    callback
 * @throws{InvalidParamException} callback is not function
 */
 client.batchSet(
   tableName,  
   argsArray, 
   function(err, result){
     // err will be always be null, result is {'error': err} array
     // if batchSet[i] operation succeed, result[i].error will be null
     // else result[i].error will be instance of PException
   }
 );
  • batchSet操作的必填参数为表名,hashKey-sortKey-value对象数组和callback
  • callback的err总是为null,result[i].error表示第i个set操作的出错情况
Apache Incubator
Copyright © 2020 The Apache Software Foundation. Licensed under the Apache License, Version 2.0.

Apache Pegasus is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.