feat(miniapp): 新增微信小程序人脸核身服务后台接口 by Copilot · Pull Request #3902 · binarywang/WxJava

Copilot · 2026-03-05T02:26:09Z

按照官方文档实现微信小程序人脸核身服务的两个后台接口，接口路径以 /cityservice/face/identify/ 为前缀。

新增接口

getVerifyId — 根据用户实名信息（姓名+身份证）获取核身会话标识 verifyId，供前端调用 wx.requestFacialVerify 使用
queryVerifyInfo — 根据 verifyId 查询人脸核身真实结果；核身通过条件：errcode=0 且 verify_ret=10000

新增文件

类型	文件
接口	`WxMaFaceService`
实现	`WxMaFaceServiceImpl`
Bean	`WxMaFaceGetVerifyIdRequest/Response`、`WxMaFaceQueryVerifyInfoRequest/Response`
常量	`WxMaApiUrlConstants.Face`

变更文件

WxMaService — 新增 getFaceService() 声明
BaseWxMaServiceImpl — 注册服务实例并实现 getter

cert_hash 计算

queryVerifyInfo 需要传入 cert_hash，WxMaFaceQueryVerifyInfoRequest 内置了静态工具方法：

// 对 cert_info 中各字段 Base64 编码后拼接，再 SHA-256
String certHash = WxMaFaceQueryVerifyInfoRequest.calcCertHash("IDENTITY_CARD", "张三", "310101199801011234");
// → "3c241f7ff324977aeb91f173bb2a7b06569e6fd784d5573db34a636d8671108b"

计算结果与官方文档示例值完全一致。

使用示例

WxMaFaceGetVerifyIdRequest req = WxMaFaceGetVerifyIdRequest.builder()
    .outSeqNo("BIZ20240101001")
    .certInfo(WxMaFaceGetVerifyIdRequest.CertInfo.builder()
        .certType("IDENTITY_CARD")
        .certName("张三")
        .certNo("310101199801011234")
        .build())
    .openid("oXXXXXXXXXXX")
    .build();

WxMaFaceGetVerifyIdResponse resp = wxMaService.getFaceService().getVerifyId(req);
String verifyId = resp.getVerifyId();

// 查询核身结果时计算 cert_hash
String certHash = WxMaFaceQueryVerifyInfoRequest.calcCertHash("IDENTITY_CARD", "张三", "310101199801011234");

Original prompt

This section details on the original issue you should resolve

<issue_title>新增接口实现：微信小程序人脸识别服务</issue_title>
<issue_description># 简要描述

实现微信小程序人脸识别服务后台相关接口，详情请参考微信官方需求文档。建议将官方文档内容直接贴入，以最大程度保证需求明确。

官方文档地址

https://developers.weixin.qq.com/miniprogram/dev/server/API/face/

以下为官方文档需求摘要（请补充完整或参考原文档）：

微信小程序人脸识别服务 API 说明：

支持创建在线人脸识别任务

查询识别任务状态

获取识别结果等

接口列表请参见文档原文。

注意不要自己瞎编接口（之前很多次PR都存在捏造根源文档不符的接口地址），完全按照文档里的要求来编写代码。

</issue_description>

Comments on the Issue (you are @copilot in this section)

Custom agent used: 全部用中文
需要用中文，包括PR标题和分析总结过程

Fixes 新增接口实现：微信小程序人脸识别服务 #3901

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

- 添加 WxMaFaceService 接口，包含 getVerifyId 和 queryVerifyInfo 方法 - 添加 WxMaFaceServiceImpl 实现，包含 cert_hash 计算工具方法 - 添加请求/响应 bean：WxMaFaceGetVerifyIdRequest/Response、WxMaFaceQueryVerifyInfoRequest/Response - 在 WxMaApiUrlConstants 中新增 Face 接口 URL 常量 - 在 WxMaService 和 BaseWxMaServiceImpl 中注册人脸核身服务 - 新增测试类 WxMaFaceServiceImplTest（含 cert_hash 单元测试） Co-authored-by: binarywang <1343140+binarywang@users.noreply.github.com>

augmentcode · 2026-03-05T04:10:01Z

🤖 Augment PR Summary

总结：本 PR 按照微信官方文档新增「小程序人脸核身」后台能力，补齐获取核身会话与查询核身结果两类接口。

主要变更：

