简介：这是一份面向Java开发者与计算机专业学生的「人脸识别签到系统」完整项目源码，适合希望将人脸识别API落地到实际业务、学习无接触身份验证流程的中级学习者。项目以Java为核心，结合科大讯飞与Face++的人脸检测、特征提取、比对及活体检测能力，覆盖图像采集、人脸比对、签到记录与异常处理等完整链路，可用于课程设计、毕业设计或企业考勤场景的二次开发。压缩包共225个文件，约15.29MB，其中65个java源文件承载核心业务逻辑，78个xml负责界面与配置，36个png与2个jpg提供图像素材，18个so与14个jar为SDK及依赖库，另有gradle构建脚本与说明文档，目录结构清晰，便于按模块研读。目前已有292人学习下载，读者可借此掌握API密钥申请、SDK集成、图像处理与数据管理的具体实现，并参考Swface-master的代码组织方式，快速搭建可运行的人脸识别签到原型。

1. 从一份只有 9 个文件的 Java 工程说起：人脸识别签到系统到底怎么落地

拿到「人脸识别签到系统_java」这个包的时候，我第一反应是有点意外——目录里没有一堆截图、没有几十兆的模型文件，只有gradlew.bat、gradlew、build.gradle、settings.gradle、.gitignore，外加三个 jar：rxjava-1.1.6.jar、Msc.jar、okhttp-3.4.1.jar。这其实是一份非常典型的 Java 客户端工程骨架，Msc.jar是科大讯飞 SDK 的核心包，okhttp负责网络请求，rxjava负责把「采集—检测—比对—签到」这条异步链路串起来。它解决的不是「从零训练一个人脸模型」的问题，而是把现成的人脸识别 API 接进一个能跑起来的签到流程里，适合做课程设计、企业内部考勤原型，或者想搞清楚人脸识别 API 调用链路的 Java 开发。下面我按「工程怎么读 → 接口怎么接 → 坑在哪 → 怎么验证」的顺序拆一遍，能直接抄的部分我都落到代码和参数上。

2. 拆开 Gradle 工程：Msc.jar、okhttp、rxjava 各自管什么

2.1 三个 jar 的分工与依赖关系

先把这三个 jar 的角色说清楚，不然后面调接口会乱。Msc.jar是科大讯飞 MSC（Mobile Speech Client）SDK 的 Java 封装，人脸相关的检测、特征提取、比对能力都通过它暴露出来，它内部会走网络请求到讯飞的服务端，所以它本身也依赖 HTTP 客户端。okhttp-3.4.1.jar是 Square 出的 HTTP 客户端，3.4.1 这个版本对应的是 OkHttp 3.x 早期，API 和现在 4.x 有差异，比如RequestBody.create的参数顺序、Response.body().string()的调用方式，抄网上新版本示例会编译不过。rxjava-1.1.6.jar是 RxJava 1.x，注意是 1.x 不是 2.x，Observable、Subscriber、Subscription这套 API 和 2.x 的Flowable、Disposable完全不同，网上搜「RxJava 人脸识别」出来的大多是 2.x 写法，直接贴进来会报cannot resolve method。

这三个 jar 放在工程根目录而不是libs/下，说明这份工程大概率是用flatDir方式引本地 jar，而不是走 Maven 仓库。build.gradle里通常会有类似这样的配置：

// build.gradle 片段：本地 jar 依赖声明 repositories { flatDir { dirs '.' // 指向工程根目录，因为 jar 就放在这里 } } dependencies { compile fileTree(dir: '.', include: ['*.jar']) // 把根目录所有 jar 都纳入编译 // 或者逐个声明： // compile name: 'Msc' // compile name: 'okhttp-3.4.1' // compile name: 'rxjava-1.1.6' }

这里flatDir的dirs '.'是关键，很多人把 jar 拷进libs/却忘了改路径，结果gradlew build报Could not find Msc.jar。compile fileTree这种写法省事，但会把根目录所有 jar 都塞进 classpath，如果以后加了别的 jar 容易冲突，我一般会逐个compile name:声明，出问题好定位。settings.gradle里一般只有一行rootProject.name = 'xxx'，不影响依赖，但工程名如果带中文或空格，某些 Gradle 版本会出路径问题，建议保持英文。

