# 阿里云短信服务 Java SDK 调用指南

## 前置准备

| 步骤 | 说明 | 参考链接 |
|------|------|----------|
| 1. 查看 API 文档 | 了解 SendSms 接口参数 | [SendSms API](https://help.aliyun.com/zh/sms/developer-reference/api-dysmsapi-2017-05-25-sendsms) |
| 2. 创建 RAM 用户 | 建议使用 RAM 用户而非主账号 | [RAM 用户概览](https://help.aliyun.com/zh/ram/user-guide/overview-of-ram-users) |
| 3. 创建 AccessKey | 获取 AccessKey ID 和 Secret | [创建访问密钥](https://help.aliyun.com/zh/ram/user-guide/create-an-accesskey-pair) |

## 环境配置

### Java 版本要求
- Java 8 或更高版本

### Maven 依赖

```xml
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>dysmsapi20170525</artifactId>
    <version>the-latest-version</version>
</dependency>
```

> 最新版本号：https://mvnrepository.com/artifact/com.aliyun/dysmsapi20170525

### 环境变量配置

| 环境变量名 | 说明 | 示例值 |
|-----------|------|--------|
| `ALIBABA_CLOUD_ACCESS_KEY_ID` | AccessKey ID | `LTAI5t...` |
| `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | AccessKey Secret | `xxx...` |

> 配置方法：[Linux/macOS/Windows 环境变量配置](https://help.aliyun.com/zh/sdk/developer-reference/configure-the-alibaba-cloud-accesskey-environment-variable-on-linux-macos-and-windows-systems)

## 代码示例

```java
package com.aliyun.sample;

import com.aliyun.teaopenapi.models.Config;
import com.aliyun.dysmsapi20170525.Client;
import com.aliyun.dysmsapi20170525.models.SendSmsRequest;
import com.aliyun.dysmsapi20170525.models.SendSmsResponse;
import static com.aliyun.teautil.Common.toJSONString;

public class Sample {
    public static Client createClient() throws Exception {
        Config config = new Config()
            // 从环境变量读取 AccessKey ID
            .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
            // 从环境变量读取 AccessKey Secret
            .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        
        // 配置 Endpoint
        config.endpoint = "dysmsapi.aliyuncs.com";
        
        return new Client(config);
    }

    public static void main(String[] args) throws Exception {
        // 初始化客户端
        Client client = Sample.createClient();
        
        // 构造请求对象
        SendSmsRequest sendSmsRequest = new SendSmsRequest()
            .setPhoneNumbers("1390000****")           // 接收短信的手机号
            .setSignName("阿里云")                      // 短信签名
            .setTemplateCode("SMS_15305****")          // 短信模板代码
            .setTemplateParam("{\"name\":\"张三\",\"number\":\"1390000****\"}"); // 模板参数（JSON 字符串）
        
        // 发送短信
        SendSmsResponse sendSmsResponse = client.sendSms(sendSmsRequest);
        
        // 输出响应
        System.out.println(toJSONString(sendSmsResponse));
    }
}
```

## 请求参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `PhoneNumbers` | String | 是 | 接收短信的手机号，多个号码用逗号分隔 |
| `SignName` | String | 是 | 短信签名，需在控制台审核通过 |
| `TemplateCode` | String | 是 | 短信模板代码，需在控制台审核通过 |
| `TemplateParam` | String | 否 | 模板参数，JSON 格式字符串 |

## 响应格式

```json
{
  "headers": {
    "x-acs-request-id": "F59B3F78-D9CD-5D01-A9CC-AE5C921ED9C0",
    "content-type": "application/json;charset=utf-8"
  },
  "statusCode": 200,
  "body": {
    "bizId": "695425589610909881^0",
    "code": "OK",
    "message": "OK",
    "requestId": "F59B3F78-D9CD-5D01-A9CC-AE5C921ED9C0"
  }
}
```

### 响应字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `bizId` | String | 业务流水号，用于查询发送状态 |
| `code` | String | 状态码，`OK` 表示成功 |
| `message` | String | 状态描述 |
| `requestId` | String | 请求 ID，用于问题排查 |

## 注意事项

1. **安全建议**：使用环境变量存储 AccessKey，避免硬编码
2. **RAM 用户**：建议使用 RAM 用户而非主账号进行 API 调用
3. **签名和模板**：需在阿里云控制台提前申请并审核通过
4. **模板参数**：必须是有效的 JSON 字符串，参数名需与模板中的变量名一致

## 相关链接

- [API 概览](https://help.aliyun.com/zh/sms/developer-reference/api-dysmsapi-2017-05-25-overview)
- [SDK 下载](https://api.aliyun.com/api-tools/sdk/Dysmsapi?version=2017-05-25&language=java-tea)
- [常见问题](https://help.aliyun.com/zh/sms/developer-reference/api-sdk-faq)