新增 WxMaFaceService 接口，提供 getVerifyId 与 queryVerifyInfo 两个方法，覆盖创建核身会话与查询核身结果流程。
新增实现类 WxMaFaceServiceImpl，通过 WxMaService.post 调用对应 API，并提供 calcCertHash 工具方法用于生成 cert_hash。
新增人脸核身相关请求/响应 Bean：WxMaFaceGetVerifyIdRequest/Response、WxMaFaceQueryVerifyInfoRequest/Response。
在 WxMaApiUrlConstants 中新增 Face 常量区，补充 /cityservice/face/identify/ 前缀下的两条接口 URL。
扩展 WxMaService：新增 getFaceService()，并在 BaseWxMaServiceImpl 中完成服务实例注册与 getter 实现。
新增 WxMaFaceServiceImplTest，包含接口调用示例以及对官方文档给出的 cert_hash 样例校验。

技术说明：接口调用由底层执行器统一追加 access_token；queryVerifyInfo 的通过条件（errcode=0 且 verify_ret=10000）由业务侧基于响应字段自行判断。

_{🤖 Was this summary useful? React with 👍 or 👎}

augmentcode

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

augmentcode · 2026-03-05T04:10:02Z

weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/impl/WxMaFaceServiceImpl.java

+      byte[] hashBytes = digest.digest(raw.getBytes(StandardCharsets.UTF_8));
+      StringBuilder hex = new StringBuilder();
+      for (byte b : hashBytes) {
+        hex.append(String.format("%02x", b));


这里用 String.format("%02x", b) 直接格式化 byte 时，遇到负值字节可能输出 ffffffff...（不会截断），导致 cert_hash 长度/内容异常；建议确认按无符号字节生成 2 位 hex。

Severity: high

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

augmentcode · 2026-03-05T04:10:02Z

...in-java-miniapp/src/test/java/cn/binarywang/wx/miniapp/api/impl/WxMaFaceServiceImplTest.java

+        .certName("张三")
+        .certNo("310101199801011234")
+        .build())
+      .openid("test_openid_001")


testGetVerifyId/testQueryVerifyInfo 里使用了明显的占位 openid/verifyId（如 test_openid_001、test_verify_id_001），在真实调用微信接口时大概率直接报错抛 WxErrorException，会让用例不可用/不稳定。

Severity: medium

Other Locations

weixin-java-miniapp/src/test/java/cn/binarywang/wx/miniapp/api/impl/WxMaFaceServiceImplTest.java:53

weixin-java-miniapp/src/test/java/cn/binarywang/wx/miniapp/api/impl/WxMaFaceServiceImplTest.java:56

_{🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.}

Copilot

Pull request overview

该 PR 在 weixin-java-miniapp 模块中新增“小程序人脸核身服务”后台接口封装，补齐官方文档中的 getVerifyId 与 queryVerifyInfo 两个能力，并将其纳入 WxMaService 的子服务体系，方便 SDK 使用方以统一方式调用。

Changes:

新增人脸核身服务接口 WxMaFaceService 及实现 WxMaFaceServiceImpl，封装 getVerifyId/queryVerifyInfo 请求。
新增对应的请求/响应 Bean，并补充 WxMaApiUrlConstants.Face 接口地址常量。
在 WxMaService/BaseWxMaServiceImpl 中注册并暴露 getFaceService()；新增相关测试类。

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
weixin-java-miniapp/src/test/java/cn/binarywang/wx/miniapp/api/impl/WxMaFaceServiceImplTest.java	新增人脸核身服务测试用例（目前包含直连真实接口的用例）。
weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/constant/WxMaApiUrlConstants.java	增加 Face 接口 URL 常量定义。
weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/face/WxMaFaceQueryVerifyInfoResponse.java	新增 queryVerifyInfo 响应模型与反序列化方法。
weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/face/WxMaFaceQueryVerifyInfoRequest.java	新增 queryVerifyInfo 请求模型与序列化方法。
weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/face/WxMaFaceGetVerifyIdResponse.java	新增 getVerifyId 响应模型与反序列化方法。
weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/face/WxMaFaceGetVerifyIdRequest.java	新增 getVerifyId 请求模型（含 cert_info）与序列化方法。
weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/impl/WxMaFaceServiceImpl.java	新增服务实现与 `cert_hash` 计算工具方法。
weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/impl/BaseWxMaServiceImpl.java	注册 `WxMaFaceService` 实例并提供 getter。
weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaService.java	新增 `getFaceService()` 对外声明。
weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaFaceService.java	新增人脸核身服务接口定义与方法注释。

weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/impl/WxMaFaceServiceImpl.java

...in-java-miniapp/src/test/java/cn/binarywang/wx/miniapp/api/impl/WxMaFaceServiceImplTest.java

weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaFaceService.java

...ava-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/face/WxMaFaceGetVerifyIdRequest.java

...va-miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/face/WxMaFaceGetVerifyIdResponse.java

...in-java-miniapp/src/test/java/cn/binarywang/wx/miniapp/api/impl/WxMaFaceServiceImplTest.java

