5.6.2 使用示例

# 使用示例文档

本文档提供了一码付 C SDK 的常见使用场景和代码示例。

---

## 基本使用流程

### 完整示例

```c
#include "ocpay_sdk.h"
#include <stdio.h>
#include <stdlib.h>

int main() {
    // 1. 加载配置
    ocpay_config_t *config = ocpay_config_create();
    if (ocpay_config_load_from_file(config, "config.json") != OCPAY_SUCCESS) {
        fprintf(stderr, "加载配置失败\n");
        ocpay_config_free(config);
        return -1;
    }
    
    // 2. 创建 SDK 实例
    ocpay_sdk_t *sdk = ocpay_sdk_create();
    ocpay_sdk_set_config(sdk, config);
    
    // 3. 生成请求序列号
    char *reqsn = ocpay_generate_reqsn();
    
    // 4. 构建请求参数
    const char *params[] = {
        "reqsn", reqsn,
        "trxamt", "28940",
        "goodsdesc", "测试商品",
        "notifyurl", "https://example.com/notify",
        NULL
    };
    
    // 5. 发起请求
    const char *endpoint = "https://api.example.com/pay";
    ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params);
    
    free(reqsn);
    
    if (!resp) {
        fprintf(stderr, "请求失败: %s\n", 
                ocpay_get_error_message(ocpay_get_last_error()));
        ocpay_sdk_free(sdk);
        ocpay_config_free(config);
        return -1;
    }
    
    // 6. 处理响应
    if (ocpay_response_is_success(resp)) {
        printf("请求成功\n");
        printf("交易ID: %s\n", ocpay_response_get_string(resp, "trxid"));
    } else {
        printf("请求失败: %s\n", ocpay_response_get_error_message(resp));
    }
    
    // 7. 清理资源
    ocpay_response_free(resp);
    ocpay_sdk_free(sdk);
    ocpay_config_free(config);
    
    return 0;
}
```

---

## 配置管理

### 示例 1：从 JSON 文件加载配置

**config.json:**
```json
{
  "app_id": "your_app_id",
  "sign_type": "RSA",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
  "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "debug_enabled": 1
}
```

**代码:**
```c
#include "ocpay_config.h"
#include <stdio.h>

int main() {
    ocpay_config_t *config = ocpay_config_create();
    
    if (ocpay_config_load_from_file(config, "config.json") != OCPAY_SUCCESS) {
        fprintf(stderr, "加载配置失败\n");
        ocpay_config_free(config);
        return -1;
    }
    
    printf("配置加载成功\n");
    printf("AppID: %s\n", config->app_id);
    printf("签名类型: %s\n", config->sign_type);
    printf("调试模式: %s\n", config->debug_enabled ? "开启" : "关闭");
    
    ocpay_config_free(config);
    return 0;
}
```

### 示例 2：从环境变量加载配置

```c
#include "ocpay_config.h"
#include <stdio.h>

int main() {
    ocpay_config_t *config = ocpay_config_create();
    
    if (ocpay_config_load_from_env(config) != OCPAY_SUCCESS) {
        fprintf(stderr, "从环境变量加载配置失败\n");
        ocpay_config_free(config);
        return -1;
    }
    
    printf("配置加载成功\n");
    printf("AppID: %s\n", config->app_id);
    
    ocpay_config_free(config);
    return 0;
}
```

### 示例 3：配置验证

```c
#include "ocpay_config.h"
#include "ocpay_errors.h"
#include <stdio.h>

int main() {
    ocpay_config_t *config = ocpay_config_create();
    ocpay_config_load_from_file(config, "config.json");
    
    // 验证配置
    if (ocpay_config_validate(config) != OCPAY_SUCCESS) {
        ocpay_error_code_t err = ocpay_get_last_error();
        fprintf(stderr, "配置验证失败: %s\n", ocpay_get_error_message(err));
        ocpay_config_free(config);
        return -1;
    }
    
    printf("配置验证通过\n");
    
    ocpay_config_free(config);
    return 0;
}
```

---

## 支付请求

### 示例 1：基本支付请求

