auth0-android-major-migration

Auth0.Android v4 迁移

将现有的 Auth0.Android（com.auth0.android:auth0）v3 集成迁移到 v4。每项代码更改都必须先搜索，确认项目确实调用了受影响的 API——如果项目从未使用 SecureCredentialsManager，就不会修改任何 SecureCredentialsManager 代码。更改遵循项目现有的架构（Kotlin 或 Java、回调或协程）和 Android 约定。

目标版本由参数指定

此技能接受可选的目标版本参数：

• /auth0-android-major-migration 4.0.0 — 迁移到确切的标签 4.0.0（使用前会验证）。
• /auth0-android-major-migration（不带参数）— 自动解析下一个主版本（v4.x）中的最新发行版，包括预发行版。

如果存在 $ARGUMENTS，它就是请求的目标标签。步骤 2 会验证该标签，并解析迁移后续步骤使用的最终 <TARGET_TAG>。

不适用场景

• 新的 Auth0 集成（没有现有的 Auth0.Android SDK）：使用 auth0-android
• 次要版本／补丁版本更新（例如，3.18 → 3.19）：在 Gradle 中更新 com.auth0.android:auth0 版本——无需迁移
• iOS / macOS 应用：使用 auth0-swift-major-migration
• React Native / Expo：使用 auth0-react-native 或 auth0-expo
• Flutter：使用原生 Flutter Auth0 SDK

先决条件

• 已有的 Auth0.Android v3 集成（com.auth0.android:auth0:3.x）
• 已安装 Android SDK / Gradle 工具链；项目在当前版本上可以成功构建
• 项目已纳入 git 版本控制，且工作区干净

---

迁移工作流

Agent 指令： 按顺序执行每个步骤。目标是在尽可能小且正确的变更集中实现构建通过。每个代码更改步骤都必须经过步骤 5 的文件读取审计——如果未在项目源文件中找到该 API，则跳过该区域的整个步骤。绝不要添加项目当前未调用的代码。v4 还提高了平台要求（步骤 3），可能会导致迁移无法继续，直至满足这些要求——请先处理这些要求，再修改任何 Auth0 API 调用位置。

---

步骤 1 — 迁移前检查与安全备份

# 1a. Verify clean working tree — stop if there are uncommitted changes
git status --porcelain

如果输出不为空，请询问用户：

“您有尚未提交的更改。要在继续前将它们暂存起来（git stash），还是希望先提交？”

# 1b. Create a safety branch the user can reset to at any time
git checkout -b auth0-v4-migration-backup
git checkout -

# 1c. Confirm the project builds on the current version before touching anything
./gradlew assembleDebug 2>&1 | tail -15

如果构建失败，请停止。请用户先修复现有问题——不要迁移无法构建的项目。

---

步骤 2 — 检测当前版本并确定目标版本

检测当前的 Auth0.Android 版本（检查所有适用位置）：

# Inline dependency in a module build file (Groovy or Kotlin DSL)
grep -rEn "com\.auth0\.android:auth0:[0-9]" --include=build.gradle --include=build.gradle.kts .

# Gradle version catalog
grep -rEn "auth0" --include=libs.versions.toml .

# Resolved lockfile (most reliable if present)
grep -rEn "com\.auth0\.android:auth0:[0-9]" --include=gradle.lockfile .

确定目标版本。 有两种方式：

方式 A — 用户传入了目标版本参数（$ARGUMENTS）：

使用前，根据已发布的版本验证该版本。必须通过全部三项检查：

# List all published Auth0.Android release tags
gh api repos/auth0/Auth0.Android/releases --paginate \
  --jq '.[] | select(.draft==false) | .tag_name'

1. 确实存在 — 请求的标签出现在上方已发布版本列表中。
2. 下一个主版本 — 标签属于 v4 主版本系列（tag_name 以 4 开头）。3.x 或更低版本不是下一个主版本；应拒绝。
3. 不是降级 — 该标签比项目中检测到的版本更新。

任意一项检查失败时，都要停止并询问用户。 不要悄悄回退。例如：

