EasySMS is an SMS sender for Node.js

EasySMS 是一个由 安正超 大神用 PHP 开发的开源的短信发送工具包。本项目是 EasySMS 包在 Node.js 上的实现，并且基本还原了PHP版的配置项以及接口的调用方式。

注：虽然也使用了 EasySMS 这个名称，但是 安正超 大神并未参与开发，请各位开发者不要因使用本包产生的疑惑而去打扰大神，如有疑问请在本项目中提 issue，谢谢~

安装

npm install -S node-easysms

使用说明

如果仍有疑问，请提issue，谢谢～

const { EasySms } = require('node-easysms');

// 配置项
let config = {
  // 请求的超时时间（豪秒）
  timeout: 5000,

  // 默认发送配置
  default: {
    // 网关调用策略，默认：order，可选值：order、random 或回调函数（使用方式见下文）
    strategy: 'order',
    // 可用于发送的网关标识列表
    gateways: ['aliyun']
  },

  // 各网关配置
  gateways: {
    aliyun: {
      access_key_id: 'your-key-id',
      access_key_secret: 'your-key-secret',
      region: 'cn-hangzhou',
      sign_name: 'xx平台',
    },
  }
};

let easySms = new EasySms(config);

// 调用发送api
let response = easySms.send('13812341234', {
  sign_name: 'xx平台',
  template: 'template_id',
  data: {
    code: '1234',
  }
});

国际短信

国际短信与国内短信的区别是号码前面需要加国际码，使用 PhoneNumber 类进行构建即可：

const { EasySms, PhoneNumber } = require('node-easysms');

// 第一个参数为电话号码，第二个参数为国际码
let number = new PhoneNumber('13812345678', 31);

let easySms = new EasySms({...});

// 发送时，传入 PhoneNumber 实例即可
easySms.send(number, {...});

短信消息

根据平台情况使用 content 或者 template + data 设置消息即可。

• content 短信内容，适用于一些直接传短信内容的平台
• template 短信模版，适用于一些传模版id+参数的平台，如：阿里云、腾讯云等
• data 短信模版参数，与 template 配合使用
• sign_name 短信签名，可选，如果消息中未配置，则会提取平台配置中的 sign_name

你也可以使用闭包来返回对应字段的值，闭包接收一个网关实例的参数，闭包也支持异步调用，如下：

easySms.send('13812341234', {
  sign_name: function (gateway) {
    return 'xx平台';
  },
  template: async function (gateway) {
    return await fetchTemplate();
  },
  data: function (gateway) {
    // 获取网关实例的类名
    let className = gateway.getName();

    if (className === 'aliyun') {
      return {
        code: '1234',
      };
    }

    // 默认数据
    return {
      code: '1234',
    };
  }
});

发送短信

默认会根据配置项中的 default.gateways 进行发送，如果某条短信需要覆盖默认对的发送网关，可以传入第三个参数：

let response = easySms.send('13812341234', {
  sign_name: 'xx平台',
  template: 'template_id',
  data: {
    code: '1234',
  }
}, ['tencent']);

返回值

由于使用多网关发送，所以返回值为一个数组，顺序同发送网关标识，结构如下：

[
  // 成功
  {
    'gateway': 'aliyun',
    'status': 'success',
    'result': {}, // 平台返回的数据
  },
  // 失败
  {
    'gateway': 'tencent',
    'status': 'failure',
    'exception': GatewayErrorException 异常实例
  },
]

GatewayErrorException 异常实例可以通过 getRaw() 方法获取接口返回的信息。如果所有网关均发送失败，则程序会抛出 NoGatewayAvailableException 异常，该异常可以通过下列方法获取对应错误信息：

e.getResults();               // 获取所有接口返回的信息
e.getExceptions();            // 获取所有接口返回的信息
e.getException('aliyun');     // 获取所有接口返回的信息
e.getLastException();         // 获取最后一个失败的异常

自定义网关

如果本工具未集成您所需的网关，可通过如下方式进行扩展：

// 需要引入网关基础类
const { EasySms, Gateway } = require('node-easysms');

// 创建自定义网关类
class MyGateway extends Gateway {
  // to: PhoneNumber 实例
  // message: Message 实例
  async send(to, message) {
    // 实现发送方法，并返回接口结果
    // 可以使用工具内置的请求方法：this.get()、this.post()、this.postJson()、this.request()
    return {};
  }
}

let easySms = new EasySms({
  default: {
    gateways: ['mygateway']
  },
  gateways: {
    mygateway: {
      // 网关所需的参数
    },
  }
});

// 注册自定义网关
// 方法一：直接传入类即可
easySms.extend('mygateway', MyGateway);
// 方法二：传入闭包，需接收一个参数，即上述配置中的 gateways.mygateway
easySms.extend('mygateway', function(config) {
  return new MyGateway($gatewayConfig);
});

自定义策略

工具集成了 order（顺序）、random（随机）两种方式，可以通过配置项 default.strategy 进行设置。如果需要自定义策略，则可以设置为一个回调函数：

const { EasySms } = require('node-easysms');

// 需要接收网关标识列表，处理后返回新的列表
function customStrategy(gateways) {
  gateways.sort();
  return gateways;
}

let easySms = new EasySms({
  default: {
    strategy: customStrategy,
    gateways: []
  },
  gateways: {
    ...
  }
});

自定义短信

您可以根据不同的场景，预先定义不同的短信消息类，从而简化发送时的配置。这时只需继承 Message 类即可：

const { EasySms, Message } = require('node-easysms');

class OrderPaidMessage extends Message {

  // 定义该消息所使用的网关，优先级高于配置项 default.gateways
  gateways = ['foo', 'bar'];

  constructor(order) {
    super({});
    this.order = order;
  }

  async getContent() {
    return `您的订单${this.order['no']}已完成付款`;
  }
  async getTemplate() {
    return 'TPL_ORDER_PAID';
  }
  async getData() {
    return {
      order_no: this.order['no'],
    };
  }
  async getSignName() {
    return 'xx商城';
  }
}

let easySms = new EasySms({...});

let order = {...};
let message = new OrderPaidMessage(order);

easySms.send(order.mobile, message);

注意，发送网关的优先级关系由高到低为：

1. easySms.send() 方法的第三个参数
2. 自定义消息中配置的 gateways
3. 工具配置项 default.gateways

各平台配置

aliyun

阿里云 文档，消息内容使用 template + data

// 配置项
{
  access_key_id: '',
  access_key_secret: '',
  region: '',  // 默认：cn-hangzhou
}

tencent

腾讯云 文档，消息内容使用 template + data

注意：腾讯云的模版参数是数组，而非键值对，如果需要与其它平台一同使用，请通过闭包来返回数据。

// 配置项
{
  secret_id: '',
  secret_key: '',
  sdk_app_id: '',
  region: '',  // 默认：ap-guangzhou
}

baidu

百度云 文档，消息内容使用 template + data

注意：使用 sign_name 设置短信签名id

// 配置项
{
  ak: '',
  sk: '',
  sign_name: '',
  domain: '',  // 默认：smsv3.bj.baidubce.com
}

qiniu

七牛云 文档，消息内容使用 template + data

注意：使用 sign_name 设置短信签名id

// 配置项
{
  access_key: '',
  secret_key: '',
  sign_name: '',
}

yunpian

云片 按内容发送，消息内容使用 content，同时也支持 按模板发送，消息内容使用 template + data

// 配置项
{
  api_key: '',
  sign_name: '',
  domain: '',  // 默认：sms.yunpian.com
}

juhe

聚合数据 文档，消息内容使用 template + data

// 配置项
{
  app_key: '',
  sign_name: '',
}