2.2 用 gradlew 把工程跑起来的最小步骤

这份工程带的是 Gradle Wrapper，也就是gradlew和gradlew.bat，好处是不用本机装 Gradle，Wrapper 会按gradle-wrapper.properties里的版本去下载。但注意，目录里没有看到gradle/wrapper/文件夹，如果gradle-wrapper.properties缺失，gradlew会直接报错找不到 distributionUrl。常见做法是补一个：

# 在工程根目录执行，Windows 用 gradlew.bat # 先看 wrapper 配置在不在 ls gradle/wrapper/gradle-wrapper.properties # 如果缺失，用本机已装的 gradle 重新生成 wrapper gradle wrapper --gradle-version 4.10.2 # 然后编译 ./gradlew build # Linux/Mac gradlew.bat build # Windows

--gradle-version选多少要看build.gradle里的compileSdkVersion或 Java 插件版本。这份工程用的是compile而不是implementation，说明 Gradle 版本偏老，4.x 比较稳。如果本机 JDK 是 17，跑 Gradle 4.x 会报Unsupported class file major version，因为 Gradle 4.x 不支持高版本 JDK 编译，解决办法是切到 JDK 8 再跑，或者把 Gradle 升到 7.x 并把compile改成implementation。这一步是很多人第一次跑就翻车的地方，不是代码问题，是工具链版本对不上。

2.3 从文件结构反推签到主流程

工程里没有src/main/java的完整展开，但从 jar 组合能反推出主流程：Msc.jar负责「人脸检测 + 特征提取 + 比对」，okhttp负责「把图片或特征传到服务端 / 拉取签到记录」，rxjava负责「把上面这些异步调用串成一条链」。典型链路是：摄像头采集一帧 → 转成 SDK 要求的格式（一般是 byte[] 或 Bitmap）→ 调Msc的检测接口拿到人脸框 → 调特征提取拿到特征串 → 调比对接口和库里预存特征比 → 比对通过后走okhttp发签到请求 →rxjava的onNext里更新 UI 或写本地记录。这条链路里任何一步失败，都要有onError兜底，否则界面会卡死。下面第 3 章就按这条链路把接口调用写细。

3. 接科大讯飞与 Face++ 接口：从 API Key 到比对返回的完整链路

3.1 API Key 申请与 SDK 初始化参数

科大讯飞和 Face++ 都需要先注册开发者账号拿 Key。讯飞这边一般是APPID+APIKey+APISecret三件套，Face++ 是API Key+API Secret。这两个平台的免费额度、QPS 限制、支持的图片格式都不一样，选型时如果只是做签到原型，讯飞的 MSC SDK 对 Java 更友好，因为它直接给了 jar；Face++ 更多是走 HTTP API，用 okhttp 自己拼请求也行，但活体检测这类能力通常要额外开通。

初始化讯飞 SDK 的常见写法：

// 讯飞 MSC SDK 初始化，参数来自控制台 // APPID 是应用标识，APIKey/APISecret 用于鉴权 String APPID = "你的APPID"; String APIKey = "你的APIKey"; String APISecret = "你的APISecret"; // 初始化 SDK，第二个参数是日志级别，调试时用 LOG_LEVEL_DEBUG MscConfig config = new MscConfig(); config.setAppId(APPID); config.setApiKey(APIKey); config.setApiSecret(APISecret); config.setLogLevel(MscConfig.LOG_LEVEL_DEBUG); // 初始化，失败会抛异常，必须 try-catch try { MscEngine engine = MscEngine.getInstance(); engine.init(config); } catch (MscException e) { // 常见原因：APPID 和 Key 不匹配、网络不通、SDK 版本过期 e.printStackTrace(); }

