tyapi-server/internal/infrastructure/external/alicloud/README.md

阿里云二要素验证服务

这个服务提供了调用阿里云身份证二要素验证API的功能，用于验证姓名和身份证号码是否匹配。

功能特性

• 身份证二要素验证（姓名 + 身份证号）
• 支持详细验证结果返回
• 支持简单布尔值判断
• 错误处理和中文错误信息

配置说明

必需配置

• Host: 阿里云API的域名地址
• AppCode: 阿里云市场应用的AppCode

配置示例

host := "https://kzidcardv1.market.alicloudapi.com"
appCode := "您的AppCode"

使用方法

1. 创建服务实例

service := NewAlicloudService(host, appCode)

2. 调用API

身份证二要素验证示例

// 构建请求参数
params := map[string]interface{}{
    "name":   "张三",
    "idcard": "110101199001011234",
}

// 调用API
responseBody, err := service.CallAPI("api-mall/api/id_card/check", params)
if err != nil {
    log.Printf("验证失败: %v", err)
    return
}

// 解析完整响应结构
var response struct {
    Msg     string `json:"msg"`
    Success bool   `json:"success"`
    Code    int    `json:"code"`
    Data    struct {
        Birthday string `json:"birthday"`
        Result   int    `json:"result"`
        Address  string `json:"address"`
        OrderNo  string `json:"orderNo"`
        Sex      string `json:"sex"`
        Desc     string `json:"desc"`
    } `json:"data"`
}

if err := json.Unmarshal(responseBody, &response); err != nil {
    log.Printf("响应解析失败: %v", err)
    return
}

// 检查响应状态
if response.Code != 200 {
    log.Printf("API返回错误: code=%d, msg=%s", response.Code, response.Msg)
    return
}

idCardData := response.Data

// 判断验证结果
if idCardData.Result == 1 {
    fmt.Println("身份证信息验证通过")
} else {
    fmt.Println("身份证信息验证失败")
}

通用API调用

// 调用其他阿里云API
params := map[string]interface{}{
    "param1": "value1",
    "param2": "value2",
}

responseBody, err := service.CallAPI("your/api/path", params)
if err != nil {
    log.Printf("API调用失败: %v", err)
    return
}

// 根据具体API的响应结构进行解析
// 每个API的响应结构可能不同，需要根据API文档定义相应的结构体
var response struct {
    Msg  string      `json:"msg"`
    Code int         `json:"code"`
    Data interface{} `json:"data"`
}

if err := json.Unmarshal(responseBody, &response); err != nil {
    log.Printf("响应解析失败: %v", err)
    return
}

// 处理响应数据
fmt.Printf("响应数据: %s\n", string(responseBody))

响应格式

通用响应结构

{
    "msg": "成功",
    "success": true,
    "code": 200,
    "data": {
        // 具体的业务数据
    }
}

身份证验证响应示例

成功响应 (code: 200)

{
    "msg": "成功",
    "success": true,
    "code": 200,
    "data": {
        "birthday": "19840816",
        "result": 1,
        "address": "浙江省杭州市淳安县",
        "orderNo": "202406271440416095174",
        "sex": "男",
        "desc": "不一致"
    }
}

参数错误响应 (code: 400)

{
    "msg": "请输入有效的身份证号码",
    "code": 400,
    "data": null
}

错误响应

{
    "msg": "AppCode无效",
    "success": false,
    "code": 400
}

错误处理

服务定义了以下错误类型：

• ErrDatasource: 数据源异常
• ErrSystem: 系统异常
• ErrInvalid: 身份证信息不匹配

注意事项

1. 请确保您的AppCode有效且有足够的调用额度
2. 身份证号码必须是18位有效格式
3. 姓名必须是真实有效的姓名
4. 建议在生产环境中添加适当的重试机制和超时设置
5. 请遵守阿里云API的使用规范和频率限制

依赖

• Go 1.16+
• 标准库：net/http, encoding/json, net/url