• "4.9.9 不是已发布的 Auth0.Android 版本。已发布的 v4 版本有：4.0.0-beta.1，……。请传入有效的 v4 标签，或省略参数以自动确定最新的 v4 版本。"
• "3.19.0 是 v3 版本，不是下一个主版本。此技能会迁移到 v4。请传入 v4 标签（例如 4.0.0），或省略参数。"
• "项目中已有的版本是 4.0.0-beta.1，4.0.0-beta.0 比它旧，这是降级。请传入更新的 v4 标签，或省略参数。"

方式 B — 未传入参数：自动确定最新的 v4 版本（包括预发布版本）：

# Newest v4.x release tag (stable or pre-release), most recent first
gh api repos/auth0/Auth0.Android/releases --paginate \
  --jq '[.[] | select(.draft==false) | select(.tag_name|startswith("4"))] | .[0].tag_name'

将结果记录为 <TARGET_TAG>，并在后续每一步中使用该值。

如果 <TARGET_TAG> 是预发布版本（包含 -beta、-rc 等），请在继续前告知用户： "v4 尚未正式发布——最新的 v4 版本是 <TARGET_TAG>（预发布版本）。我会迁移到该版本。你可以通过传入参数来固定到其他标签。"

如果尚无 v4 版本（解析器返回空值），请停止并告知用户，目前没有可供迁移的已发布 v4 版本。

---

步骤 3 — 前置条件检查（要求变更）

v4 提高了构建工具链和平台的最低要求。迁移任何 API 之前，请检查每项要求。如果未满足某项要求，请提示用户并应用构建文件变更（或等用户确认后再继续）——不满足这些要求的项目，无论 API 如何变更，都无法使用 v4 构建。

如果从第 4 步获取的 SDK 自身 build.gradle / gradle-wrapper.properties 中，<TARGET_TAG> 的确切要求与下方数值不同，请以 SDK 中的要求为准（下方数值反映的是 v4 的基准要求）。

要求	v3	v4	检查 / 修改位置
minSdk	21	26（Android 8.0）	android { defaultConfig { minSdk } }
Java	8+	17	compileOptions { sourceCompatibility/targetCompatibility }、kotlinOptions { jvmTarget }
Gradle	—	8.11.1+	gradle/wrapper/gradle-wrapper.properties（distributionUrl）
AGP	—	8.10.1+	根目录 build.gradle 中的 com.android.tools.build:gradle classpath / plugins 块
Kotlin	—	2.0.21	ext.kotlin_version / 版本目录（仅当项目使用 Kotlin 时）

# Inspect current values
grep -rEn "minSdk(Version)?\s*[ =]" --include=build.gradle --include=build.gradle.kts .
grep -rEn "sourceCompatibility|targetCompatibility|jvmTarget" --include=build.gradle --include=build.gradle.kts .
grep -En "distributionUrl" gradle/wrapper/gradle-wrapper.properties
grep -rEn "com\.android\.tools\.build:gradle|kotlin_version|kotlin(\"|-)" --include=build.gradle --include=build.gradle.kts --include=libs.versions.toml .

minSdk 低于 26 时必须阻止迁移。 如果项目面向 API 25 或更低版本，请告知用户，这会提高最低支持的 Android 版本（将不再支持运行 Android 7.1 及更低版本的设备），并请他们确认是否将 minSdk 提升到 26，或者继续使用 v3。

应用所需的版本升级（以下为示例形式——请匹配项目使用的 DSL）：

android {
    defaultConfig { minSdk 26 }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions { jvmTarget = '17' }
}

Kotlin DSL、版本目录以及 Gradle/AGP 包装器的特殊情况，请参阅 references/process.md。

---

第 4 步 — 获取并阅读 v4 SDK 源码

获取 <TARGET_TAG> 对应的实际 Kotlin 源码。这里的签名是第 7 步中所有变更的权威参考。不要凭记忆或仅依据指南进行迁移——请从获取的源码中确认每个签名。