```c
#include "ocpay_sdk.h"
#include <stdio.h>
#include <stdlib.h>

int main() {
    // 初始化 SDK
    ocpay_config_t *config = ocpay_config_create();
    ocpay_config_load_from_file(config, "config.json");
    
    ocpay_sdk_t *sdk = ocpay_sdk_create();
    ocpay_sdk_set_config(sdk, config);
    
    // 生成请求序列号
    char *reqsn = ocpay_generate_reqsn();
    
    // 构建支付参数
    const char *params[] = {
        "reqsn", reqsn,                              // 请求序列号
        "trxamt", "28940",                           // 交易金额（分）
        "goodsdesc", "测试商品",                      // 商品描述
        "notifyurl", "https://example.com/notify",   // 异步通知地址
        NULL
    };
    
    // 发起支付请求
    const char *endpoint = 
        "https://dms-api-test.shopoint.cn/shopoint-openapis-web/szyx/apiweb/pay/unifiedorder";
    
    ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params);
    free(reqsn);
    
    if (resp && ocpay_response_is_success(resp)) {
        printf("支付请求成功\n");
        printf("交易ID: %s\n", ocpay_response_get_string(resp, "trxid"));
        printf("支付信息: %s\n", ocpay_response_get_string(resp, "payinfo"));
    } else {
        fprintf(stderr, "支付请求失败\n");
    }
    
    // 清理资源
    ocpay_response_free(resp);
    ocpay_sdk_free(sdk);
    ocpay_config_free(config);
    
    return 0;
}
```

### 示例 2：带可选参数的支付请求

```c
// 构建支付参数（包含可选参数）
const char *params[] = {
    "reqsn", reqsn,                              // 请求序列号（必填）
    "trxamt", "28940",                           // 交易金额（必填）
    "goodsdesc", "测试商品",                      // 商品描述（必填）
    "notifyurl", "https://example.com/notify",   // 异步通知地址（必填）
    "cusid", "266649",                           // 商户号（可选）
    "appid", "your_app_id",                      // 应用ID（可选，SDK会自动添加）
    "body", "商品详细描述",                       // 商品详情（可选）
    "remark", "备注信息",                         // 备注（可选）
    "validtime", "300",                          // 订单有效期（秒，可选）
    "limit_pay", "no_credit",                    // 支付限制（可选）
    NULL
};
```

### 示例 3：处理支付响应

```c
ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params);

if (!resp) {
    fprintf(stderr, "请求失败: %s\n", 
            ocpay_get_error_message(ocpay_get_last_error()));
    return -1;
}

if (ocpay_response_is_success(resp)) {
    printf("支付请求成功\n");
    
    // 获取交易状态
    if (ocpay_response_has(resp, "trxstatus")) {
        const char *status = ocpay_response_get_string(resp, "trxstatus");
        printf("交易状态: %s\n", status);
        
        if (strcmp(status, "0000") == 0) {
            printf("交易成功\n");
        } else if (strcmp(status, "1000") == 0) {
            printf("交易处理中\n");
        } else if (strcmp(status, "2000") == 0) {
            printf("交易失败\n");
        }
    }
    
    // 获取支付信息（二维码或链接）
    if (ocpay_response_has(resp, "payinfo")) {
        printf("支付信息: %s\n", ocpay_response_get_string(resp, "payinfo"));
    }
    
    // 获取交易ID
    if (ocpay_response_has(resp, "trxid")) {
        printf("交易ID: %s\n", ocpay_response_get_string(resp, "trxid"));
    }
} else {
    printf("支付请求失败: %s\n", ocpay_response_get_error_message(resp));
}

ocpay_response_free(resp);
```

---

## 交易查询

### 示例 1：查询交易状态

```c
#include "ocpay_sdk.h"
#include <stdio.h>
#include <stdlib.h>

int main() {
    // 初始化 SDK
    ocpay_config_t *config = ocpay_config_create();
    ocpay_config_load_from_file(config, "config.json");
    
    ocpay_sdk_t *sdk = ocpay_sdk_create();
    ocpay_sdk_set_config(sdk, config);
    
    // 生成随机字符串
    char *randomstr = ocpay_generate_random_string(16);
    
    // 构建查询参数
    const char *params[] = {
        "cusid", "266649",                       // 商户号
        "version", "11",                         // 版本号
        "reqsn", "PN20240101120000abcdef",      // 原请求序列号
        "randomstr", randomstr,                  // 随机字符串
        NULL
    };
    
    // 发起查询请求
    const char *endpoint = 
        "https://dms-api-test.shopoint.cn/shopoint-openapis-web/szyx/apiweb/tranx/query";
    
    ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params);
    free(randomstr);
    
    if (resp && ocpay_response_is_success(resp)) {
        printf("查询成功\n");
        printf("交易状态: %s\n", ocpay_response_get_string(resp, "trxstatus"));
        printf("交易金额: %s 分\n", ocpay_response_get_string(resp, "trxamt"));
    } else {
        fprintf(stderr, "查询失败\n");
    }
    
    // 清理资源
    ocpay_response_free(resp);
    ocpay_sdk_free(sdk);
    ocpay_config_free(config);
    
    return 0;
}
```

### 示例 2：解析查询响应

