编写 Android Library 的最佳实践

写在前面

一直以来，技术圈里面只要涉及 Android Library 的文章，几乎都在讲如何发布到 Maven/Jcenter，却很少见到有文章来指导大家如何编写一个规范又好用的 Android Library。

这几年 Android 各式各样的开源库层出不穷，国内的很多开发者都慷慨地将自己的一些成果做成开源库发布出去，然而当我们兴致盎然地想去试用一下这些库的时候，却时常会遇到“引用”“依赖”“冲突”“API 调用”等各种问题，这其中有很多问题，其实是库的作者本身造成的。

魅族的联运 SDK 从去年8月份开始立项，10月份开始逐渐有合作伙伴开始接入，经过半年多以来已经有超过50家 cp 应用接入，期间版本仅升级了1次，其余时间一直在稳定运行并寻求新的合作伙伴。在期间我们也收到了很多 cp 应用开发者的反馈，但更多的都表示这个库接起来非常轻松易上手，这也让我非常欣慰。

事实上，我在正式参加工作之前，已经做了2年多时间的个人开发者，这段经历让我深刻地体会到了开发者究竟喜欢什么，不喜欢什么。如果每一个 Android Library 的作者在编写的时候能够常去换位思考，多站在接入者的角度审视自己这个库的设计与实现，那么往往出来的 Android Library 效果都不会差。所以我会在接下来的内容中跟大家分享一些我们的做法，这些做法有一些也是踩了坑之后才填上的，我会把他们写出来，希望对大家今后的开发工作有所帮助。

规范工程结构

一个规范的 Android Library 工程应该由一个 library模块与一个demo模块共同组成。

demo模块的好处有两点：

1. 方便开发时自己调试，自己写的库，自己写的过程中就要不停尝尝咸淡才能保证“真香”
2. 库发布后可以编译出 apk 供人先行体验

注意 demo 模块的 build.gradle 在引用 library 时应该做出区分，如果是 debug编译模式，则直接引用 library 项目，如果是 release编译模式，则应该引用你发布的版本。相信 android 开发者都有过“开发调试的时候好好的，编出来的正式版就有问题”的经历，使用这样的引用模式，万一你发布的库有问题，则可以在编译 demo apk 的时候立刻发现。好在 build.gradle 在引用的时候可以很方便做出区分：

        debugImplementation project(':library') //debug 版本直接引用本地项目
        releaseImplementation '远程库地址'   //release 版本引用远程版本用来最终测试发现问题

指导接入者快速依赖全部 aar

如果你的库没办法发布到 mavenCentral，那么提供 SDK 给别人的时候 可能会有多个 aar 需要对方添加到项目里。我们经常在网上看到一做法，要求接入者在依赖时，先把 aar 文件拷贝到项目下，然后修改 build.gradle 申明参与编译，接入者必须仔细看 aar 的名字是什么，因为在 build.gradle 是需要声明清楚的。

事实上，你的接入者没有义务去弄清你的 aar 命名。接你的库已经够累了，为什么还要人家仔细看你的命名呢？这里推荐一种做法：

1. 让你的接入者在他们项目 app 模块下新建 libs/xxx 目录，将你们提供的所有 aar拷贝进去，这个 XXX 可以是你们渠道的名字，以后这个下面的 aar 就全是你们的，跟其它的隔离开。
2. 打开 app 的 build.gradle，在根节点声明：

repositories {
    flatDir {
        dirs 'libs/xxx'
    }
}

3.在 dependencies{} 闭包内添加如下声明：

//递归 'libs/xxx` 下所有的 aar 并引用 def xxxLibs = project.file('libs/xxx') xxxLibs.traverse(nameFilter: ~/.*\.aar/) { file -> def name = file.getName().replace('.aar', '') implementation(name: name, ext: 'aar') } 

或者，我们可以参考依赖的第一行，直接用下面的代码一步到位（感谢评论区 @那时年少）：

    implementation fileTree(include: ['*.aar'], dir: 'libs/xxx')

