Kotlin Biometric 生物识别：完整指南与代码示例

生物识别认证已成为现代移动应用不可或缺的功能。它允许用户通过指纹、面部扫描或虹膜识别来验证身份，比输入密码更便捷、更安全。Kotlin 的 Biometric 库（属于 AndroidX 组件）为 Android 设备上的所有生物识别传感器提供了统一的 API 接口。

为什么需要这个库？首先，它屏蔽了不同厂商生物识别传感器实现的差异。其次，它能自动处理生物识别不可用（如设备无扫描器）或锁定等场景。第三，该库与 Android Keystore 深度集成，允许创建加密保护的密钥，这些密钥仅在用户成功认证后才能使用。

本文将详细讲解 Kotlin Biometric 库的所有方面：从安装和最小示例到高级技巧和常见错误。您将学会如何在应用中添加生物识别认证，使其既安全又用户友好。

安装步骤

要在 Kotlin Android 项目中使用 Biometric 库，请在 build.gradle（模块级别）文件中添加以下依赖：

dependencies {
    implementation("androidx.biometric:biometric:1.2.0-alpha05")
}

同时，确保在 AndroidManifest.xml 文件中声明使用生物识别传感器的权限：

如果您的应用面向 Android 12（API 31）及以上版本，建议添加更精确的生物识别类型权限：

快速上手：最小工作示例

让我们创建一个简单的 Activity，点击按钮时启动生物识别认证，并通过 Toast 显示结果。

import android.os.Bundle
import android.widget.Button
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import androidx.biometric.BiometricManager
import androidx.biometric.BiometricPrompt
import androidx.core.content.ContextCompat
import java.util.concurrent.Executors

class MainActivity : AppCompatActivity() {

    private lateinit var biometricPrompt: BiometricPrompt
    private lateinit var promptInfo: BiometricPrompt.PromptInfo

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val authButton: Button = findViewById(R.id.auth_button)

        // 检查设备是否支持生物识别
        val biometricManager = BiometricManager.from(this)
        when (biometricManager.canAuthenticate(BiometricManager.Authenticators.BIOMETRIC_STRONG)) {
            BiometricManager.BIOMETRIC_SUCCESS -> {
                // 生物识别可用，配置对话框
                setupBiometricPrompt()
            }
            BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE -> {
                Toast.makeText(this, "设备没有生物识别传感器", Toast.LENGTH_LONG).show()
            }
            BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE -> {
                Toast.makeText(this, "生物识别传感器暂时不可用", Toast.LENGTH_LONG).show()
            }
            BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED -> {
                Toast.makeText(this, "未添加生物识别数据