wechat-api-rs 0.1.0

# 快速开始指南

本指南将带你快速上手使用WeChat SDK for Rust，从安装到运行第一个示例。

## 📋 前置条件

### 系统要求
- Rust 1.70+ 
- 网络连接（用于下载依赖和调用微信API）

### 微信开发者账号
- [微信公众平台](https://mp.weixin.qq.com/) 账号（公众号开发）
- [微信开放平台](https://open.weixin.qq.com/) 账号（小程序开发）

## 🚀 安装SDK

### 1. 创建新的Rust项目

```bash
cargo new my-wechat-app
cd my-wechat-app
```

### 2. 添加依赖到 `Cargo.toml`

```toml
[dependencies]
wechat-sdk = "0.1.0"
tokio = { version = "1.0", features = ["full"] }
tracing-subscriber = "0.3"  # 用于日志输出
```

### 3. 设置环境变量

创建 `.env` 文件：

```env
# 微信公众号/小程序配置
WECHAT_APP_ID=wx1234567890123456
WECHAT_APP_SECRET=your_32_char_app_secret_here
WECHAT_TOKEN=your_token_here
WECHAT_ENCODING_AES_KEY=your_43_char_encoding_aes_key_here
```

> ⚠️ **安全提醒**：不要将真实的密钥提交到版本控制系统中！

## 💡 第一个示例

### 基础客户端创建

在 `src/main.rs` 中：

```rust
use wechat_sdk::{WeChat, Result};

#[tokio::main]
async fn main() -> Result<()> {
    // 初始化日志
    tracing_subscriber::init();

    // 创建微信客户端
    let client = WeChat::builder()
        .app_id(std::env::var("WECHAT_APP_ID").expect("WECHAT_APP_ID required"))
        .app_secret(std::env::var("WECHAT_APP_SECRET").expect("WECHAT_APP_SECRET required"))
        .timeout(std::time::Duration::from_secs(30))
        .build()?;

    println!("✅ 微信SDK初始化成功！");
    println!("📱 App ID: {}", client.core().app_id());

    Ok(())
}
```

运行：
```bash
cargo run
```

## 📱 公众号开发示例

### 发送消息

```rust
use wechat_sdk::{WeChat, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = WeChat::builder()
        .app_id("your_app_id")
        .app_secret("your_app_secret")
        .build()?;

    // 发送文本消息
    client.official()
        .message()
        .to("user_openid")
        .text("Hello from Rust!")
        .send().await?;

    println!("✅ 消息发送成功！");
    Ok(())
}
```

### 消息处理服务器

```rust
use wechat_sdk::WeChat;
use std::collections::HashMap;

// 消息处理函数
async fn handle_message(body: &str) -> String {
    println!("📨 收到消息: {}", body);
    
    // 这里解析XML消息并处理
    // 返回XML格式的回复
    format!(r#"
    <xml>
        <ToUserName><![CDATA[{}]]></ToUserName>
        <FromUserName><![CDATA[{}]]></FromUserName>
        <CreateTime>{}</CreateTime>
        <MsgType><![CDATA[text]]></MsgType>
        <Content><![CDATA[Hello from Rust SDK!]]></Content>
    </xml>"#, "user", "official", chrono::Utc::now().timestamp())
}
```

## 📲 小程序开发示例

### 登录验证

```rust
use wechat_sdk::{WeChat, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = WeChat::builder()
        .app_id("your_miniapp_app_id")
        .app_secret("your_miniapp_app_secret")
        .build()?;

    // 小程序登录
    let session = client.miniapp()
        .auth()
        .code_to_session("js_code_from_miniapp")
        .call().await?;

    println!("✅ 登录成功！");
    println!("🔑 OpenID: {}", session.openid);
    println!("🔐 Session Key: {}", session.session_key);

    Ok(())
}
```

### 数据解密

```rust
use wechat_sdk::{WeChat, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = WeChat::builder()
        .app_id("your_app_id")
        .app_secret("your_app_secret")
        .build()?;

    // 解密用户数据
    let user_info = client.miniapp()
        .crypto()
        .decrypt_data(
            "session_key",
            "encrypted_data", 
            "iv"
        ).await?;

    println!("👤 用户昵称: {}", user_info.nick_name);
    println!("🌍 用户城市: {}", user_info.city);

    Ok(())
}
```

## 🌐 Web服务器集成

### 使用Axum框架

```toml
[dependencies]
wechat-sdk = "0.1.0"
axum = "0.7"
tokio = { version = "1.0", features = ["full"] }
```

```rust
use wechat_sdk::WeChat;
use axum::{
    extract::State,
    routing::{get, post},
    Json, Router,
};
use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    wechat: Arc<WeChat>,
}

#[tokio::main]
async fn main() {
    let client = WeChat::builder()
        .app_id(std::env::var("WECHAT_APP_ID").unwrap())
        .app_secret(std::env::var("WECHAT_APP_SECRET").unwrap())
        .build()
        .unwrap();

    let state = AppState {
        wechat: Arc::new(client),
    };

    let app = Router::new()
        .route("/wechat/verify", get(wechat_verify))
        .route("/miniapp/login", post(miniapp_login))
        .with_state(state);

    println!("🚀 服务器启动在 http://0.0.0.0:3000");
    
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

// 微信服务器验证
async fn wechat_verify() -> &'static str {
    "Hello WeChat!"
}

// 小程序登录接口
async fn miniapp_login(
    State(state): State<AppState>,
    Json(payload): Json<serde_json::Value>,
) -> Json<serde_json::Value> {
    // 处理小程序登录逻辑
    Json(serde_json::json!({"success": true}))
}
```

## 🔧 常见配置

### 1. 超时设置

```rust
let client = WeChat::builder()
    .app_id("your_app_id")
    .app_secret("your_app_secret")
    .timeout(std::time::Duration::from_secs(60))  // 60秒超时
    .build()?;
```

### 2. 只使用特定功能

```toml
# 只使用公众号功能
[dependencies]
wechat-sdk = { version = "0.1.0", default-features = false, features = ["official"] }

# 只使用小程序功能
wechat-sdk = { version = "0.1.0", default-features = false, features = ["miniapp"] }
```

### 3. 配置文件管理

创建 `wechat.toml`：

```toml
app_id = "wx1234567890123456"
app_secret = "your_app_secret_here"
timeout_seconds = 30

[cache]
redis_url = "redis://localhost:6379"
key_prefix = "wechat:"
```

```rust
use wechat_sdk::config::WeChatConfig;

let config = WeChatConfig::from_file("wechat.toml")?;
let client = config.build_client()?;
```

## ❓ 常见问题

### Q1: 如何获取APP ID和APP Secret？

**公众号：**
1. 登录[微信公众平台](https://mp.weixin.qq.com/)
2. 进入"开发" → "基本配置"
3. 找到"开发者ID(AppID)"和"开发者密码(AppSecret)"

**小程序：**
1. 登录[小程序后台](https://mp.weixin.qq.com/)
2. 进入"开发" → "开发设置"
3. 找到"小程序ID"和"小程序密钥"

### Q2: 遇到网络错误怎么办？

检查：
- 网络连接是否正常
- 防火墙设置
- 代理配置
- API调用频率是否超限

### Q3: 如何调试API调用？

```rust
// 启用详细日志
tracing_subscriber::fmt()
    .with_max_level(tracing::Level::DEBUG)
    .init();

// 设置更长的超时时间
let client = WeChat::builder()
    .timeout(std::time::Duration::from_secs(120))
    .build()?;
```

## 🎯 下一步

现在你已经完成了基础设置，可以：

1. 查看 [API使用文档](./api-reference.md) 了解详细的API使用方法
2. 阅读 [配置指南](./configuration.md) 学习高级配置
3. 参考 [最佳实践](./best-practices.md) 构建生产级应用
4. 浏览 [示例代码](../examples/) 获取更多灵感

## 🆘 获取帮助

如果遇到问题：

1. 查看 [API文档](https://docs.rs/wechat-sdk)
2. 搜索 [GitHub Issues](https://github.com/your-username/wechat-sdk-rust/issues)
3. 创建新的 [Issue](https://github.com/your-username/wechat-sdk-rust/issues/new)

---

**祝你开发愉快！🎉**