这么一来，gradle 在编译前就会自动进到 xxx 目录下面，遍历并引用所有 aar 文件。之后哪个 aar 有更新，就让你的接入者直接把新的扔到 XXX 目录，删除老的就行。至于你的 aar前缀是啥，他们根本不用关心。

Kotlin？大胆用!

Google 早在2017年就官宣了 Android 与 Kotlin 的关系。我在这次写 SDK 的时候最大胆的决定就是全部使用 Kotlin，事实证明我是正确的。Kotlin 的引入帮我省去了大量的胶水代码，各种语法糖吃起来也是真香。所以从现在起如果你决心造一个轮子，大胆全部使用 Kotlin 来写吧，但是请注意。因为你的引用者大部还是 Java 程序员，甚至可能还不熟悉 Kotlin，因此一些兼容点还是值得注意的。

引用者的项目必须添加 Kotlin 支持

如果你的库是 Kotlin 编写的，不管用你库的人是用 Java 调还是 Kotlin，请他们把项目添加 Kotlin 支持，否则在编译期间没问题，但在运行期间很有可能遇到NoClassDefError，比如下面这个：

java.lang.NoClassDefFoundError:Failed resolution of: Lkotlin/jvm/internal/Intrinsics

而添加依赖的方法也很简单：只需要 Android Studio -> Tools -> Kotlin -> Configure Kotlin in project， Android Studio 会自动帮助项目添加依赖插件, Gradle Sync 一下如果没问题，就搞定了。

伴生对象里需要暴露的 api 请打上 @JvmStatic

已经在写 Kotlin 的小伙伴应该都清楚，Kotlin 的“静态方法”、“静态常量”是靠“伴生对象”来实现的。比如一个简单的类：

class DemoPlatform private constructor() {
    companion object {
        fun sayHello() {
            //do something
        }
    }
}

这个类如果我想调 sayHello() 方法，在 Kotlin 里非常简单，直接 DemoPlatform.sayHello()就好。但是如果在 Java 里，就必须使用编译器自动帮我们生成的 Companion 类，变成 DemoPlatform.Companion.sayHello()。这对于不熟悉 Kotlin 的 Java 程序员来说是很不友好的，尽管 IDE 的提示可能会让他们自己最终摸索出这个方法，但是面对不熟悉的 Companion 类仍然会一脸懵。所以最佳的做法是给这个方法打上@JvmStatic注解：

        @JvmStatic
        fun sayHello() {
            //do something
        }

这么一来编译器就会为你这个 Kotlin 方法（Kotlin function）单独生成一个静态可直接访问的 Java 方法（Java method），此时再回到 Java 类里面，你就可以直接 DemoPlatform.sayHello()了。

事实上这个方法 Google 自己也在用，如果你的项目在用 Kotlin，你可以尝试在代码树上右击 -> New -> Fragment -> Frgment(Blank)，让 Android Studio 自动为我们创建一个 Fragment。我们都知道一个规范的 Fragment 必须包含一个静态的 newInstance() 方法，来限制传进来的参数，可以看到 Android Studio 自动帮我们生成的这个方法上面，也有一个 @JvmStatic 注解。

        @JvmStatic
        fun newInstance(param1: String, param2: String) =
                BlankFragment().apply {
                    arguments = Bundle().apply {
                        putString(ARG_PARAM1, param1)
                        putString(ARG_PARAM2, param2)
                    }
                }

很多项目在迁移阶段肯定是 Java 与 Kotlin 混调的，而我们作为一个给别人用的 Android Library 就更不用说了，一个小小的注解可以省下接入者的一些学习成本，何乐而不为呢？

Proguard 混淆

自我混淆

如果你的库仅仅想供人使用，而并没有打算完全开源，请一定记得打开混淆。在打开之前。把需要完全暴露给调用者的方法或者属性打上@android.support.annotation.Keep注解就行，比如上面的 sayHello()方法，我希望把它暴露出去，那就变成了：

        @Keep
        @JvmStatic
        fun sayHello() {
            //do something
        }