setLogLevel调成 DEBUG 后，SDK 会把每次请求的 URL、参数、返回码打到日志里，排查10105（无效的 APPID）或10106（无效的 APIKey）这类错误码时非常有用。注意MscEngine.getInstance()是单例，整个应用初始化一次就行，重复 init 可能报already initialized。Face++ 那边如果用 okhttp 直接调，鉴权参数一般放在 URL query 或 header 里，api_key和api_secret不要硬编码在代码里，放local.properties或环境变量，避免提交到仓库。

3.2 人脸检测与特征提取的调用与返回解析

检测接口的作用是告诉你在图片哪个位置有人脸，返回一般是人脸框坐标 + 置信度。特征提取是在检测基础上拿到一个特征串（feature），这个串才是比对用的。以讯飞风格为例：

// 人脸检测：传入图片字节数组，返回人脸列表 // 参数 imageData 是图片的 byte[]，format 指定 jpg/png byte[] imageData = readImageBytes("face.jpg"); FaceDetectResult detectResult = engine.detectFace(imageData, "jpg"); if (detectResult.getFaceCount() == 0) { // 没检测到人脸，常见于光线太暗、人脸太小、侧脸角度过大 Log.e("Face", "no face detected"); return; } // 取第一张人脸的框，left/top/right/bottom 是像素坐标 FaceRect rect = detectResult.getFaces().get(0).getRect(); Log.d("Face", "rect=" + rect.left + "," + rect.top + "," + rect.right + "," + rect.bottom); // 特征提取：基于检测结果拿特征串 String feature = engine.extractFeature(imageData, rect); // feature 是一段 Base64 或十六进制字符串，长度通常几百到上千字符

detectFace的第二个参数"jpg"要和实际图片格式一致，传 png 图片却写 jpg，SDK 可能解析失败返回空。getFaceCount()为 0 时不要直接抛异常，签到场景里用户没对准摄像头是常态，应该提示「请正对摄像头」而不是崩溃。特征串feature拿到后要存库，存的时候注意字段长度，MySQL 里用TEXT而不是VARCHAR(255)，因为特征串可能超过 255。比对时把现场特征和库里特征一起传给比对接口，返回一个相似度分数，通常 0 到 1 之间，阈值设 0.8 以上比较稳，设太低会误识，设太高用户签不上。

3.3 用 RxJava 1.x 串起异步链路与签到落库

RxJava 1.x 的写法核心是Observable.create+subscribeOn+observeOn。人脸检测和网络请求都是耗时操作，必须放子线程，结果回主线程更新 UI：

// RxJava 1.x：把检测、比对、签到串成一条链 Observable.create(new Observable.OnSubscribe<SignResult>() { @Override public void call(Subscriber<? super SignResult> subscriber) { try { // 1. 检测 FaceDetectResult detect = engine.detectFace(imageData, "jpg"); if (detect.getFaceCount() == 0) { subscriber.onError(new Throwable("no face")); return; } // 2. 提取特征 String feature = engine.extractFeature(imageData, detect.getFaces().get(0).getRect()); // 3. 比对：compareFeature 返回相似度 float score = engine.compareFeature(feature, storedFeature); if (score < 0.8f) { subscriber.onError(new Throwable("score too low: " + score)); return; } // 4. 签到落库，走 okhttp SignResult result = signApi.postSign(userId, score); subscriber.onNext(result); subscriber.onCompleted(); } catch (Exception e) { subscriber.onError(e); } } }) .subscribeOn(Schedulers.io()) // 耗时操作放 IO 线程 .observeOn(AndroidSchedulers.mainThread()) // 结果回主线程 .subscribe(new Subscriber<SignResult>() { @Override public void onCompleted() { } @Override public void onError(Throwable e) { // 统一在这里处理：没人脸、分数低、网络失败 toast("签到失败：" + e.getMessage()); } @Override public void onNext(SignResult r) { toast("签到成功，相似度 " + r.getScore()); } });