```c
ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params);

if (resp && ocpay_response_is_success(resp)) {
    printf("查询成功\n\n");
    
    // 基本信息
    printf("交易基本信息:\n");
    printf("  交易ID: %s\n", ocpay_response_get_string(resp, "trxid"));
    printf("  请求序列号: %s\n", ocpay_response_get_string(resp, "reqsn"));
    printf("  商户号: %s\n", ocpay_response_get_string(resp, "cusid"));
    
    // 交易状态
    const char *status = ocpay_response_get_string(resp, "trxstatus");
    printf("\n交易状态: %s", status);
    if (strcmp(status, "0000") == 0) {
        printf(" (交易成功)\n");
    } else if (strcmp(status, "1000") == 0) {
        printf(" (交易处理中)\n");
    } else if (strcmp(status, "2000") == 0) {
        printf(" (交易失败)\n");
    } else {
        printf("\n");
    }
    
    // 金额信息
    const char *amount = ocpay_response_get_string(resp, "trxamt");
    long amt = atol(amount);
    printf("交易金额: %.2f 元 (%s 分)\n", amt / 100.0, amount);
    
    // 时间信息
    if (ocpay_response_has(resp, "trxdate")) {
        printf("交易日期: %s\n", ocpay_response_get_string(resp, "trxdate"));
    }
    if (ocpay_response_has(resp, "trxtime")) {
        printf("交易时间: %s\n", ocpay_response_get_string(resp, "trxtime"));
    }
    
    // 支付方式
    if (ocpay_response_has(resp, "paytype")) {
        const char *paytype = ocpay_response_get_string(resp, "paytype");
        printf("支付方式: %s", paytype);
        if (strcmp(paytype, "W01") == 0) {
            printf(" (微信)\n");
        } else if (strcmp(paytype, "A01") == 0) {
            printf(" (支付宝)\n");
        } else {
            printf("\n");
        }
    }
}

ocpay_response_free(resp);
```

---

## 错误处理

### 示例 1：基本错误处理

```c
#include "ocpay_sdk.h"
#include "ocpay_errors.h"
#include <stdio.h>

int main() {
    ocpay_config_t *config = ocpay_config_create();
    
    if (ocpay_config_load_from_file(config, "config.json") != OCPAY_SUCCESS) {
        ocpay_error_code_t err = ocpay_get_last_error();
        fprintf(stderr, "错误: %s (错误码: %d)\n", 
                ocpay_get_error_message(err), err);
        ocpay_config_free(config);
        return -1;
    }
    
    ocpay_config_free(config);
    return 0;
}
```

### 示例 2：详细错误处理

```c
ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params);

if (!resp) {
    // 获取错误码
    ocpay_error_code_t err = ocpay_get_last_error();
    
    // 根据错误码进行不同处理
    switch (err) {
        case OCPAY_ERR_INVALID_CONFIG:
            fprintf(stderr, "配置错误，请检查配置文件\n");
            break;
        
        case OCPAY_ERR_SIGN_FAILED:
            fprintf(stderr, "签名失败，请检查私钥是否正确\n");
            break;
        
        case OCPAY_ERR_NETWORK_FAILED:
            fprintf(stderr, "网络请求失败，请检查网络连接\n");
            break;
        
        case OCPAY_ERR_VERIFY_FAILED:
            fprintf(stderr, "验签失败，请检查公钥是否正确\n");
            break;
        
        default:
            fprintf(stderr, "未知错误: %s\n", ocpay_get_error_message(err));
            break;
    }
    
    return -1;
}
```

### 示例 3：响应错误处理

```c
ocpay_response_t *resp = ocpay_sdk_request(sdk, endpoint, params);

if (resp) {
    if (ocpay_response_is_success(resp)) {
        printf("请求成功\n");
    } else {
        // 获取响应中的错误信息
        const char *retcode = ocpay_response_get_string(resp, "retcode");
        const char *retmsg = ocpay_response_get_error_message(resp);
        
        fprintf(stderr, "请求失败\n");
        fprintf(stderr, "返回码: %s\n", retcode ? retcode : "未知");
        fprintf(stderr, "错误信息: %s\n", retmsg ? retmsg : "未知错误");
        
        // 根据返回码进行处理
        if (retcode && strcmp(retcode, "FAIL") == 0) {
            fprintf(stderr, "业务处理失败，请检查请求参数\n");
        }
    }
    
    ocpay_response_free(resp);
} else {
    fprintf(stderr, "请求失败: %s\n", 
            ocpay_get_error_message(ocpay_get_last_error()));
}
```

---

## 高级用法

### 示例 1：调试模式

```c
// 在配置中启用调试模式
config->debug_enabled = 1;

// 或在配置文件中设置
{
  "debug_enabled": 1
}

// 调试模式下会输出详细的日志信息：
// - 待签名字符串
// - 请求参数
// - 响应数据
```