当然了，不仅仅是方法，只要是@Keep注解支持的范围都可以。如果你还不知道 @Keep注解是咋回事，兄弟你再不补课就真的要失业了。

而启用混淆的方法也很简单，在编译 release 版本的时候把混淆启用即可，就像这样：

release {
    minifyEnabled true
    proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}

这样一来，调用者依赖了你的库之后，除了你自己暴露的方法或者类，一些内部实现就不那么容易找到了。

把自己的 ProGuard 配置文件打包进 aar

我们经常在一些开源库的主页介绍下面看到一段 Proguard 内容，目的是让调用者把他加到自己 app 模块的 Proguard 配置文件中去。其实 Android 的编译系统早就支持库模块包含自己的 ProGuard 配置文件了，如果你希望你自己库里的一些代码，在调用者编译时也不被混淆，可以在自己 library 的 proguard-rules.pro里定义好：

然后打开 library 的 build.gradle， 在 defaultConfig 闭包里调用 consumerProguardFiles() 方法：

 defaultConfig { minSdkVersion build_versions.min_sdk targetSdkVersion build_versions.target_sdk consumerProguardFiles 'proguard-rules.pro' 
 ... } 

加上之后我们可以编译一次 aar，打开看一下，会发现里面多了一个 proguard.txt文件，一旦你的库被依赖，Gradle 会把这个规则与 app 模块的 Proguard 配置文件 合并后一起运行混淆，这样一来引用你 library 的人就再也不用担心混淆配置的问题了，因为你已经完全帮他做好。

so 文件

CMake 直接编译 so 文件

联运 SDK 由于涉及支付业务，一些安全相关的工作势必要放到 C 层去执行。在最开始的时候我也考虑过直接编译好 so 文件，让接入方直接拷贝到 jni 目录下，事实上国内现在很多第三方库让别人接的时候都是这么做的，然而这个做法实在是太不酷了，接入方在操作过程中经常会遇到这几个问题：

1. so 名字是什么？
2. 拷到哪个目录下面？
3. build.gradle怎么配？
4. abi 怎么区分？

好的是，从 Android Studio 2.3 开始，CMake 已经被很好地集成了进来，我们可以在项目里直接添加 C/C++ 的代码，然后编译期间动态生成 so 文件。

关于项目里集成 C/C++ 编译的方法，网上已经有很多教程了，大家 Google 一下 Android Studio Cmake 就会有很多。当然我最推荐的还是官网教程。或者如果你跟我一样喜欢动手实践的话，可以新建一个干净的 Android Project，然后在向导里勾上 Include C++ Support，最后生成出来的工程就会包含一个简单的例子，学习起来非常容易。

extern "C" JNIEXPORT jstring JNICALL
Java_your_app_package_name_YourClass_stringFromJNI( JNIEnv *env, jobject /* this */) {
    std::string hello = "Hello from C++";
    return env->NewStringUTF(hello.c_str());
}

class YourClass(private val context: Context) {
    init {
        System.loadLibrary(your-name-lib")
    }
    /** * A native method that is implemented by the 'native-lib' native library, * which is packaged with this application. */
    external fun stringFromJNI(): String  //Kotlin 的 external 关键字 类似 Java 的 native 关键字
}

尽量包含所有 abi，把选择权交给接入方

在联运 SDK 上线后的一个月，我们收到 cp 反馈接入了之后有奔溃，后来检查发现是 armeabi 下没有 so 文件导致的。这本没有什么问题。但是你没有办法保证接入方应用的 armeabi 文件里也是空的，一旦这里面有 so ，android 就会去这里面找；还有一种可能就是现在很多应用会设置 abiFilter 去过滤掉一些 abi，万一人家只想保留 armeabi，而你的 library 里面又没有，这两种情况都会导致 crash。然而：

ndk r16b 已经弃用了 armeabi ，r17c 直接移除了对 armeabi 的支持, 如果有生成 armeabi 的需求只能降低 ndk 版本。（感谢评论区 @我啥时候说啦jj整理指出）

所以为了确保兼容，我们必须在 library 的 build.gradle里手动声明自己需要编出哪几个 abi：

