Android 库的 Android API 级注解

Question

我正在编写一个 Android 库。 lbirary 中的绝大多数接口(interface)都支持 Android API 级别 10 或更高版本。但是，某些功能需要更高的 API 级别。例如，部分库需要用于低功耗蓝牙的 API 18。

为了具体起见，假设库生成了三个类 ClassA , ClassB和 ClassC . ClassA使用 API 10 中可用的功能，ClassB使用 API 14 和 ClassC 中可用的功能使用 API 18 中提供的功能。

我希望能够在有人使用我的库中的类时在他们的项目中没有所需的 API 级别时触发 lint 问题(警告/错误)(除非他们使用适当的注释抑制警告)，类似于lint 使用的已经内置的 NewApi 问题。

经过搜索，我找到了以下可能的解决方案:

1) 此解决方案与 lint 不一致:将库拆分为三个 .jar 文件，例如 lib_10.jar其中包括使用 API 10 中可用功能的所有类(示例中的 ClassA)，lib_14.jar其中包括使用 API 14 中可用功能的所有类(示例中的 ClassB)和 lib_18.jar其中包括使用 API 18 中可用功能的所有类(示例中的 ClassC)。该解决方案允许可移植性，但会使代码库的后期可维护性复杂化，并且可能还需要一些代码重复。

2) 创建我自己的注解(例如，@RequireAndroidApi(API_LEVEL) 指示被注解的类/方法/等所需的最低 API 级别...)并使用 lint-api.jar ( http://tools.android.com/tips/lint-custom-rules ) 创建一个自定义的 lint 规则，检查任何带注释的类/方法/等的使用...使用低于要求的 API。稍后看起来像这样的东西:

@RequireAndroidApi(10)
Class ClassA {
}

@RequireAndroidApi(14)
Class ClassB {
}

@RequireAndroidApi(18)
Class ClassC {
}

问题是我找不到很好的 lint API 文档，这似乎是重新发明 lint 已经支持的功能的轮子(lint 已经检查了“NewApi”问题)。

3)终于编辑成功了<SDK>/platform-tools/api/api-versions.xml为了表明每个类需要的API级别如下:

<api version="1">
    ...
    <class name="package/path/ClassA" since="10">
        <extends name="java/lang/Object" />
        <method name="&lt;init>()V" />
    </class>
    <class name="package/path/ClassB" since="14">
        <extends name="java/lang/Object" />
        <method name="&lt;init>()V" />
    </class>
    <class name="package/path/ClassC" since="18">
        <extends name="java/lang/Object" />
        <method name="&lt;init>()V" />
    </class>
</api>

这导致 lint 以与 Android API 相同的方式触发 NewApi 问题。我喜欢这种类型的解决方案，因为它不会重新发明轮子，而且以这种方式抛出的任何错误都会利用在 Eclipse 或 Android Studio 中编程的建议解决方案来处理问题(即 Eclipse 中的“快速修复”)。此解决方案的问题在于它需要编辑 api-versions.xml随 Android SDK 一起提供，这使得该解决方案对于发布库来说不是很便携，原因包括:a) api-versions.xml文件不是项目的本地文件，它会更改所有 android 项目的 lint 行为，包括那些不使用该库的项目；和 b) api-versions.xml每次从 Android SDK 管理器更新 SDK 时都会被覆盖，这将覆盖所做的任何更改。

我想知道是否有更简单的解决方案来实现此“最少的 API 错误/警告”，或者是否有一种方法可以编写类似于 api-versions.xml 的单独文件可以放置在项目目录中，只要在相关项目上运行 lint 时，lint 就可以读取该目录(类似于 lint.xml )。

感谢您在对问题进行如此长的描述期间耐心等待，感谢您提前提供的任何帮助。

Answer 1

不需要自己创建注解，android支持库的@RequiresApi注释是你要找的。例如:

@RequiresApi(Build.VERSION_CODES.LOLLIPOP)
public void someMethod() {}

如果在可能具有较低 API 级别的上下文中使用 someMethod()，此注释告诉 lint 发出警告。

请注意，@TargetApi 是不同的:它用于确保 linter 仅使用目标 API 调用带注释的方法，否则它会警告您不要使用该方法.因此 @TargetApi 可用于消除由 @RequiresApi 触发的 lint 警告。