@1table/sms-core

可嵌入的短信核心库：不依赖 HTTP 微服务，在进程内按租户配置直接调用阿里云 / Btom / Chatbot / Mock 网关发送短信。适合 Serverless、单机应用或希望零网络调用的场景。

与 @1table/sms-client 的区别

| 能力 | @1table/sms-client | @1table/sms-core | |------|--------------------|------------------| | 使用方式 | 调用已部署的短信微服务（HTTP） | 在进程内直接调网关，无 HTTP | | 依赖 | 微服务需单独部署并可达 | 仅 Node 进程 + 网关配置 | | 租户/模板 | 由微服务侧配置 | 由业务方传入配置对象 | | 适用场景 | 多系统共用一套微服务 | 单应用内嵌、Serverless、无网调用 |

安装

npm install @1table/sms-core
# 或从本地
npm install file:../sms-microservice/sms-core

租户配置结构

const tenantConfig = {
  gateway: {
    provider: 'aliyun',   // 'aliyun' | 'btom' | 'chatbot' | 'mock'
    config: {
      // 阿里云示例
      accessKeyId: 'xxx',
      accessKeySecret: 'xxx',
      signName: '您的签名',
      endpoint: 'dysmsapi.aliyuncs.com',  // 可选
    },
  },
  templates: {
    REGISTER: {
      code: 'SMS_123456789',           // 阿里云模板 code；Btom 可空
      description: '注册验证码',
      content: '您的验证码是${code}，${ttl}分钟内有效。',  // 可选，用于插值/Btom 正文
    },
    LOGIN: { code: 'SMS_987654321', description: '登录验证码', content: '验证码：${code}' },
  },
};

各网关 config 要求见 微服务 API 说明。

使用方式

方式一：createSmsService（推荐）

const { createSmsService } = require('@1table/sms-core');

const tenantConfig = {
  gateway: { provider: 'aliyun', config: { accessKeyId: '...', accessKeySecret: '...', signName: '...' } },
  templates: {
    REGISTER: { code: 'SMS_123456789', content: '验证码：${code}，5分钟内有效。' },
  },
};

const sms = createSmsService(tenantConfig);

// 发送模板短信（传模板 key 或 code）
const result = await sms.sendTemplate('13800138000', 'REGISTER', { code: '123456' });
console.log(result.requestId, result.bizId);

// 批量发送
const batch = await sms.sendBatch(['138...', '139...'], 'REGISTER', { code: '123456' });
console.log(batch.success, batch.failed, batch.details);

方式二：new SmsService

const { SmsService } = require('@1table/sms-core');

const sms = new SmsService(tenantConfig);
await sms.sendTemplate('13800138000', 'REGISTER', { code: '123456' });

方式三：直接按网关发送（不依赖租户模板）

适合 Btom 等无模板网关，或临时指定网关配置：

const { createGateway } = require('@1table/sms-core');

const gateway = createGateway('btom', {
  apiUrl: 'https://...',
  appId: '...',
  appSecret: '...',
  signName: '...',
});

const result = await gateway.sendTemplate({
  mobile: '13800138000',
  templateCode: '',
  params: {},
  signName: '...',
  content: '您的验证码是 123456，5 分钟内有效。',
});

Mock 网关（测试）

const { createSmsService } = require('@1table/sms-core');

const sms = createSmsService({
  gateway: { provider: 'mock', config: {} },
  templates: { CODE: { code: 'MOCK', content: '${code}' } },
});
await sms.sendTemplate('13800138000', 'CODE', { code: '123456' });
// 仅打日志，不真实发送

API

• createSmsService(tenantConfig) → SmsService 实例
• SmsService#sendTemplate(mobile, templateKeyOrCode, params?, options?)
  • options.content：Btom 等无模板网关时作为完整正文（不含签名）
• SmsService#sendBatch(mobiles, templateKeyOrCode, params?, options?)
• createGateway(provider, config) → 网关实例（sendTemplate / sendCode）
• gateways：AliyunGateway、BtomGateway、ChatbotGateway、MockGateway、BaseGateway（按需扩展）

错误处理

配置缺失或网关返回失败会抛出异常，建议业务侧 try/catch 并记录日志。

发布

发布到公共 npm

1. 登录 npm（未登录则先 npm login）
2. 在 sms-core 目录下执行：

cd sms-microservice/sms-core
npm version patch   # 或 minor / major，按需
npm publish --access public

@1table 为 scope，默认会按私有包发布；若包要对所有人可见，必须加 --access public。

发布到私有 registry

在 package.json 中增加（或使用项目根目录 .npmrc 配置 registry）：

"publishConfig": {
  "registry": "https://your-private-registry.com/"
}

然后执行：

npm publish

发布前自检

cd sms-core
npm pack --dry-run   # 查看将要打包的文件
npm pack             # 生成 .tgz，可本地安装测试：npm install ./1table-sms-core-1.0.0.tgz

相关

• 微服务（HTTP）接入：使用 @1table/sms-client
• 微服务 API 说明：docs/SMS_API_REFERENCE.md