    defaultConfig {
        externalNativeBuild {
            cmake {
                cppFlags ""
                abiFilters 'arm64-v8a', 'armeabi', 'armeabi-v7a', 'x86', 'x86_64'
            }
        }
    }

这么一来你的 library 编出来之后就会包含上面 5 种 abi，确保所有的新老机型起码都不会崩溃，如果你的接入方嫌你的 so 太多太大了，他自己可以在 app编译期间设置过滤，“反正我都有，你自己挑吧”。

Resource 资源

库内部资源的命名不要干扰接入方

相信大家平时开发过程中都有过类似的经历：一旦引入了一些第三方库，自己写代码的时候，想调用某个资源文件，一按提示，IDE 提示的全是这些第三方库里面的资源，而自己 app 里面的资源却要找半天。

我们平时写库的时候难免会自己定义一些 Resource 文件，包括string.xml xxx_layout.xml color.xml 等等，这些库生成的 R.java 一旦参与 app 的编译之后，是可以直接被引用到的，所以自然而言也会被 IDE 索引进提示里面。而照常来讲，一个应用是不应该直接引用一些第三方库里面的资源的，搞不好就很容易出现一些问题。比如万一哪天人家库升级把这串值改掉了，或者干脆拿掉了，你 app 就跪了。

联运 SDK 在开发的时候就注意到了这一点，比如我们的 SDK 叫 MeizuLibrarySdk，那么我在定义 strings.xml时，我会写：

    <string name="mls_hello">你好</string>
    <string name="mls_world">世界</string>

再比如，我需要定义一个颜色，我会在 colors.xml里面写：

    <color name="mls_blue">#8124F6</color>

相信大家应该已经发现了，每一个资源都会以 mls 开头，这样有个好处，就是别人在引用了你的库之后，用代码提示的时候，只要看到 mls 开头的资源，就知道是你库里面的，不要用。但是这还不够，因为 Android Studio 还是会在人家写代码的时候把你的资源提示出来：

有没有一种办法，来让 library 开发者可以向 Android Studio 申明自己需要暴露哪些资源，而哪些不希望暴露呢？

当然是有的。我们可以在 library 的 res/values 下面建立一个 public.xml 文件：

    <!--向 Android Studio 声明我只希望暴露这个名称的 string 资源-->
    <public name="mls_hello" type="string" />

这样依赖，如果你在 app 里面试图引用 mls_world，Android Studio 就会警告你引用了一个 private 资源。

这个方法的详细介绍可以看官方文档：

developer.android.com/studio/proj…

但是不知道为什么，这个方法我在15、16年的时候还是有效的。但是升级到 Android Studio 3.3 + Gradle Plugin 3.1.3 之后我发现 IDE 不会再警告了，也可以通过编译，不知道这又是什么坑。但官方文档依旧没有去掉关于这个用法的描述，估计是插件的一个 bug 吧。

第三方依赖库

JCenter() 能引用到的，不要打包进你自己里面

本着“不要重复造轮子”的原则，我们在开发第三方库的时候，自身难免也会依赖一些第三方库。比如用于解析 json 的 Gson，或者用于加载图片的 Picasso。这些库本身都是 jar 文件的，所以之前会有一些第三方库的作者在用到这些库的时候，把对应的 jar 下载到 libs 下面参与编译，最终编译到自己的jar或者aar里面。而接入者的项目原可能已经依赖了这些库，一旦再接入了你的，就会导致错误，提示 duplicated class was found。

这种做法与 Gradle 的依赖管理机制完全是背道而驰的。正确的原则应该是：

只要第三方应用自己能从 JCenter/MavenCentral 获取到的库，如果你的库也依赖了，请一概使用 compileOnly

举个例子，比如我的库里面需要发起网络请求，按照 Google 的推荐，目前最好用的库应该是 Retrofit 了，这个时候我应该在 library 的 build.gradle 里这样写：

