TypeScript/Nodejs SDK调用示例

系统要求

• Node.js 版本：14.0 及以上。

• 操作系统：Windows、macOS、Linux。

• 其他依赖：无特殊依赖，SDK 内部已包含所有必需的依赖项。

使用 npm 安装

npm install @alicloud/dysmsapi20170525 -S

验证安装

npm list @alicloud/dysmsapi20170525

# 输出SDK具体版本号代表安装成功

步骤一：创建RAM用户并完成授权

• 创建RAM用户：访问创建RAM用户，完成相关名称设置，并选择访问配置为使用永久 AccessKey 访问，单击确定后即可完成RAM用户的创建。请及时保存AccessKey信息。

• 为RAM用户授权：访问RAM用户列表，找到您所创建的RAM用户，单击操作列的新增授权。在权限策略文本搜索框中输入AliyunDysmsFullAccess后选中此策略，单击确认新增授权，即可完成授权操作。

步骤二：获取访问凭证

请配置环境变量，通过环境变量读取访问密钥（AccessKey）。环境变量配置方法，请参见在Linux、macOS和Windows系统配置环境变量。

步骤三：配置环境变量

环境变量方式最安全、最灵活，避免凭证硬编码，且易于在 CI/CD 流水线中注入。

设置环境变量：

export ACCESS_KEY_ID='your_access_key_id'
export ACCESS_KEY_SECRET='your_access_key_secret'

在代码中使用：

TypeScript：

import { Client } from '@alicloud/dysmsapi20170525';

// 从环境变量读取凭证
const client = new Client({
  accessKeyId: process.env.ACCESS_KEY_ID,
  accessKeySecret: process.env.ACCESS_KEY_SECRET,
  regionId: 'cn-hangzhou', // 根据实际需要选择区域
});

JavaScript：

const { Client } = require('@alicloud/dysmsapi20170525');

// 从环境变量读取凭证
const client = new Client({
  accessKeyId: process.env.ACCESS_KEY_ID,
  accessKeySecret: process.env.ACCESS_KEY_SECRET,
  regionId: 'cn-hangzhou', // 根据实际需要选择区域
});

安全最佳实践

• 使用环境变量或密钥管理服务存储凭证。

• 定期轮换访问密钥。

• 遵循最小权限原则，为RAM用户分配最小必要权限。

• 不要在日志中打印凭证信息。

• 在生产环境中使用RAM角色而非主账号凭证。

代码示例

使用SDK调用发送短信API的代码示例如下，请根据注释完成参数填写。

TypeScript：

// 阿里云短信服务 SDK - TypeScript 优化版本
import Dysmsapi20170525, * as $Dysmsapi20170525 from '@alicloud/dysmsapi20170525';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Credential from '@alicloud/credentials';

/**
 * 创建短信服务客户端
 * 使用默认凭据链，从环境变量或配置文件中读取访问凭证
 */
function createClient(): Dysmsapi20170525 {
  const credential = new Credential();
  const config = new $OpenApi.Config({
    credential,
    endpoint: 'dysmsapi.aliyuncs.com',
  });
  
  return new Dysmsapi20170525(config);
}

/**
 * 发送短信
 * @param phoneNumbers 手机号码（支持多个，逗号分隔）
 * @param signName 短信签名
 * @param templateCode 短信模板CODE
 * @param templateParam 模板参数（JSON字符串）
 */
async function sendSms(
  phoneNumbers: string,
  signName: string,
  templateCode?: string,
  templateParam?: string
): Promise<void> {
  const client = createClient();
  
  const request = new $Dysmsapi20170525.SendSmsRequest({
    phoneNumbers,
    signName,
    templateCode,
    templateParam,
  });

  try {
    const response = await client.sendSms(request);
    console.log('发送成功:', JSON.stringify(response, null, 2));
  } catch (error: any) {
    console.error('发送失败:', error.message);
    if (error.data?.Recommend) {
      console.log('诊断建议:', error.data.Recommend);
    }
    throw error;
  }
}

// 使用示例
sendSms(
  '1380013xxxx',           // 手机号
  '阿里云',                 // 签名名称
  'SMS_123456',            // 模板CODE
  '{"code":"123456"}'      // 模板参数
);

JavaScript：

// 阿里云短信服务 SDK - Node.js 优化版本
const Dysmsapi20170525 = require('@alicloud/dysmsapi20170525');
const OpenApi = require('@alicloud/openapi-client');
const Credential = require('@alicloud/credentials');

/**
 * 创建短信服务客户端
 * 使用默认凭据链，从环境变量或配置文件中读取访问凭证
 */
function createClient() {
  const credential = new Credential.default();
  const config = new OpenApi.Config({
    credential,
    endpoint: 'dysmsapi.aliyuncs.com',
  });

  return new Dysmsapi20170525.default(config);
}

/**
 * 发送短信
 * @param {string} phoneNumbers - 手机号码（支持多个，逗号分隔）
 * @param {string} signName - 短信签名
 * @param {string} templateCode - 短信模板CODE
 * @param {string} templateParam - 模板参数（JSON字符串）
 */
async function sendSms(phoneNumbers, signName, templateCode, templateParam) {
  const client = createClient();

  const request = new Dysmsapi20170525.SendSmsRequest({
    phoneNumbers,
    signName,
    templateCode,
    templateParam,
  });

  try {
    const response = await client.sendSms(request);
    console.log('发送成功:', JSON.stringify(response, null, 2));
  } catch (error) {
    console.error('发送失败:', error.message);
    if (error.data?.Recommend) {
      console.log('诊断建议:', error.data.Recommend);
    }
    throw error;
  }
}

// 使用示例
sendSms(
  '1380013xxxx',           // 手机号
  '阿里云',                 // 签名名称
  'SMS_123456',            // 模板CODE
  '{"code":"123456"}'      // 模板参数
).catch(console.error);

module.exports = { createClient, sendSms };

下载示例代码

也可以下载示例代码，直接运行。

1. 访问SendSms。

2. 在左侧的参数配置页签，填写需要的参数信息，填写示例如下：

性能优化

• 连接复用：SDK 默认使用 HTTP 连接池，无需额外配置。

• 异步处理：短信发送是异步操作，避免阻塞主线程。

• 错误重试：对网络超时等临时性错误实现指数退避重试策略。

安全建议

• 凭证管理：始终使用环境变量或密钥管理服务存储凭证。

• 最小权限：为不同应用创建独立的 RAM 子账号，并授予最小必要权限。

• 输入验证：对用户输入的手机号、模板参数等进行严格验证和清理。

• 日志脱敏：在日志中隐藏敏感信息（手机号中间四位、验证码等）。

资源管理

• 客户端复用：在整个应用生命周期中复用同一个 Client 实例，避免频繁创建销毁。

• 错误处理：对 SDK 抛出的异常进行分类处理，区分业务错误和系统错误。

• 监控告警：记录关键指标（发送成功率、响应时间、QPS），设置监控告警。

常见问题

• AccessKey是否支持调用短信API？

• 短信服务RPC方式中签名生成示例？

• 短信服务公网IP调用接口提示拒绝访问该怎么办？

• 短信服务HTTP拼接支持ROA调用机制吗？

• 短信服务API接口中BizId参数的作用？

• 短信服务密钥会泄露吗？

• 短信服务API调用阿里云的IP服务器地址是固定的吗？

• 短信服务AccessKey和RAM用户有什么区别？

• 短信服务如何查看AccessKey？