Java 發送手機短信實戰：基於 HTTP API 的完整實現

前言

Java 發送短信主流方案為調用第三方 HTTP API。本文提供基於 HttpClient 的生產級實現代碼，含簽名驗證、異常處理、配置管理。

主流方案對比

HTTP API 完整實現 (Apache HttpClient 4.5+)

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.ContentType;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import java.nio.charset.StandardCharsets;

public class SmsSender {
    private final String apiUrl;
    private final String uid;
    private final String key;
    private final CloseableHttpClient httpClient;
    
    public SmsSender(String apiUrl, String uid, String key) {
        this.apiUrl = apiUrl;
        this.uid = uid;
        this.key = key;
        this.httpClient = HttpClients.createDefault();
    }
    
    /**
     * 發送短信
     * @param mobile 手機號
     * @param content 內容 (建議 ≤ 70 字符，超長自動分條計費)
     * @return 平台返回碼/消息
     */
    public String send(String mobile, String content) {
        HttpPost post = new HttpPost(apiUrl);
        post.setHeader("Content-Type", "application/x-www-form-urlencoded;charset=UTF-8");
        
        String form = String.format("Uid=%s&Key=%s&smsMob=%s&smsText=%s",
            uid, key, mobile, java.net.URLEncoder.encode(content, StandardCharsets.UTF_8));
        post.setEntity(new StringEntity(form, ContentType.APPLICATION_FORM_URLENCODED));
        
        try (CloseableHttpResponse resp = httpClient.execute(post)) {
            String body = EntityUtils.toString(resp.getEntity(), StandardCharsets.UTF_8);
            int status = resp.getStatusLine().getStatusCode();
            if (status != 200) throw new RuntimeException("HTTP " + status + ": " + body);
            return body; // 平台具體返回格式查閱文檔
        } catch (Exception e) {
            throw new RuntimeException("發送失敗: " + mobile, e);
        }
    }
    
    public void shutdown() throws Exception { httpClient.close(); }
}

Spring Boot 整合配置

# application.yml
sms:
  api-url: https://sms.example.com/api/send
  uid: your_uid
  key: your_key
  sign-name: 【您的簽名】 # 內容前綴，按平台要求

@ConfigurationProperties(prefix = "sms")
@Component
public class SmsProperties {
    private String apiUrl, uid, key, signName;
    // getter/setter
}

@Service
public class SmsService {
    private final SmsSender sender;
    private final String signName;
    
    public SmsService(SmsProperties props) {
        this.sender = new SmsSender(props.getApiUrl(), props.getUid(), props.getKey());
        this.signName = props.getSignName();
    }
    
    public void sendVerificationCode(String mobile, String code) {
        String content = signName + "您的驗證碼是 " + code + "，5 分鐘內有效。";
        sender.send(mobile, content);
    }
    
    @PreDestroy
    public void destroy() throws Exception { sender.shutdown(); }
}

生產級增強建議

• 異步發送：@Async + 線程池，避免阻塞業務線程
• 幂等性：業務層去重 (如同一手機 60s 內不重發)
• 重試機制：網絡異常指數退避重試 (3 次)
• 發送記錄：持久化發送日誌 (手機、內容、狀態、平台返回碼) 供對賬
• 簽名/模板審核：內容需符合運營商規範，變量部分使用模板

常見平台返回碼對照

// 示例，實際以平台文檔為準
0  成功
-1 參數錯誤
-2 賬號/密鑰錯誤
-3 餘額不足
-4 手機號格式錯誤
-5 內容含敏感詞
-6 同一手機發送過於頻繁