    compileOnly "com.squareup.retrofit2:retrofit:2.4.0"

compileOnly 标明后面的库只会在编译时有效，但不会你 library 的打包。这么一来，你只需要告诉你的引用者，让他们在自己 app 模块的 build.gradle 里加上引用即可，就像这样：

    implementation "com.squareup.retrofit2:retrofit:$versions.retrofit"

这样做的好处是，如果引用者的项目本来就已经依赖了 Retrofit，那么皆大欢喜，什么都不用加，并且上面的 $versions.retrofit 意味着引用者可以自己决定他要用哪个版本的 Retrofit，一般来讲只要大于等于你编译库时用的版本都不会有太大问题，除非 Retrofit 自己大量修改了 API 导致编不过的那种。这么一来就再一次把选择权交给了你的引用者，既不用担心冲突，也不用担心版本跟你用的不匹配。

使用单个文件统一依赖库的版本

如果你的项目分了好多模块，结构比较复杂，我这边推荐大家使用一个 versions.gradle 文件来统一所有模块依赖库的版本。这一招并不是我原创的，而是 Google 在 architecture-components 的官方 demo 里体现的。这个 demo 的 Project 包含了大量的 module，有 library 有 app，而所有的 module 都需要统一版本的依赖库，拿 buildToolsVersion 为例，总不能不能你依赖 27.1.1，我依赖 28.0.0 这样。我把链接放在下面，推荐大家都去学习一下这个文件的写法，以及它是如何去统一所有 module 的。

github.com/googlesampl…

API 设计

关于 API 设计，由于大家的库所要实现的功能不一样，所以没有办法具体列举，但是依然在这里为大家分享一些注意点，其实这些注意点只要能站在接入者的角度去考虑，大多数都能想到，而问题就在于你在写库的时候愿不愿意去为你的接入者多考虑一点。

不要在人家的 Application 类里蹦迪

相信暴露一个 init() 方法让你的调用者在 Application 类里做初始化，是很多库作者喜欢干的事。然而大家反过来想一下，我们都看过很多性能优化的文章，通常第一篇都是让大家检查一下自己的 Application 类，有没有做太多耗时的操作？因为 Application 是你应用起来之后第一个要走的，如果你在里面做了耗时操作了，势必会推迟 Activity 的加载，然而这一点却很容易被大家忽略。所以如果你是一个库的作者，请：

1. 不要在你的 init() 方法里做任何耗时操作
2. 更不要提供一个 init() 方法，让人家放在 Application 类里，还让人家“最好建议异步”，这跟耍流氓没区别

统一入口，用一个平台类去包含所有的功能

这里的平台类是我自己取的名字，你可以叫 XXXManager、XXXProxy、XXXService、XXXPlatform都可以，把它设计成单例，或者把内部所有的方法写成静态方法。不要让你的调用者费劲心思去找应该实例化哪个类，反正所有的方法都在这一个类里面，拿到实例之后调用对应的方法即可。这样统一入口，既降低了维护成本，你的调用者也会感谢你。

所有的常量，定义到一个类

if (code == 10012) {
    //do something
}

这个 10012 是什么？是你库里面定义的返回码？那为啥不写成常量暴露给你的调用者呢？

@Keep
class DemoResult private constructor(){

