联通短信接口集成指南：Java与JS双端实现详解

一、技术选型与接口特性

联通短信接口采用RESTful API设计，支持HTTP/HTTPS协议，提供验证码发送、营销短信、通知类短信三大核心功能。接口参数包括appId（应用标识）、timestamp（时间戳）、sign（数字签名）等安全验证字段，其中签名算法采用MD5加密，需将参数按字典序拼接后与密钥组合生成。

Java端推荐使用Apache HttpClient 4.5+或OkHttp 3.x实现HTTP请求，JS端可通过axios或原生Fetch API调用。两种技术栈均需处理异步回调与错误重试机制，Java可通过CompletableFuture实现，JS则依赖Promise或async/await语法。

二、Java实现关键步骤

1. 依赖配置

Maven项目需引入以下依赖：

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.13</version>
</dependency>
<dependency>
    <groupId>commons-codec</groupId>
    <artifactId>commons-codec</artifactId>
    <version>1.15</version>
</dependency>

2. 签名生成算法

public class SignUtil {
    public static String generateSign(Map<String, String> params, String secretKey) {
        // 参数按字典序排序
        params.entrySet().stream()
            .filter(e -> e.getValue() != null)
            .sorted(Map.Entry.comparingByKey())
            .forEach(e -> params.put(e.getKey(), e.getValue()));
        // 拼接签名串
        StringBuilder sb = new StringBuilder();
        params.forEach((k, v) -> sb.append(k).append("=").append(v).append("&"));
        sb.append("key=").append(secretKey);
        // MD5加密并转大写
        return DigestUtils.md5Hex(sb.toString()).toUpperCase();
    }
}

3. 完整请求示例

public class SmsSender {
    private static final String URL = "https://api.10010.com/sms/send";
    public static boolean sendSms(String phone, String content) throws Exception {
        CloseableHttpClient httpClient = HttpClients.createDefault();
        HttpPost httpPost = new HttpPost(URL);
        // 构建请求参数
        Map<String, String> params = new HashMap<>();
        params.put("appId", "YOUR_APP_ID");
        params.put("timestamp", String.valueOf(System.currentTimeMillis()));
        params.put("phone", phone);
        params.put("content", content);
        params.put("sign", SignUtil.generateSign(params, "YOUR_SECRET_KEY"));
        // 设置请求体
        List<NameValuePair> nvps = new ArrayList<>();
        params.forEach((k, v) -> nvps.add(new BasicNameValuePair(k, v)));
        httpPost.setEntity(new UrlEncodedFormEntity(nvps, "UTF-8"));
        // 执行请求
        try (CloseableHttpResponse response = httpClient.execute(httpPost)) {
            String result = EntityUtils.toString(response.getEntity());
            return "0000".equals(JSON.parseObject(result).getString("code"));
        }
    }
}

三、JavaScript实现要点

1. 浏览器端实现

async function sendSms(phone, content) {
    const params = new URLSearchParams();
    params.append('appId', 'YOUR_APP_ID');
    params.append('timestamp', Date.now());
    params.append('phone', phone);
    params.append('content', content);
    // 生成签名（需后端提供签名服务或使用WebAssembly）
    const sign = await generateSign(params, 'YOUR_SECRET_KEY');
    params.append('sign', sign);
    try {
        const response = await fetch('https://api.10010.com/sms/send', {
            method: 'POST',
            body: params,
            headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
        });
        const data = await response.json();
        return data.code === '0000';
    } catch (error) {
        console.error('SMS send failed:', error);
        return false;
    }
}
// 实际项目中建议将签名生成放在服务端
async function generateSign(params, secretKey) {
    // 模拟签名生成（实际需实现完整算法）
    return 'MOCK_SIGNATURE';
}

2. Node.js服务端实现

const axios = require('axios');
const crypto = require('crypto');
function generateSign(params, secretKey) {
    const sortedParams = Object.keys(params)
        .filter(key => params[key] !== null)
        .sort()
        .map(key => `${key}=${params[key]}`)
        .join('&');
    const signStr = `${sortedParams}&key=${secretKey}`;
    return crypto.createHash('md5').update(signStr).digest('hex').toUpperCase();
}
async function sendSms(phone, content) {
    const params = {
        appId: 'YOUR_APP_ID',
        timestamp: Date.now(),
        phone,
        content
    };
    params.sign = generateSign(params, 'YOUR_SECRET_KEY');
    try {
        const response = await axios.post('https://api.10010.com/sms/send', 
            new URLSearchParams(params),
            { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
        );
        return response.data.code === '0000';
    } catch (error) {
        console.error('SMS send failed:', error.response?.data || error.message);
        return false;
    }
}

四、安全优化方案

1. 密钥管理：采用KMS（密钥管理服务）存储密钥，Java端通过JCEKS密钥库，JS端通过环境变量注入
2. IP白名单：在联通控制台配置允许访问的服务器IP
3. 频率限制：实现令牌桶算法控制发送速率，Java可使用Guava RateLimiter
4. 内容过滤：对短信内容进行敏感词检测，JS端可使用正则表达式预检

五、异常处理机制

1. 错误码对照表

错误码	含义	处理方案
1001	参数缺失	检查必填字段
2003	签名错误	重新生成签名
3005	频率超限	指数退避重试
9999	系统异常	切换备用接口

2. 重试策略实现

// Java重试机制示例
public class RetryUtil {
    public static <T> T executeWithRetry(Callable<T> task, int maxRetries, long delayMillis) 
            throws Exception {
        Exception lastException = null;
        for (int i = 0; i < maxRetries; i++) {
            try {
                return task.call();
            } catch (Exception e) {
                lastException = e;
                if (i < maxRetries - 1) {
                    Thread.sleep(delayMillis * (long) Math.pow(2, i));
                }
            }
        }
        throw lastException;
    }
}

六、性能优化建议

1. 连接池配置：Java端配置HttpClient连接池

   PoolingHttpClientConnectionManager cm = new PoolingHttpClientConnectionManager();
   cm.setMaxTotal(200);
   cm.setDefaultMaxPerRoute(20);

2. 异步非阻塞：JS端使用WebSocket长连接替代短连接
3. 批量发送：联通接口支持批量发送，Java可通过多线程并发处理

七、监控与日志

1. 调用统计：记录发送成功率、平均耗时等指标
2. 日志规范：Java使用Log4j2，JS使用winston，记录请求参数（脱敏后）、响应结果
3. 告警机制：当连续失败超过阈值时触发告警

通过以上技术实现，开发者可构建稳定、高效的联通短信服务系统。实际开发中需根据业务场景调整参数配置，并定期进行压力测试确保系统可靠性。