subscribeOn(Schedulers.io())决定上游在哪个线程跑，observeOn决定下游在哪个线程收，这两个顺序不能反。RxJava 1.x 里Subscriber没有Disposable，取消订阅用Subscription，如果 Activity 销毁时没取消，回调里更新 UI 会崩。compareFeature的阈值 0.8 不是固定的，光线好的室内可以到 0.85，光线差的场景降到 0.75，但低于 0.7 基本就不能用了，误识率会明显上升。签到落库用 okhttp 时，RequestBody用FormBody还是MultipartBody取决于后端接口，传特征串用FormBody就够，传图片才需要MultipartBody。

4. 避坑与排查：人脸识别签到系统最容易翻车的 5 个点

4.1 现象：gradlew 报 Could not find Msc.jar

原因：jar 放在根目录但build.gradle里flatDir的dirs指向了libs，或者fileTree的dir写错。解决：确认dirs '.'和 jar 实际位置一致，或者把 jar 移到libs/并改dirs 'libs'。另外 Windows 下路径分隔符用/而不是\，Gradle 对反斜杠支持不好。

4.2 现象：调用检测接口返回 10105 或 10106

原因：APPID、APIKey、APISecret 三者不匹配，或者 Key 复制时带了空格。解决：去控制台重新复制，注意不要带首尾空格；确认应用状态是「已开通」而不是「审核中」；如果换了应用，Key 要同步换。日志级别开到 DEBUG 能看到具体是哪个参数被拒。

4.3 现象：特征比对分数总是很低，本人也签不上

原因：注册时存的特征和签到时的特征提取条件不一致，比如注册用高清图、签到用低分辨率摄像头帧，或者两次光线差异大。解决：注册和签到走同一套采集流程，图片尺寸、格式、压缩质量保持一致；阈值不要一刀切，可以按场景调；如果 SDK 支持活体检测，开启后能过滤掉照片攻击，但也会增加失败率，要权衡。

4.4 现象：RxJava 回调里更新 UI 崩溃

原因：Activity 已销毁但订阅没取消，onNext里还在调toast或setText。解决：在onDestroy里保存Subscription并调unsubscribe()；或者用CompositeSubscription统一管理，销毁时clear()。RxJava 1.x 没有自动生命周期绑定，这一点比 2.x 的AutoDispose麻烦。

4.5 现象：okhttp 请求签到接口超时或返回 415

原因：Content-Type没设对，或者FormBody里参数名和后端不一致。解决：用FormBody.Builder时确认add的 key 和后端@RequestParam一致；如果后端要 JSON，改用RequestBody.create(MediaType.parse("application/json"), jsonStr)，注意 OkHttp 3.4.1 的create第一个参数是 MediaType，顺序和新版本不同。

5. 进阶验证：用一组对照样本测出你系统的真实阈值

调通接口只是第一步，真正决定这套签到系统能不能用的，是阈值定得准不准。我一般会做一组对照实验：找 5 个人，每人采 3 张注册图（正脸、稍侧、不同光线），再采 10 张签到图（包含本人和他人），跑一遍比对，把分数记下来。下面这个表是我常用的记录格式：

从这组数能看出，本人正脸和他人误识之间有明显的分数带间隔，阈值设在 0.7 到 0.8 之间比较安全。如果本人侧脸的最低分掉到 0.65，而他人误识最高分到了 0.62，那这个间隔就太窄了，说明特征区分度不够，要么换更好的采集条件，要么换识别方案。验证时还要注意，同一张图重复调接口，分数应该基本一致，如果波动超过 0.05，可能是服务端做了随机化或者网络传输丢了数据，这种就要查 SDK 版本和网络链路。

另一个容易被忽略的点是签到记录的幂等性。同一个人短时间内重复签到，后端应该按时间窗口去重，而不是每次都插一条。我一般会在签到接口里加一个last_sign_time判断，比如 5 分钟内重复请求直接返回「已签到」，避免刷接口。这个逻辑放在 Java 服务端比放在客户端可靠，客户端的时间可以被改。

从那以后我每次接人脸识别类的工程，都强制先跑一遍「注册—签到—误识」三组对照，把分数分布画出来再定阈值，而不是拍脑袋写 0.8。这套流程看起来多花半小时，但能省掉后面反复调参的血泪经验。希望帮到你。

本文还有配套的精品资源，点击获取