    @Keep
    companion object {
        /** * 支付失败，原因：无法连接网络，请检查网络设置 */
        const val CODE_ERROR_CONFIG_ERROR: Int = 10012
        const val MSG_ERROR_CONFIG_ERROR: String = "配置错误，请检查参数"
        
        ...
    }
}

这样一写，你的调用者只要点点鼠标，进来看一下你这个类，就能迅速把错误码跟错误提示对应上。懒一点的话，他们甚至可以直接用你定义的这些提示去展现给用户。而且万一有一天，服务端的同事告诉你，10012 需要变成别的值，此时你只需要修改你自己的代码就行，对库的接入者而言，它依然是 DemoResult.CODE_ERROR_CONFIG_ERROR ，不需要做任何修改，这样方便接入者的事何乐而不为呢？

帮助接入者检查传入参数的合法性

如果你的 API 对传入的参数有要求。建议在方法执行的第一步就对参数予以检查。一旦调用者传递的参数不合法，直接抛异常。有很多开发者觉得抛异常这种行为不能接受，因为毕竟这在 Android 平台的直接表现就是 app crash。但是于其让 app 在用户手里 crash，还不如直接在开发阶段 crash 掉让开发者立刻注意到并且予以修复。

这里以 String 的判空为例，如果你用 Kotlin 来开发，一切都简单多了。比如我现在有一个实体如下：

data class StudentInfo(val name: String)

一个 StudentInfo 是必须要有一个 name 的，并且我声明了 name 是不为空的。这个时候如果你在 Kotlin 里面实例化 Student 并且 name 传空，是直接编译不过的。而对于 Java 而言，Kotlin 帮我们生成的 class 文件也已经做好了这一点：

public StudentInfo(@NotNull String var1) {
      Intrinsics.checkParameterIsNotNull(var1, "name");
      super();
      this.name = var1;
   }

继续看 checkParameterIsNotNull() 方法：

public static void checkParameterIsNotNull(Object value, String paramName) {
        if (value == null) {
            throwParameterIsNullException(paramName);
        }
    }

throwParameterIsNullException()就是一个比较简单的抛异常了。

private static void throwParameterIsNullException(String paramName) {
        StackTraceElement[] stackTraceElements = Thread.currentThread().getStackTrace();

        // #0 Thread.getStackTrace()
        // #1 Intrinsics.throwParameterIsNullException
        // #2 Intrinsics.checkParameterIsNotNull
        // #3 our caller
        StackTraceElement caller = stackTraceElements[3];
        String className = caller.getClassName();
        String methodName = caller.getMethodName();

        IllegalArgumentException exception =
                new IllegalArgumentException("Parameter specified as non-null is null: " +
                                             "method " + className + "." + methodName +
                                             ", parameter " + paramName);
        throw sanitizeStackTrace(exception);
    }

所以即便你用的是 Java， 试图直接 Student student = new Student(null)，运行时也是会直接 crash 掉并且告诉你 name 不能为空的。联运 SDK 有大量的参数检查用了 Kotlin 的这一特性，使得我少些了很多代码，编译器编译后会自动帮我生成。

这里要推荐大家参考一下 android.support.v4.util.Preconditions ，这个里面封装好了大量的数据类型的情景检查，源码一看就明白。希望大家在写一个库的时候，都能做好传入参数合法性的检查工作，把问题发现在开发阶段，也能确保运行阶段不被意外值搞到奔溃。

一些遗憾

到这里，我基本上已经把这次 SDK 开发过程中的经验与踩过的坑都分享给大家了。当然了，这个世界上没有完美的事物，目前我们的联运 SDK 仍然有许多方面的不足，比如：

1. 没有发布到 mavenCentral()，需要开发者手动下载 aar 并添加进编译
2. SDK 需要依赖 Picasso 来完成图片加载，这部分功能应该抽象出来，由接入方去用他们自己的方案实现
3. 我们的 SDK 总共由 7 个 aar 组成，每个 aar 背后都有一个小团队来专门维护，开发者接入时需要全部复制到一个目录下，有些冗余跟臃肿

这些不足有些是因为项目初期没有考虑充分导致，有些是受限于项目架构上的原因导致的。接下来我们会逐一评估，争取把我们的 SDK 越做越好。同时也欢迎大家在评论区亮出自己在写 Android Library 时踩过的坑或者分享一些技巧，我会在后面逐步把它更新到文章里来，大家一起努力，造出更多规范的、优秀的轮子。