### 示例 2：自定义请求序列号

```c
// 使用自定义格式的请求序列号
char reqsn[64];
time_t now = time(NULL);
struct tm *tm_info = localtime(&now);
char timestamp[32];
strftime(timestamp, sizeof(timestamp), "%Y%m%d%H%M%S", tm_info);

// 生成随机字符串
char *random = ocpay_generate_random_string(16);
snprintf(reqsn, sizeof(reqsn), "PN%s%s", timestamp, random);
free(random);

printf("请求序列号: %s\n", reqsn);
```

### 示例 3：批量查询

```c
// 查询多个交易
const char *reqsn_list[] = {
    "PN20240101120000abcdef",
    "PN20240101120001ghijkl",
    "PN20240101120002mnopqr",
    NULL
};

for (int i = 0; reqsn_list[i] != NULL; i++) {
    char *randomstr = ocpay_generate_random_string(16);
    
    const char *params[] = {
        "cusid", "266649",
        "version", "11",
        "reqsn", reqsn_list[i],
        "randomstr", randomstr,
        NULL
    };
    
    ocpay_response_t *resp = ocpay_sdk_request(sdk, query_endpoint, params);
    free(randomstr);
    
    if (resp && ocpay_response_is_success(resp)) {
        printf("交易 %s 状态: %s\n", 
               reqsn_list[i], 
               ocpay_response_get_string(resp, "trxstatus"));
    }
    
    ocpay_response_free(resp);
}
```

### 示例 4：重试机制

```c
#include <unistd.h>  // for sleep()

#define MAX_RETRIES 3
#define RETRY_DELAY 2  // 秒

ocpay_response_t *resp = NULL;
int retry_count = 0;

while (retry_count < MAX_RETRIES) {
    resp = ocpay_sdk_request(sdk, endpoint, params);
    
    if (resp) {
        break;  // 请求成功
    }
    
    // 检查错误类型
    ocpay_error_code_t err = ocpay_get_last_error();
    if (err == OCPAY_ERR_NETWORK_FAILED) {
        retry_count++;
        printf("网络请求失败，%d 秒后重试 (%d/%d)...\n", 
               RETRY_DELAY, retry_count, MAX_RETRIES);
        sleep(RETRY_DELAY);
    } else {
        // 其他错误不重试
        break;
    }
}

if (!resp) {
    fprintf(stderr, "请求失败，已重试 %d 次\n", retry_count);
}
```

### 示例 5：多配置管理

```c
// 管理多个商户的配置
typedef struct {
    const char *name;
    ocpay_config_t *config;
    ocpay_sdk_t *sdk;
} merchant_t;

merchant_t merchants[] = {
    {"商户A", NULL, NULL},
    {"商户B", NULL, NULL},
    {NULL, NULL, NULL}
};

// 初始化所有商户
for (int i = 0; merchants[i].name != NULL; i++) {
    char config_file[256];
    snprintf(config_file, sizeof(config_file), "config_%s.json", merchants[i].name);
    
    merchants[i].config = ocpay_config_create();
    ocpay_config_load_from_file(merchants[i].config, config_file);
    
    merchants[i].sdk = ocpay_sdk_create();
    ocpay_sdk_set_config(merchants[i].sdk, merchants[i].config);
    
    printf("商户 %s 初始化成功\n", merchants[i].name);
}

// 使用特定商户的 SDK
ocpay_response_t *resp = ocpay_sdk_request(merchants[0].sdk, endpoint, params);

// 清理所有商户
for (int i = 0; merchants[i].name != NULL; i++) {
    ocpay_sdk_free(merchants[i].sdk);
    ocpay_config_free(merchants[i].config);
}
```

---

## 完整示例程序

完整的示例程序可以在 `examples/` 目录中找到：

- `basic_usage.c` - 基本使用示例，演示完整的支付流程
- `query_transaction.c` - 交易查询示例，演示如何查询交易状态

编译并运行示例：

```bash
# 编译
make

# 运行基本使用示例
./examples/basic_usage

# 运行交易查询示例
./examples/query_transaction PN20240101120000abcdef
```

---

## 注意事项

1. **内存管理**：所有动态分配的对象（config、sdk、response）都需要手动释放
2. **参数数组**：传递给 `ocpay_sdk_request()` 的参数数组必须以 `NULL` 结尾
3. **错误处理**：始终检查函数返回值，并使用 `ocpay_get_last_error()` 获取详细错误信息
4. **线程安全**：SDK 不保证线程安全，多线程环境下每个线程应创建独立的 SDK 实例
5. **配置安全**：不要将配置文件提交到版本控制系统，建议使用环境变量或加密存储

---