一、准备

1、购买阿里云的三要素核验套餐包

根据你的业务量选择购买

地址：

https://www.aliyun.com/product/dytns/

2、申请开通三要素一致性核验

调用三要素校验的接口需要授权ID，到号码百科这一功能的标签广场申请

我这里已经申请通过了，点击“立即使用”可跳转查看授权ID

3、查看AccessKey

目前调用过的阿里云的接口都需要“AccessKey ID”和“AccessKey Secret”，登录阿里云后，点击头像“AccessKey管理”

如果有多组，任意拿一组就行了。

二、调用三要素核验接口

1、查看接口文档

地址：

https://help.aliyun.com/zh/cpns/developer-reference/api-dytnsapi-2020-02-17-threeelementsverification?spm=a2c4g.11186623.4.6.5ca451cdWl3z2V&scm=20140722.H_433414._.ID_433414-OR_rec-V_1

2、查看阿里云的调用示例

点击文档右边的调试可进入阿里云的调试页

代码示例在“SDK示例-Java”

也可以下载完整工程

3、阿里云完整示例代码

在使用之前先导入三要素核验的依赖

<dependency><groupId>com.aliyun</groupId><artifactId>dytnsapi20200217</artifactId><version>2.1.0</version>
</dependency>

代码如下：

// This file is auto-generated, don't edit it. Thanks.
package com.aliyun.sample;import com.aliyun.tea.*;public class Sample {/*** 使用AK&SK初始化账号Client* @param accessKeyId* @param accessKeySecret* @return Client* @throws Exception*/public static com.aliyun.dytnsapi20200217.Client createClient(String accessKeyId, String accessKeySecret) throws Exception {com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()// 必填，您的 AccessKey ID.setAccessKeyId(accessKeyId)// 必填，您的 AccessKey Secret.setAccessKeySecret(accessKeySecret);// Endpoint 请参考 https://api.aliyun.com/product/Dytnsapiconfig.endpoint = "dytnsapi.aliyuncs.com";return new com.aliyun.dytnsapi20200217.Client(config);}public static void main(String[] args_) throws Exception {java.util.List<String> args = java.util.Arrays.asList(args_);// 请确保代码运行环境设置了环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET。// 工程代码泄露可能会导致 AccessKey 泄露，并威胁账号下所有资源的安全性。以下代码示例使用环境变量获取 AccessKey 的方式进行调用，仅供参考，建议使用更安全的 STS 方式，更多鉴权访问方式请参见：https://help.aliyun.com/document_detail/378657.htmlcom.aliyun.dytnsapi20200217.Client client = Sample.createClient(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));com.aliyun.dytnsapi20200217.models.ThreeElementsVerificationRequest threeElementsVerificationRequest = new com.aliyun.dytnsapi20200217.models.ThreeElementsVerificationRequest();com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();try {// 复制代码运行请自行打印 API 的返回值client.threeElementsVerificationWithOptions(threeElementsVerificationRequest, runtime);} catch (TeaException error) {// 如有需要，请打印 errorcom.aliyun.teautil.Common.assertAsString(error.message);} catch (Exception _error) {TeaException error = new TeaException(_error.getMessage(), _error);// 如有需要，请打印 errorcom.aliyun.teautil.Common.assertAsString(error.message);}        }
}

4、改造后的示例代码

这只是一个代码片段，完整的代码在工具类那里

public static void main(String[] args) throws Exception{ThreeElementIdentifyRequestParam param = new ThreeElementIdentifyRequestParam();param.setAccessKeyId("你的AccessKey ID");param.setAccessSecret("你的AccessKey Secret");param.setAuthCode("你的授权ID");param.setMask("你的加密方式");param.setInputNumber("你的手机号码");param.setCertCode("你的身份证号码");param.setName("你的名字");threeElementIdentify(param);
}

5、响应示例

{"headers": {"access-control-allow-origin": "*","date": "Mon, 23 Oct 2023 10:11:26 GMT","content-length": "137","keep-alive": "timeout=25","x-acs-request-id": "35266210-AB31-5E73-88AC-509C5F0B3E79","connection": "keep-alive","content-type": "application/json;charset=utf-8","etag": "1mfbFqXYsVtweJZ6OSyCWpg9","access-control-expose-headers": "*","x-acs-trace-id": "fa79554ca5ea3ffc8a613a0f85426a8d"},"body": {"code": "OK","data": {"basicCarrier": "中国移动","isConsistent": 1},"requestId": "35266210-AB31-5E73-88AC-509C5F0B3E79","message": "OK"},"statusCode": 200
}

三、工具类

1、请求参数dto

因为我还有调用其他接口，所以把公共的参数抽取出来了，可以和三要素核验的参数放一起。

package org.jeecg.modules.aliyun.dto;import lombok.Data;/*** 阿里云公共请求参数** @author：user* @date: 2022-09-05 10:38*/
@Data
public class AliyunConfig {//阿里云accessKeyIdprivate String accessKeyId;//阿里云accessSecretprivate String accessSecret;//阿里云识别身份证的regionId，设置请求参数的方法有横线，似乎废弃了private String regionId;
}

package org.jeecg.modules.aliyun.dto;import lombok.Data;/*** 三要素（姓名、手机号和身份证号）识别请求参数dto** @author：gan* @date: 2023-09-25 09:44*/
@Data
public class ThreeElementIdentifyRequestParam extends AliyunConfig {//阿里云三要素核验授权码。private String AuthCode;/*待检验的号码。若Mask取值为NORMAL，该字段为明文。若Mask取值为MD5，请将该字段做MD5加密。若Mask取值为SHA256，请将该字段做SHA256加密。*/private String InputNumber;/*加密方式。取值：NORMAL：不加密MD5SHA256*/private String Mask;/*待核验的身份证号。若Mask取值为NORMAL，该字段为明文。若Mask取值为MD5，请将该字段做MD5加密。若Mask取值为SHA256，请将该字段做SHA256加密。*/private String CertCode;/*待核验的姓名。若Mask取值为NORMAL，该字段为明文。若Mask取值为MD5，请将该字段做MD5加密。若Mask取值为SHA256，请将该字段做SHA256加密。*/private String Name;
}

2、枚举类

加密方式枚举类

package org.jeecg.modules.aliyun.enums;/*** 姓名、身份证、手机号码三要素校验加密方式枚举类** @author：gan* @date: 2023-10-24 09:41*/
public enum ThreeElementIdentifyMaskEnum {NORMAL("NORMAL", "不加密"),MD5("MD5", "MD5加密"),SHA256("SHA256", "SHA256加密");private String code;private String desc;ThreeElementIdentifyMaskEnum(String code, String desc) {this.code = code;this.desc = desc;}public String getCode() {return code;}public void setCode(String code) {this.code = code;}public static String getDesc(String code) {for (ThreeElementIdentifyMaskEnum value : ThreeElementIdentifyMaskEnum.values()) {if (value.code.equals(code))return value.desc;}throw new RuntimeException("未知加密方式：" + code);}public String getDesc() {return desc;}public void setDesc(String desc) {this.desc = desc;}
}

错误码枚举类，错误码在返回结果中是英文的，详情如下：

这个枚举类是为了返回中文提示

package org.jeecg.modules.aliyun.enums;/*** 姓名、身份证、手机号码三要素校验三要素错误码枚举类** @author：gan* @date: 2023-10-24 09:41*/
public enum ThreeElementIdentifyErrorCodeEnum {OperatorLimit("200", "OperatorLimit", "该号码受运营商限制"),MobileNumberIllegal("400", "MobileNumberIllegal", "手机号码格式错误"),EncyrptTypeIllegal("400", "EncyrptTypeIllegal", "手机号加密类型非法"),CarrierIllegal("400", "CarrierIllegal", "运营商类型非法"),CertCodeIllegal("400", "CertCodeIllegal", "身份证号码格式错误"),MobileNumberTypeNotMatch("400", "MobileNumberTypeNotMatch", "号码与号码类型不匹配"),AuthCodeNotExist("400", "AuthCodeNotExist", "该标签申请单不存在，请重新更换授权码"),Unknown("500", "Unknown", "未知异常"),SystemError("500", "SystemError", "系统异常");private String status;  //HTTP状态private String code;  //错误码private String desc;  //错误描述ThreeElementIdentifyErrorCodeEnum(String status, String code, String desc) {this.status = status;this.code = code;this.desc = desc;}public String getStatus() {return status;}public void setStatus(String status) {this.status = status;}public static String getDesc(String code) {for (ThreeElementIdentifyErrorCodeEnum value : ThreeElementIdentifyErrorCodeEnum.values()) {if (value.code.equals(code))return value.desc;}throw new RuntimeException("未知验证结果错误码：" + code);}public String getDesc() {return desc;}public void setDesc(String desc) {this.desc = desc;}
}

验证结果状态枚举类

package org.jeecg.modules.aliyun.enums;/*** 姓名、身份证、手机号码三要素校验返回验证结果状态枚举类** @author：gan* @date: 2023-10-24 09:41*/
public enum ThreeElementIdentifyConsistentEnum {STATUS_0("0", "不一致"),STATUS_1("1", "一致"),STATUS_2("2", "查无");private String status;private String desc;ThreeElementIdentifyConsistentEnum(String status, String desc) {this.status = status;this.desc = desc;}public String getStatus() {return status;}public void setStatus(String status) {this.status = status;}public static String getDesc(String status) {for (ThreeElementIdentifyConsistentEnum value : ThreeElementIdentifyConsistentEnum.values()) {if (value.status.equals(status))return value.desc;}throw new RuntimeException("未知验证结果状态：" + status);}public String getDesc() {return desc;}public void setDesc(String desc) {this.desc = desc;}
}

3、调用接口的工具类（关键是这个）

其中“VerifyUtil”是校验空参的工具类，放在这篇博客里面了，也可以用自己的方法校验。

package org.jeecg.modules.aliyun.utils;import com.alibaba.fastjson.JSONObject;
import com.aliyun.dytnsapi20200217.models.ThreeElementsVerificationRequest;
import com.aliyun.dytnsapi20200217.models.ThreeElementsVerificationResponse;
import com.aliyun.tea.TeaException;
import com.aliyun.tea.TeaModel;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;
import com.google.gson.Gson;
import org.jeecg.common.util.VerifyUtil;
import org.jeecg.modules.aliyun.dto.AliyunConfig;
import org.jeecg.modules.aliyun.dto.ThreeElementIdentifyRequestParam;
import org.jeecg.modules.aliyun.enums.ThreeElementIdentifyConsistentEnum;
import org.jeecg.modules.aliyun.enums.ThreeElementIdentifyErrorCodeEnum;import java.util.Arrays;
import java.util.List;/*** 阿里云工具类** @author：user* @date: 2022-09-02 16:36*/
public class AliyunUtil {public static void main(String[] args) throws Exception{ThreeElementIdentifyRequestParam param = new ThreeElementIdentifyRequestParam();param.setAccessKeyId("你的AccessKey ID");param.setAccessSecret("你的AccessKey Secret");param.setAuthCode("你的授权ID");param.setMask("你的加密方式");param.setInputNumber("你的手机号码");param.setCertCode("你的身份证号码");param.setName("你的名字");threeElementIdentify(param);}/*** 获取阿里云的公共Client（核验信息）* @param param 阿里云公共配置* @return* @throws Exception*/private static com.aliyun.dytnsapi20200217.Client getVerifyClient(AliyunConfig param) throws Exception {//这是阿里云案例代码中拿过来的Config  config = new Config ();config.setAccessKeyId(param.getAccessKeyId());config.setAccessKeySecret(param.getAccessSecret());return new com.aliyun.dytnsapi20200217.Client(config);}/*** 处理返回结果* @param response* @return*/private static JSONObject getResponseBody(TeaModel response) {//将返回的json转化成JSONObjectJSONObject responseJsonObject = JSONObject.parseObject(new Gson().toJson(response));System.out.println("responseJsonObject: " + responseJsonObject);//拿返回结果中的body，需要取哪些信息后面自己取JSONObject bodyJsonObject = responseJsonObject.getJSONObject("body");return bodyJsonObject;}/*** 三要素（姓名、手机号和身份证号）识别* @param param*/public static Boolean threeElementIdentify(ThreeElementIdentifyRequestParam param) throws Exception {List<String> noEmptyFieldList = Arrays.asList("accessKeyId", "accessSecret", "AuthCode", "Mask", "InputNumber", "CertCode", "Name");VerifyUtil.checkBeanByNonEmptyFiledList(param, noEmptyFieldList, "三要素校验信息");com.aliyun.dytnsapi20200217.Client client = getVerifyClient(param);ThreeElementsVerificationRequest request = new ThreeElementsVerificationRequest();request.setAuthCode(param.getAuthCode());request.setMask(param.getMask());request.setCertCode(param.getCertCode());request.setInputNumber(param.getInputNumber());request.setName(param.getName());ThreeElementsVerificationResponse response = null;try {response = client.threeElementsVerificationWithOptions(request, new RuntimeOptions());} catch (TeaException e) {e.printStackTrace();//这里主要是把报错信息从英文换为中文throw new RuntimeException(ThreeElementIdentifyErrorCodeEnum.getDesc(e.code) + "！");} catch (Exception e) {e.printStackTrace();throw new RuntimeException(e.getMessage());}JSONObject body = getResponseBody(response);//{"headers":{"access-control-allow-origin":"*","date":"Mon, 23 Oct 2023 10:11:26 GMT","content-length":"137","keep-alive":"timeout=25","x-acs-request-id":"35266210-AB31-5E73-88AC-509C5F0B3E79","connection":"keep-alive","content-type":"application/json;charset=utf-8","etag":"1mfbFqXYsVtweJZ6OSyCWpg9","access-control-expose-headers":"*","x-acs-trace-id":"fa79554ca5ea3ffc8a613a0f85426a8d"},"body":{"code":"OK","data":{"basicCarrier":"中国移动","isConsistent":1},"requestId":"35266210-AB31-5E73-88AC-509C5F0B3E79","message":"OK"},"statusCode":200}if (VerifyUtil.isEmpty(body) || (VerifyUtil.isNotEmpty(body) && body.size() < 1)) {throw new RuntimeException("三要素校验响应异常！");}if (!body.getString("code").equals("OK")) {throw new RuntimeException(body.getString("message"));}JSONObject data = body.getJSONObject("data");if (VerifyUtil.isEmpty(data) || (VerifyUtil.isNotEmpty(data) && data.size() < 1)) {throw new RuntimeException("三要素校验结果状态异常！");}String isConsistent = data.getString("isConsistent");if (!isConsistent.equals(ThreeElementIdentifyConsistentEnum.STATUS_1.getStatus())) {throw new RuntimeException("手机号码" + ThreeElementIdentifyConsistentEnum.getDesc(isConsistent) + "!");}return true;}
}