Android库开发minSdkVersion与@TargetApi选型疑问
核心结论：二者生效层级、校验逻辑完全不同，不存在“全库删除minSdkVersion、仅靠@TargetApi做版本限制”的通用最优解，需要根据库的实际兼容逻辑选择配置方式。
一、必须优先使用minSdkVersion、无法用@TargetApi替代的场景
@TargetApi（以及语义更明确的替代注解@RequiresApi）仅对Java/Kotlin代码层面的Lint告警生效，完全覆盖不到以下场景，这类场景必须正确配置minSdkVersion：
- 当库存在Manifest、资源层面的高版本依赖时
注解无法校验Manifest中声明的高版本组件属性、权限、系统特性要求，也无法校验res目录下的高版本XML资源、格式依赖。比如库Manifest中声明了API 28才支持的android:foregroundServiceType属性，或使用了API 26才支持的自适应图标、XML字体资源，就算给所有代码加了@TargetApi注解，minSdk低于对应版本的应用接入后，要么在低版本系统上安装时直接包解析失败，要么运行时触发资源加载、类加载崩溃，这类硬不兼容场景必须靠minSdkVersion给构建工具传递明确的校验信号。 - 当库全链路无低版本降级逻辑时
如果库的核心初始化流程、所有公开API 100%依赖高版本系统能力（比如全链路依赖Vulkan渲染、低版本ART无法加载库使用的字节码格式），不存在“低版本判断后降级兼容”的可能，必须将minSdkVersion设置为对应版本值，从构建层面给出明确的不兼容提示。这种场景下如果靠@TargetApi替代minSdkVersion，等于完全放弃构建层的硬校验，把版本判断责任全部甩给接入方，一旦接入方漏做版本判断直接调用，低版本设备上会直接触发NoClassDefFoundError、NoSuchMethodError等不可逆崩溃，风险远高于接入方需要手动添加tools:override的体验成本。 - 当需要构建工具自动处理兼容逻辑时
AGP的脱糖逻辑、高版本API兼容类注入（如java.time包的向后兼容、集合类的版本适配）、资源兼容处理，都是基于库声明的minSdkVersion判断是否执行的。如果刻意把库的minSdkVersion设低、仅靠注解标注高版本API，构建工具会注入大量库本身不需要的兼容代码，无端增大库体积；如果库实际需要脱糖支持却没有声明正确的minSdkVersion，构建时不会触发对应脱糖流程，高版本API在低版本系统上会直接崩溃。
二、适合用版本注解、不需要抬升全库minSdkVersion的场景
如果库本身具备分层兼容能力：核心功能支持低版本，仅部分可选高级能力依赖高版本API，就不应该抬升全库的minSdkVersion。比如库核心功能支持API 21，仅通知渠道、画中画等可选功能需要API 26，这种场景只需要给高版本专属的类、方法添加@RequiresApi(26)注解，内部做好版本判断分支，低版本走兼容实现即可。接入方minSdk为21时也能正常使用核心功能，仅在直接调用高版本专属API时Lint会提示添加版本校验，不需要做override配置。
注：做库开发时优先使用
@RequiresApi而非@TargetApi：@TargetApi的作用是压制当前代码内部调用高版本API的Lint告警，不会提示调用方做版本校验；@RequiresApi会明确向调用方传递“调用该方法/类需要满足指定API版本要求”的信号，触发调用方侧的Lint告警，更符合库的版本约束需求。
三、版本注解的批量配置方案
目前没有官方提供的包级别生效的版本注解，但有两种可落地的批量配置方案，不需要逐个给方法加注解：
- 通过Lint配置指定目录的校验基准
在库的build.gradle中配置lint规则，给指定源码目录设置API校验基准，效果等同于给目录下所有代码添加对应版本的@TargetApi注解：android { lintOptions { // 对指定路径下的代码，按API 26做NewApi规则校验 check 'NewApi', 26, 'src/main/java/com/your/lib/highlevel/**' } } - 使用文件级注解覆盖整个文件
对Kotlin代码，可以在文件顶部添加文件级注解，作用范围覆盖当前文件内的所有类、方法，大幅减少注解添加量：// 该文件下所有代码默认要求API 26 @file:RequiresApi(Build.VERSION_CODES.O) package com.your.lib.highlevel
针对全库API最低支持26场景的实践建议
不需要删除minSdkVersion配置，保持minSdkVersion=26即可。tools:override本身就是官方预留的、给接入方明确知晓风险、自行做好版本判断后才使用的口子，只需要在接入文档中明确说明库的最低支持版本，以及override操作的适用场景即可，不要为了降低接入时的配置成本，放弃构建层的硬安全校验。
内容的提问来源于stack exchange，提问作者Maurice Lam