Copilot · 2026-03-05T04:11:29Z

...in-java-miniapp/src/test/java/cn/binarywang/wx/miniapp/api/impl/WxMaFaceServiceImplTest.java

+import org.testng.annotations.Test;
+
+import static org.testng.Assert.assertEquals;
+import static org.testng.AssertJUnit.assertNotNull;


这里同时静态导入了 org.testng.Assert.assertEquals 和 org.testng.AssertJUnit.assertNotNull，断言库混用会降低可读性并可能引入行为差异。建议统一使用 TestNG 的 org.testng.Assert（例如静态导入 assertNotNull），与本模块其他测试类保持一致。

Suggested change

import static org.testng.AssertJUnit.assertNotNull;

import static org.testng.Assert.assertNotNull;

weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/impl/WxMaFaceServiceImpl.java

...miniapp/src/main/java/cn/binarywang/wx/miniapp/bean/face/WxMaFaceQueryVerifyInfoRequest.java

...iniapp/src/main/java/cn/binarywang/wx/miniapp/bean/face/WxMaFaceQueryVerifyInfoResponse.java

…/impl/WxMaFaceServiceImplTest.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…/WxMaFaceService.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…n/face/WxMaFaceGetVerifyIdResponse.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

binarywang · 2026-03-05T04:19:39Z

@copilot apply changes based on the comments in this thread

- 将 calcCertHash 工具方法从 WxMaFaceServiceImpl 移到 WxMaFaceQueryVerifyInfoRequest 中 - 修复所有文件中 Github → GitHub 拼写错误 - 重构测试类：移除依赖真实接口的测试，只保留本地 calcCertHash 计算测试 - 修复测试类断言库混用问题，统一使用 TestNG 的 org.testng.Assert Co-authored-by: binarywang <1343140+binarywang@users.noreply.github.com>

Copilot · 2026-03-05T04:23:06Z

@copilot apply changes based on the comments in this thread

已根据审查意见完成全部修改（commit 6297422）：

calcCertHash 方法迁移 — 从 WxMaFaceServiceImpl 移到 WxMaFaceQueryVerifyInfoRequest 中作为 public static 方法，使用方直接调用 WxMaFaceQueryVerifyInfoRequest.calcCertHash(...) 即可，无需依赖实现类
拼写修复 — 全部 Github → GitHub
测试类重构 — 移除依赖真实微信接口的 testGetVerifyId/testQueryVerifyInfo，只保留本地计算的 testCalcCertHash；统一使用 org.testng.Assert，消除断言库混用

Initial plan

3d9ef97

Copilot AI assigned Copilot and binarywang Mar 5, 2026

Copilot started work on behalf of binarywang March 5, 2026 02:26 View session

Copilot AI changed the title ~~[WIP] Add WeChat mini-program face recognition service API~~ feat(miniapp): 新增微信小程序人脸核身服务后台接口 Mar 5, 2026

Copilot finished work on behalf of binarywang March 5, 2026 02:36

binarywang marked this pull request as ready for review March 5, 2026 04:06

Copilot AI review requested due to automatic review settings March 5, 2026 04:06

Copilot started reviewing on behalf of binarywang March 5, 2026 04:07 View session

augmentcode bot reviewed Mar 5, 2026

View reviewed changes

Copilot AI reviewed Mar 5, 2026

View reviewed changes

binarywang and others added 3 commits March 5, 2026 12:18

Update weixin-java-miniapp/src/test/java/cn/binarywang/wx/miniapp/api…

5ab453c

…/impl/WxMaFaceServiceImplTest.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api…

0523de4

…/WxMaFaceService.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/bea…

4b8c025

…n/face/WxMaFaceGetVerifyIdResponse.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot started work on behalf of binarywang March 5, 2026 04:19 View session

Copilot finished work on behalf of binarywang March 5, 2026 04:23

binarywang merged commit 2622437 into develop Mar 6, 2026
1 check passed

binarywang added this to the 4.8.2 milestone Mar 7, 2026

	import static org.testng.AssertJUnit.assertNotNull;
	import static org.testng.Assert.assertNotNull;

Uh oh!

Conversation

Copilot AI commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

新增接口

新增文件

变更文件

cert_hash 计算

使用示例

官方文档地址

Comments on the Issue (you are @copilot in this section)

Uh oh!

augmentcode bot commented Mar 5, 2026

Uh oh!

augmentcode bot left a comment

Choose a reason for hiding this comment

Uh oh!

augmentcode bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

augmentcode bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

binarywang commented Mar 5, 2026

Uh oh!

Copilot AI commented Mar 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Mar 5, 2026 •

edited

Loading