PermissionsDispatcher项目迁移指南：从旧版本升级到最新版的最佳实践

PermissionsDispatcher项目迁移指南：从旧版本升级到最新版的最佳实践

PermissionsDispatcher 项目地址: https://gitcode.com/gh_mirrors/pe/PermissionsDispatcher

前言

PermissionsDispatcher是一个简化Android运行时权限处理的优秀库，随着Android系统的演进和库本身的迭代，开发者需要了解如何将项目从旧版本迁移到新版本。本文将详细介绍从1.x到最新版的完整迁移过程，帮助开发者平滑过渡。

迁移到Maven Central仓库

由于Maven Central对groupId有严格要求，PermissionsDispatcher不得不再次变更groupId。这是开发者需要首先注意的变化。

基础依赖变更

dependencies {
-  implementation "org.permissionsdispatcher:permissionsdispatcher:${latest.version}"
+  implementation "com.github.permissions-dispatcher:permissionsdispatcher:${latest.version}"
-  annotationProcessor "org.permissionsdispatcher:permissionsdispatcher-processor:${latest.version}"
+  annotationProcessor "com.github.permissions-dispatcher:permissionsdispatcher-processor:${latest.version}"
}

Kotlin扩展库特别说明

由于历史原因，Kotlin扩展库的artifactId存在两种形式，但ktx才是正确的形式：

dependencies {
-  implementation "org.permissionsdispatcher:permissionsdispatcher-ktx:${latest.version}"
+  implementation "com.github.permissions-dispatcher:ktx:${latest.version}"
}

迁移到4.x版本

1. Maven groupId变更

4.x版本将groupId从com.github.hotchemi变更为org.permissionsdispatcher：

dependencies {
-  implementation "com.github.hotchemi:permissionsdispatcher:${latest.version}"
+  implementation "org.permissionsdispatcher:permissionsdispatcher:${latest.version}"
-  annotationProcessor "com.github.hotchemi:permissionsdispatcher-processor:${latest.version}"
+  annotationProcessor "org.permissionsdispatcher:permissionsdispatcher-processor:${latest.version}"
}

2. 迁移到AndroidX支持

从4.x版本开始，PermissionsDispatcher全面转向支持AndroidX(Jetpack组件)，不再支持旧的AppCompat库。在升级到4.x之前，请确保已完成项目的AndroidX迁移工作。

迁移到3.x版本

1. 方法命名变更

3.0版本对生成的方法名进行了更语义化的调整，将***WithCheck后缀改为***WithPermissionCheck：

- MainActivityPermissionsDispatcher.showCameraWithCheck(this);
+ MainActivityPermissionsDispatcher.showCameraWithPermissionCheck(this);

这一变更使生成的代码更具声明性，更清晰地表达其功能。

2. 增强的Kotlin支持

3.x版本提供了更原生的Kotlin支持，主要变化包括：

方法调用简化

button.setOnClickListener {
-   MainActivityPermissionsDispatcher.showCameraWithCheck(this)
+   showCameraWithPermissionCheck()
}

权限结果处理简化

override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<String>, grantResults: IntArray) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
-   MainActivityPermissionsDispatcher.onRequestPermissionsResult(requestCode, grantResults)
+   onRequestPermissionsResult(requestCode, grantResults)
}

这些方法现在作为扩展函数提供，不再需要通过***PermissionsDispatcher类调用。

迁移到2.x版本

2.x版本是PermissionsDispatcher的一个重要里程碑，内部进行了彻底重构，主要变化包括：

1. 依赖配置更新

确保使用正确的版本号：

dependencies {
    compile "com.github.hotchemi:permissionsdispatcher:2.0.0"
    apt "com.github.hotchemi:permissionsdispatcher-processor:2.0.0"
}

2. 注解统一化

@NeedsPermission注解

废弃了复数形式的@NeedsPermissions，统一使用@NeedsPermission：

@NeedsPermission({ CAMERA, WRITE_EXTERNAL_STORAGE })
void setupCamera() {
}

@OnShowRationale注解

废弃了@ShowsRationale和@ShowsRationales，引入新的@OnShowRationale注解。新注解的方法需要接收一个PermissionRequest参数，开发者可以控制权限请求流程：

@OnShowRationale({ CAMERA, WRITE_EXTERNAL_STORAGE })
void showCameraRationale(final PermissionRequest request) {
    new AlertDialog.Builder(...)
        .setPositiveButton("OK", (dialog, which) -> request.proceed())
        .setNegativeButton("Abort", (dialog, which) -> request.cancel())
        .show();
}

@OnPermissionDenied注解

废弃了@DeniedPermission和@DeniedPermissions，统一使用@OnPermissionDenied：

@OnPermissionDenied({ CAMERA, WRITE_EXTERNAL_STORAGE })
void cameraDenied() {
}

迁移建议与最佳实践

1. 逐步迁移：建议按照版本顺序逐步迁移，先升级到2.x，然后是3.x，最后到最新版。

2. 测试覆盖：每次升级后，确保全面测试所有权限相关功能。

3. 利用编译时检查：新版本的PermissionsDispatcher提供了更好的编译时检查，利用这些错误提示可以快速定位迁移问题。

4. Kotlin用户：如果使用Kotlin，强烈建议升级到3.x或更高版本以获得最佳开发体验。

5. AndroidX准备：计划升级到4.x的项目，应提前完成AndroidX迁移。

结语

PermissionsDispatcher的每次大版本升级都带来了更好的开发体验和更强的功能。通过遵循本指南，开发者可以顺利完成迁移工作，享受新版本带来的便利。随着Android权限系统的演进，PermissionsDispatcher将继续为开发者提供简洁高效的权限处理方案。

PermissionsDispatcher 项目地址: https://gitcode.com/gh_mirrors/pe/PermissionsDispatcher