TAG=<TARGET_TAG>   # the version resolved in Step 2, e.g. 4.0.0-beta.1
BASE="https://raw.githubusercontent.com/auth0/Auth0.Android/${TAG}/auth0/src/main/java/com/auth0/android"

# List all public Kotlin files in the SDK (confirm paths for this tag)
gh api "repos/auth0/Auth0.Android/git/trees/${TAG}?recursive=1" \
  --jq '.tree[].path | select(startswith("auth0/src/main/") and endswith(".kt"))'

# Fetch the files that back the breaking changes
for FILE in \
  provider/WebAuthProvider.kt \
  authentication/AuthenticationAPIClient.kt \
  authentication/mfa/MfaApiClient.kt \
  authentication/storage/SecureCredentialsManager.kt \
  authentication/storage/CredentialsManager.kt \
  authentication/storage/BaseCredentialsManager.kt \
  authentication/storage/Storage.kt \
  dpop/DPoPException.kt \
  result/SSOCredentials.kt \
  request/DefaultClient.kt ; do
    CONTENT=$(curl -sf "${BASE}/${FILE}")
    [ -n "$CONTENT" ] && echo "=== ${FILE} ===" && echo "$CONTENT"
done

如果某个发布标签尚无源码（例如，在 v4 开发阶段，首个包含完整代码树的标签发布之前），请改用 v4_development 分支确认签名：将上方 URL 中的 ${TAG} 替换为 v4_development。如果所选标签已有源码，始终优先使用该标签。

阅读获取的源码，并针对每个文件记录：

• 发生变化的公共方法签名（参数、返回类型、@Throws）
• 已移除的构造函数
• 已移除或重命名的类型／类
• 已更改的默认参数值（例如 minTtl）

这是事实依据。第 7 步中的每项变更都必须与这些文件中的实际签名相符。

---

第 5 步 — 审核项目使用的 Auth0 API

查找所有导入 Auth0 SDK 的源文件——这些文件就是本次迁移的范围：

grep -rlE "import com\.auth0\.android" --include="*.kt" --include="*.java" .

阅读列表中的每个文件。 不要只搜索个别 API 模式后就停止——请通读完整源码，准确了解项目如何使用 Auth0、WebAuthProvider、AuthenticationAPIClient、SecureCredentialsManager／CredentialsManager 和任何 Auth0 类型，包括多行构建器链以及任何自定义的 Storage 实现。

针对每个文件，确认：

