适用于Android库的Android API级别注释 [英] Android API level annotation for Android libraries

问题描述

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

I am writing an Android library. The vast majority of the interface in the lbirary supports Android API level 10 or above. Some functionality, though, requires a higher API level. For instance, part of the library requires API 18 for Bluetooth Low Energy.

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

For the sake of concreteness, let's say that the library produces three classes ClassA, ClassB and ClassC. ClassA uses functionality available in API 10, ClassB uses functionality available in API 14 and ClassC uses functionality available in API 18.

我希望每当有人使用我的类时，就能够触发皮棉问题（警告/错误）库，而不在项目中具有必需的API级别（除非它们使用适当的注释抑制警告），类似于lint使用的内置NewApi问题。

I want to be able to trigger a lint issue (warning/error) whenever someone uses a class from my library without having the required API level in their project (unless they suppress the warning with the appropriate annotation), similar to the already built-in NewApi issue used by lint.

搜索之后，我发现了以下可能的解决方案：

After searching, I have found the following possible solutions:

1）这种解决方案并非一尘不染：将库分成三个.jar文件，说 lib_10.jar 包括使用API​​ 10中可用功能的所有类（示例中为ClassA）， lib_14.jar 包括所有使用API​​ 14中可用功能的类（示例中为ClassB）和 lib_18.jar ，其中包括所有使用API​​中可用功能的类API 18（示例中为ClassC）。此解决方案具有可移植性，但会使代码库的后期可维护性复杂化，并且还可能需要重复一些代码。

1) This solution isn't along the lines of lint: Split the library into three .jar files, say lib_10.jar that includes all classes using functionality available in API 10 (ClassA in the example), lib_14.jar that includes all the classes using functionality available in API 14 (ClassB in the example) and lib_18.jar that includes all classes using functionality available in API 18 (ClassC in the example). This solution allows portability but would complicate the later maintainability of the codebase and would potentially require some code duplication as well.

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

2) Create my own annotation (say, @RequireAndroidApi(API_LEVEL) indicating the minimum API level required by the annotated class/method/etc...) and use the lint-api.jar (http://tools.android.com/tips/lint-custom-rules) to create a custom lint rules that check the usage of any annotated classes/methods/etc... with a lower API than required. Something that would later look like this:

@RequireAndroidApi(10)
Class ClassA {
}

@RequireAndroidApi(14)
Class ClassB {
}

@RequireAndroidApi(18)
Class ClassC {
}

问题是我找不到关于lint API的好的文档，而且看来这是在重新发明皮棉已经支持的功能（皮棉已经检查 NewApi问题）了。

The problem is that I couldn't find good documentation for the lint API and it seems that this is reinventing the wheel for a functionality that lint already supports (lint already checks for the "NewApi" issue).

3）最后，我成功地编辑了 < SDK> /platform-tools/api/api-versions.xml ，以指示每个类所需的API级别，如下所示：

3) Finally, I succeeded to edit <SDK>/platform-tools/api/api-versions.xml in order to indicate the API level required by each class as follows:

<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>

这导致棉绒以与Android API相同的方式触发NewApi问题。我喜欢这种解决方案，因为它不会浪费很多精力，而且进一步抛出任何错误都会利用Eclipse或Android Studio中编程的建议解决方案来解决该问题（即Eclipse中的快速修复）。该解决方案的问题在于，它需要编辑Android SDK随附的 api-versions.xml ，由于以下几个原因，该解决方案对于发布该库不是很方便。 ：a） api-versions.xml 文件不是项目本地的，并且会更改所有android项目（包括不使用该库的android项目）的lint行为； b）每次从Android SDK管理器更新SDK时，都会覆盖 api-versions.xml ，这将覆盖所做的任何更改。

Which caused lint to trigger the NewApi issue in the same manner as it would with the Android APIs. I like this type of solution because it doesn't reinvent the wheel and further any errors thrown this way would utilize the suggested solutions programmed in Eclipse or Android Studio to deal with the problem (i.e. "quick fixes" in Eclipse). The problem with this solution is that it requires editing api-versions.xml that ships with the Android SDK, which makes this solution not very portable for releasing the library for several reasons including: a) the api-versions.xml file is not local to a project and changes the behavior of lint for all android projects, including the ones that do not use the library; and b) api-versions.xml will be overwritten every time the SDK is updated from the Android SDK manager which would overwrite any changes made.

我想知道是否有一个更简单的解决方案来实现最小的API错误/警告，或者是否有一种方法可以编写类似于 api-versions.xml的单独文件可以放置在项目目录中，每当在有关项目上运行皮棉时，皮棉都可以读取 lint.xml ）。

I was wondering if there is a simpler solution to achieve this "minimum API errors/warnings" or if there is a way to write a separate file similar to api-versions.xml that can be placed in the project directory which can be read by lint whenever lint is ran on the project in question (something similar to lint.xml).

感谢您在本问题的详细介绍中与我保持联系，并感谢您提前提供的帮助。

Thanks for bearing with me during this long description of the problem and I appreciate any help in advance.

推荐答案

无需创建自己的注释，android支持库的 @RequiresApi 注释就是您要寻找的。例如：

There is no need to create your own annotation, the android support library's @RequiresApi annotation is what you are looking for. For example:

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

此注释告诉lint警告 someMethod（）是否为

This annotation tells lint to warn if someMethod() is used in a context that may have a lower API level.

请注意， @TargetApi 是不同的：它用于确保lint，该注解的方法只能用目标API调用，否则它会警告您不要使用该方法。因此， @TargetApi 可用于使由 @RequiresApi 触发的棉绒警告静音。

Note that @TargetApi is different: It's used to assure the linter that the annotated method will only be called with the targeted API, in a situation where it would otherwise warn you not to use that method. So @TargetApi can be used to silence the lint warning triggered by @RequiresApi.

这篇关于适用于Android库的Android API级别注释的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！