194 lines
3.8 KiB
Markdown
194 lines
3.8 KiB
Markdown
# 阿里云二要素验证服务
|
||
|
||
这个服务提供了调用阿里云身份证二要素验证API的功能，用于验证姓名和身份证号码是否匹配。
|
||
|
||
## 功能特性
|
||
|
||
- 身份证二要素验证（姓名 + 身份证号）
|
||
- 支持详细验证结果返回
|
||
- 支持简单布尔值判断
|
||
- 错误处理和中文错误信息
|
||
|
||
## 配置说明
|
||
|
||
### 必需配置
|
||
|
||
- `Host`: 阿里云API的域名地址
|
||
- `AppCode`: 阿里云市场应用的AppCode
|
||
|
||
### 配置示例
|
||
|
||
```go
|
||
host := "https://kzidcardv1.market.alicloudapi.com"
|
||
appCode := "您的AppCode"
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 1. 创建服务实例
|
||
|
||
```go
|
||
service := NewAlicloudService(host, appCode)
|
||
```
|
||
|
||
### 2. 调用API
|
||
|
||
#### 身份证二要素验证示例
|
||
|
||
```go
|
||
// 构建请求参数
|
||
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调用
|
||
|
||
```go
|
||
// 调用其他阿里云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))
|
||
```
|
||
|
||
## 响应格式
|
||
|
||
### 通用响应结构
|
||
|
||
```json
|
||
{
|
||
"msg": "成功",
|
||
"success": true,
|
||
"code": 200,
|
||
"data": {
|
||
// 具体的业务数据
|
||
}
|
||
}
|
||
```
|
||
|
||
### 身份证验证响应示例
|
||
|
||
#### 成功响应 (code: 200)
|
||
|
||
```json
|
||
{
|
||
"msg": "成功",
|
||
"success": true,
|
||
"code": 200,
|
||
"data": {
|
||
"birthday": "19840816",
|
||
"result": 1,
|
||
"address": "浙江省杭州市淳安县",
|
||
"orderNo": "202406271440416095174",
|
||
"sex": "男",
|
||
"desc": "不一致"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 参数错误响应 (code: 400)
|
||
|
||
```json
|
||
{
|
||
"msg": "请输入有效的身份证号码",
|
||
"code": 400,
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
```json
|
||
{
|
||
"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` |