Jsoup 1.17.2在Android Release构建时的类缺失问题解析

问题背景

在使用Jsoup 1.17.2版本进行Android应用开发时，开发者在构建Release版本时可能会遇到一个关于类缺失的构建错误。这个错误特别出现在使用ProGuard/R8进行代码优化和混淆的过程中。

错误表现

构建系统会报告以下错误信息：

Missing classes detected while running R8. Please add the missing classes or apply additional keep rules...
Missing class org.jspecify.annotations.NullMarked

错误信息明确指出在构建过程中缺少org.jspecify.annotations.NullMarked类，这个类被Jsoup内部注解FieldsAreNonnullByDefault等引用。

问题根源

这个问题的本质在于Jsoup 1.17.2版本开始使用了JSpecify注解库中的@NullMarked注解，但该注解库被声明为"provided"作用域的依赖。在Android构建环境中：

1. JSpecify注解库仅用于编译时检查
2. 这些注解在运行时不需要实际存在
3. 但ProGuard/R8在优化阶段会检查所有引用的类

解决方案

开发者有两种主要方式解决这个问题：

方案一：添加ProGuard排除规则

在项目的ProGuard配置文件中添加以下规则：

-dontwarn org.jspecify.annotations.NullMarked

这种方法简单直接，告诉构建系统忽略关于这个缺失类的警告。

方案二：显式添加JSpecify依赖

在项目的构建配置中显式添加JSpecify依赖：

implementation 'org.jspecify:jspecify:0.3.0'

这种方法更符合依赖管理的规范，确保所有需要的类在构建时都可用。

技术建议

对于大多数Android项目，推荐使用方案一，因为：

1. JSpecify注解确实是编译时依赖
2. 添加实际依赖会增加APK大小（虽然很小）
3. 这些注解在运行时确实不需要

但如果项目本身就需要进行空安全相关的静态分析，那么方案二可能更合适，因为它可以提供完整的注解支持。

版本兼容性说明

这个问题从Jsoup 1.17.0版本开始出现，因为该版本开始引入了对JSpecify注解的使用。如果项目不能升级构建配置，可以考虑暂时回退到1.16.1版本，但会错过后续版本的安全更新和功能改进。

总结

Jsoup引入现代Java注解规范导致的构建问题，反映了Java生态向更严格类型检查演进的过程。Android开发者需要理解这类"provided"作用域依赖的特殊性，并掌握ProGuard/R8配置技巧来应对类似的构建问题。