要查找的内容	章节
使用 PasskeyAuthProvider	§7.1 — 已移除该类
UsersAPIClient、ManagementException、ManagementCallback	§7.2 — 已移除 Management API
在 AuthenticationAPIClient 上调用 loginWithOTP(、loginWithOOB(、loginWithRecoveryCode(、multifactorChallenge(	§7.3 — 已移除弃用的 MFA 方法
在对象上、调用 .login( 之前调用 WebAuthProvider.useDPoP(	§7.4 — useDPoP 已移至登录构建器
DPoPException.UNSUPPORTED_ERROR	§7.5 — 已移除该常量
在 SSOCredentials 值上访问 .expiresIn	§7.6 — 已重命名为 expiresAt（现在是 Date）
SecureCredentialsManager( 的第一个参数是 Auth0 实例	§7.7 — 已移除基于 Auth0 的构造函数
调用 getCredentials(／awaitCredentials( 时未显式指定 minTtl，或调用 hasValidCredentials()	§9.1 — 默认 minTtl 从 0 变为 60s（行为变化）
clearCredentials(	§9.3 — 现在会清除所有存储内容
实现 Storage 接口的类	§9.4 — 新增 removeAll()（提供默认实现）

制作一份清单：“本项目使用：[列表]”以及“本项目不使用：[列表]”。只处理“使用”列表中涉及的 §7.x／§9.x 章节，其余章节全部跳过。

---

第 6 步 — 更新 SDK 依赖

应用相应的声明样式。使用第 2 步中的 <TARGET_TAG>。

内联 — Groovy DSL（build.gradle）：

implementation 'com.auth0.android:auth0:<TARGET_TAG>'

内联 — Kotlin DSL（build.gradle.kts）：

implementation("com.auth0.android:auth0:<TARGET_TAG>")

版本目录（gradle/libs.versions.toml）：

[versions]
auth0 = "<TARGET_TAG>"

预发布标签（例如 4.0.0-beta.1）必须精确固定——不要使用 4.+ 或 [4.0,5.0) 这类动态范围，因为 Gradle 可能会解析到其他构件。对于稳定版 v4，仍建议使用精确版本，以确保可复现性。

暂时不要构建——先应用所有已知代码变更（第 7 步），再进行构建（第 8 步），以发现剩余问题。

---

第 7 步 — 应用破坏性变更

Agent 指令： 只处理第 5 步审核中匹配的 §7.x 章节。跳过项目未使用其 API 的所有章节——不要改动这些文件。严格按照示例应用每项变更，并根据第 4 步获取的源码进行确认。不要重命名变量、重新格式化代码，也不要对无需迁移的代码进行现代化改造。遵循项目现有风格：回调 → 回调，协程 await → 协程 await，Kotlin → Kotlin，Java → Java。

7.1 — 已移除 PasskeyAuthProvider

**适用条件：**步骤 5 在项目源文件中找到了 PasskeyAuthProvider。

com.auth0.android.provider.PasskeyAuthProvider 类已移除。Passkey 操作现在位于 AuthenticationAPIClient 上：passkeyChallenge()、signupWithPasskey() 和 signinWithPasskey()。请在步骤 4 获取的 AuthenticationAPIClient.kt 中确认确切的方法签名，然后将每个调用点迁移到相应的客户端方法。如果无法根据源代码有把握地迁移 Passkey 流程，请添加 // TODO:，并在步骤 10 的摘要中列出，而不要猜测。

---

7.2 — 已移除 Management API（UsersAPIClient）

**适用条件：**步骤 5 在项目源文件中找到了 UsersAPIClient、ManagementException 或 ManagementCallback。

SDK 的整个 Management API 客户端已在 v4 中移除。从移动应用直接调用 Management API 从来就不受推荐——这需要在设备上使用特权令牌。不要悄悄删除调用点。 添加 // TODO: 以保留原有意图，并在步骤 10 的摘要中将其列为所需的后端工作。

// v3 — direct Management API call from the app (e.g. updating user_metadata)
val users = UsersAPIClient(account, accessToken)
users.updateMetadata(userId, metadata)
    .start(object : Callback<UserProfile, ManagementException> { /* ... */ })

// v4 — Management client removed; preserve intent, move to a backend
// TODO: Auth0.Android v4 removed the Management API client (UsersAPIClient).
// Expose an endpoint on your own backend (e.g. PATCH /me/metadata) that performs
// this operation. Call it from the app with the user's access token as a Bearer
// token. On the backend, obtain a machine-to-machine token via Client Credentials
// and call the Management API with the minimum required scopes.
// NEVER embed a Management API token in the app.
// See: https://auth0.com/docs/manage-users/user-accounts/manage-user-metadata

这需要后端工作——请在步骤 10 的摘要中记录。

---

7.3 — 已移除 AuthenticationAPIClient 中弃用的 MFA 方法 → MfaApiClient

**适用条件：**步骤 5 在项目源文件中找到了由 AuthenticationAPIClient 调用的 loginWithOTP(、loginWithOOB(、loginWithRecoveryCode( 或 multifactorChallenge(。

这四个方法在 v3 中已弃用，并在 v4 中移除。请通过 AuthenticationAPIClient.mfaClient(mfaToken) 获取 MfaApiClient，并使用其 API。应用更改前，请在步骤 4 获取的 MfaApiClient.kt 中确认 MfaApiClient 方法的确切签名。

// v3 — removed methods on AuthenticationAPIClient
authentication
    .loginWithOTP(mfaToken, otp)
    .start(object : Callback<Credentials, AuthenticationException> { /* ... */ })

// v4 — obtain an MfaApiClient and use its verify API (confirm signature in MfaApiClient.kt)
val mfaClient = authentication.mfaClient(mfaToken)
// e.g. mfaClient.verifyWithOTP(otp) — use the exact method/parameters from the fetched source

mfaToken 仍然来自同一处——挑战为必需时产生的 AuthenticationException。请在步骤 10 的摘要中列出所有已迁移的 MFA 流程，并要求用户针对其租户端到端重新测试每个 MFA 流程。完整的方法映射请参阅 references/process.md。

---

7.4 — WebAuthProvider.useDPoP(context) 已移至登录构建器

**适用条件：**步骤 5 发现 WebAuthProvider 对象在 .login( 之前调用了 WebAuthProvider.useDPoP(。请查看实际调用链——它可能跨多行。

在 v4 中，useDPoP(context) 是在登录构建器上按请求配置的，而不是全局配置在 WebAuthProvider 对象上。请移动 .useDPoP(context) 调用，使其链式调用位于 .login(account) 之后。

// v3 — global configuration (no longer compiles)
WebAuthProvider
    .useDPoP(context)
    .login(account)
    .start(context, callback)

// v4 — builder-based, per-request
WebAuthProvider
    .login(account)
    .useDPoP(context)
    .start(context, callback)

---

7.5 — 已移除 DPoPException.UNSUPPORTED_ERROR

**适用条件：**步骤 5 在项目源文件中找到了 DPoPException.UNSUPPORTED_ERROR。

由于最低 SDK 要求已提升至 API 26，v4 面向的所有 API 级别均支持 DPoP，因此移除了这个常量。请删除对它的任何引用，例如检查 UNSUPPORTED_ERROR 的 when/if 分支或比较操作。无需替代项；不再会出现不支持版本的情况。

// v3 — guarding against the unsupported case
if (error == DPoPException.UNSUPPORTED_ERROR) {   // ❌ no longer exists in v4
    showDeviceUnsupported()
} else {
    handle(error)
}

// v4 — the guard is no longer applicable; handle the remaining cases
handle(error)

---

7.6 — SSOCredentials.expiresIn → expiresAt（Int → Date）

**适用条件：**步骤 5 在项目源文件中发现访问了 SSOCredentials 值的 .expiresIn。

SSOCredentials.expiresIn（原始秒数，Int）已重命名为 expiresAt，现在是绝对时间 Date（在反序列化期间计算，与 Credentials.expiresAt 一致）。请重命名属性，并更新任何假定其为秒数时长的算术运算。

JSON 线上格式未变——SDK 中的字段仍为 @field:SerializedName("expires_in")。只有 Kotlin 属性名称和类型发生了变化（expiresIn: Int → expiresAt: Date）；如果检索原始 JSON 时使用 grep，请不要期待字段名变为 expires_at。

// v3 — seconds until expiry (Int)
val secondsUntilExpiry: Int = ssoCredentials.expiresIn

// v4 — absolute expiration Date
val expirationDate: Date = ssoCredentials.expiresAt
// If you previously did `now + expiresIn` to get an absolute time, use expiresAt directly.

---

7.7 — 已移除基于 Auth0 的 SecureCredentialsManager 构造函数

**适用条件：**步骤 5 在项目源文件中发现 SecureCredentialsManager( 的第一个参数是 Auth0 实例。

接受 Auth0 实例的两个构造函数已移除。剩下的两个构造函数都要求第一个参数为 AuthenticationAPIClient。请从 Auth0 账户创建客户端，然后将同一个客户端传入 SecureCredentialsManager。

// v3 — Auth0-based constructors (removed in v4)
val manager = SecureCredentialsManager(auth0, context, storage)
val manager = SecureCredentialsManager(auth0, context, storage, fragmentActivity, localAuthenticationOptions)

// v4 — build an AuthenticationAPIClient first, pass it in
val apiClient = AuthenticationAPIClient(auth0)
val manager = SecureCredentialsManager(apiClient, context, storage)

// v4 — biometric variant
val apiClient = AuthenticationAPIClient(auth0)
val manager = SecureCredentialsManager(
    apiClient,
    context,
    storage,
    fragmentActivity,
    localAuthenticationOptions
)

// Java — same change; there is no Java-specific overload
AuthenticationAPIClient apiClient = new AuthenticationAPIClient(auth0);
SecureCredentialsManager manager = new SecureCredentialsManager(apiClient, context, storage);

如果项目启用了 DPoP，请先在客户端上进行配置，再将其传入：AuthenticationAPIClient(auth0).useDPoP(context)。请确认步骤 4 获取的 SecureCredentialsManager.kt 中的构造函数签名。

---

步骤 8 — 编译直至成功

./gradlew assembleDebug 2>&1 | tail -40

对于每条错误：阅读错误信息，找到对应源代码行，将其与步骤 7 的某个小节对应，依据步骤 4 获取的签名验证修复方式，按项目现有风格应用修复，然后重新编译。

常见错误 → 可能原因对应表：

编译错误	可能原因
unresolved reference: PasskeyAuthProvider	§7.1 — 类已移除；改用 AuthenticationAPIClient 的 Passkey API
unresolved reference: UsersAPIClient / ManagementException / ManagementCallback	§7.2 — Management API 已移除；添加 // TODO: 并跟进后端处理
unresolved reference: loginWithOTP / loginWithOOB / loginWithRecoveryCode / multifactorChallenge	§7.3 — 使用 mfaClient(mfaToken) / MfaApiClient
unresolved reference: useDPoP on WebAuthProvider	§7.4 — 将 .useDPoP(context) 移至 .login(account) 之后
unresolved reference: UNSUPPORTED_ERROR	§7.5 — 移除此引用
unresolved reference: expiresIn on SSOCredentials, or Int/Date type mismatch	§7.6 — 重命名为 expiresAt（现在为 Date）
none of the following functions can be called / too many arguments on SecureCredentialsManager(	§7.7 — 先构建 AuthenticationAPIClient(auth0)，再传入
class … must override removeAll（自定义 Storage）	§9.4 — 该接口提供了默认实现；仅在需要时重写

**限制：**最多进行 10 次编译修复循环。如果尝试 10 次后编译仍然失败，请停止并提供剩余错误及其上下文——不要猜测。

---

步骤 9 — 行为与默认值变更（检查，通常无需修改代码）

这些变更无需编辑即可编译，但会改变运行时行为。在步骤 10 的总结中逐一说明。只有当项目依赖旧行为时才修改代码。

9.1 — Credentials Manager 默认 minTtl 从 0 变为 60s

**适用条件：**项目调用 getCredentials(...) / awaitCredentials(...) 时未显式指定 minTtl，或调用 hasValidCredentials()。

v4 会续期将在 60 秒内过期的凭据，而不再仅在凭据已过期时续期。这是推荐行为（可避免发放在请求期间过期的令牌）。如需显式恢复 v3 行为，请传入 minTtl = 0：

// v4 — restore v3 behavior explicitly if required
credentialsManager.getCredentials(scope = null, minTtl = 0, callback = callback)

9.2 — CredentialsManager 现在使用全局执行器

仅影响运行时。同一个 Auth0 对象支持的各个管理器之间的续期现在会串行执行，从而避免重复交换刷新令牌。无需修改代码。

9.3 — clearCredentials() 现在会清除所有存储内容

**适用条件：**项目调用 clearCredentials()。

v4 会调用 Storage.removeAll()，清除存储中的所有值——包括为特定受众存储的 API 凭据。如果项目需要保留同一 Storage 中的其他数据，建议为 API 凭据单独创建一个 Storage 实例，或考虑使用新的 clearAll()（步骤 10 的可选改进）。

9.4 — Storage 接口新增 removeAll()

适用条件： 项目中有类实现了 Storage 接口。

removeAll() 自带默认空实现，因此现有自定义 Storage 实现仍可正常编译。如果自定义存储与 clearCredentials() 一起使用，请重写 removeAll()，以实际清除存储；否则，clearCredentials() 对它将不起作用。

---

第 10 步 — 迁移摘要

简要概述以下内容：

1. 前置条件变更 — 已应用的 minSdk / Java / Gradle / AGP / Kotlin 升级，以及 minSdk 26 不再支持 Android 7.1 及更低版本。

2. 已应用的变更 — 按 API 范围（§7.x）分组，并列出各范围涉及的文件。

3. 需要人工审核

• 已将 §7.1 Passkey / §7.3 MFA 流程迁移到新客户端 — 请针对租户重新进行端到端测试。
• §7.2（Management API）遗留的任何 // TODO: — 需要后端工作。

4. 行为变更（无需修改代码，请确认是否可接受）

• §9.1 minTtl 现在默认为 60s — 令牌会在过期前 60s 续期。
• §9.3 clearCredentials() 现在会清除所有存储内容（包括 API 凭据）。
• §9.2 CredentialsManager 现在使用全局执行器（续期操作将串行执行）。

5. 后端 / 配置后续工作

• §7.2 移除 Management API — 列出使用 TODO 标记的操作，以及必须移至安全后端的内容（M2M 令牌，绝不能存储在设备上）。

6. 未应用的可选改进（简要列出；绝不自动应用）

• clearAll() — 用户登出 / 移除账户时，完整清除凭据和加密密钥。
• 在 onCreate() 中调用 WebAuthProvider.registerCallbacks() — 避免身份验证期间因配置更改或进程终止而丢失回调 / 发生内存泄漏。
• DefaultClient.Builder — 构造函数已弃用（但尚未移除）；构建器可添加写入 / 调用超时、自定义拦截器和日志记录器。
• Gson 2.8.9 → 2.11.0（传递依赖）— TypeToken / 类型强制转换更严格；请参阅 references/process.md。

7. 询问用户是要提交迁移、探索一项可选改进，还是一起逐个检查特定文件。

**安全提醒：**摘要或任何构建日志中绝不能包含令牌、机密、客户端凭据或已存储的凭据值。

---

详细参考资料

• 迁移流程 — 版本参数验证、前置条件 / 工具链处理、构建系统边缘情况（Groovy DSL、Kotlin DSL、版本目录）、MFA 方法映射、Management API 后端模式、Gson 传递依赖说明、回滚，以及“已弃用 ≠ 已移除”的指导。
• 安全检查清单 — 迁移前后必须满足的约束。

常见错误

错误	正确做法
第 5 步未在项目中找到某个 API，却仍应用 §7.x 章节	第 5 步的文件读取是判断依据。未找到 = 完全跳过该章节
仅凭 grep 判断是否使用了某个 API	grep 会漏掉多行构建器链（例如在 login 前调用 useDPoP）和别名变量。请阅读实际文件
尚未满足第 3 步的前提条件，就迁移 API 调用位置	minSdk 26 / Java 17 以下的项目无法使用 v4 构建。请先处理前提条件
不验证目标版本，就接受版本参数	验证版本是否存在、是否为下一个主版本、是否不是降级版本；若验证失败，停止并询问用户
为预发布标签使用动态版本范围（4.+）	固定预发布版本 — 版本范围可能解析到其他制品
默默删除 Management API 或已移除 MFA 的调用位置	添加 // TODO: 并在摘要中指出 — 删除会破坏功能
未确认 SDK 源码，就应用迁移指南中的更改	每项修复都必须能追溯到第 4 步获取的文件中的签名
将 DefaultClient(...) 构造函数视为破坏性变更	它是已弃用，而非已移除 — 保留它；说明 Builder 是可选项
在工作树有未提交更改时开始操作	始终先确认 git status --porcelain 输出为空
构建失败周期超过 10 次仍继续	停止并向用户展示剩余错误
跳过迁移摘要	始终提供完整摘要 — 用户需要它

相关技能

• auth0-android — 从头开始集成 Auth0.Android
• auth0-swift-major-migration — 升级 Auth0.swift 主版本
• auth0-mfa — 配置多因素身份验证

---

参考资料

• Auth0.Android GitHub
• Auth0.Android Releases
• V4 Migration Guide
• Auth0 Android SDK Documentation

**安全：**切勿在构建日志或终端输出中回显令牌、客户端密钥或凭据。切勿将机密提交到版本控制中。