三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

Android SDK开发与打包全流程：从设计到发布的工程实践

发布时间：2026/8/15 11:38:10 三亩地 编程学习日记
Android SDK开发与打包全流程：从设计到发布的工程实践

1. 项目概述：从使用者到创造者的视角转变

作为一名Android开发者，我们每天都在与各种SDK打交道，从Google官方的Support库、Play Services，到各大厂商的支付、推送、地图SDK。我们熟练地在build.gradle文件中添加一行implementation或api依赖，然后调用其提供的API，这似乎就是SDK的全部。但你是否想过，这些能直接集成、稳定运行的.aar或.jar文件，究竟是如何从一行行代码变成我们手中的“黑盒”工具的？这个从“使用者”到“创造者”的视角转变，正是理解Android SDK开发与打包的核心。它不仅仅是技术实现，更关乎工程规范、兼容性设计和商业交付的完整链条。

开发一个Android SDK，远非简单地将几个类文件打个包那么简单。它意味着你需要考虑最小化侵入性（如何让接入方几乎无感集成）、最大化兼容性（从Android 5.0到最新的Android版本，从ARM到x86）、清晰的API设计（如何让开发者一眼看懂、不易误用）以及稳定的依赖管理（如何避免与宿主App的依赖冲突）。而最终交付物——.aar（Android Archive）或.jar（Java Archive）包，则是这一切设计思想的物理封装。理解如何开发并打包它们，不仅能让你更好地使用第三方SDK，更能让你在需要对外提供能力时（比如公司内部组件化、对外提供开放平台服务），构建出专业、可靠的交付件。接下来，我将结合多年的一线开发与SDK维护经验，拆解这背后的完整流程与核心细节。

2. SDK开发的核心设计思路与工程规范

在动手写第一行代码之前，正确的设计思路比技术实现更重要。一个糟糕的SDK设计，会让接入方开发者痛苦不堪，最终导致你的SDK无人问津。

2.1 明确SDK的边界与职责

首先，你必须像产品经理一样定义你的SDK。它到底提供什么核心能力？是一个完整的支付流程？一个图像滤镜处理库？还是一个网络请求框架？职责单一且明确是首要原则。避免打造一个“瑞士军刀”式的巨型SDK，这会给接入方带来不必要的体积膨胀和潜在的冲突。例如，一个推送SDK就应该专注于消息的接收、展示和点击上报，而不应该内置一个自己的图片加载库。

在定义清楚后，你需要规划公开API（Public API）与内部实现（Internal Implementation）的严格界限。公开API是SDK与外界通信的唯一契约，必须保持极致的稳定性和向后兼容性。一旦发布，任何对Public API的修改（如删除方法、修改签名）都可能造成接入方应用崩溃。内部实现类则应使用internal（Kotlin）或包级私有（Java）进行隐藏，或者通过@Hide注解（对于Android系统API风格）来避免被外部直接调用。

2.2 依赖管理的艺术：避免“依赖地狱”

这是SDK开发中最容易踩坑的地方。你的SDK应该尽可能轻量化，减少对外部库的直接依赖。如果必须依赖，比如需要使用Gson进行JSON解析，或者OkHttp进行网络请求，你需要仔细评估：

  1. 使用api还是implementation？这是Gradle依赖配置的关键区别。

    • api（旧称compile）：将依赖项“传递”暴露给SDK的使用者。如果你在SDK的Public API中直接使用了Gson类作为参数或返回值，那么你必须使用api。但这意味着，如果接入方App也依赖了不同版本的Gson，就可能发生冲突。
    • implementation：将依赖项完全封装在SDK内部。外部App无法直接访问到这个依赖。这是首选方式。为了实现这一点，你需要在SDK内部对外部库的功能做一层接口隔离。例如，不直接返回com.google.gson.JsonObject，而是返回一个SDK自定义的JsonObject接口，内部用Gson实现。这样，SDK的build.gradle中对Gson的依赖就可以声明为implementation，完美避免了传递性依赖冲突。

  2. 处理版本冲突：即使你用了implementation，如果接入方也用了相同的库（比如OkHttp），Gradle在构建App时依然会选择同一个版本。如果版本不兼容，可能导致运行时错误。一种进阶做法是，将关键依赖（如网络库、图片库）的类进行重打包（Shading/Relocation）。使用Maven的maven-shade-plugin或Gradle的shadow插件，可以将okhttp3这个包名在打包时重命名为com.yourcompany.sdk.internal.okhttp3，从而彻底避免类路径冲突。但这会增加包体积和复杂度，需权衡使用。

2.3 资源与配置的隔离

Android SDK经常需要包含资源文件（布局、图片、字符串等）和AndroidManifest.xml组件声明。.aar包的优势就在于它能包含这些Android特有的资源。

  • 资源命名：务必为你的所有资源（drawable、layout、string等）添加唯一前缀，例如sdk_。避免使用ic_launcher、title这种通用名称，否则会与宿主App的资源发生合并冲突，导致资源找不到或被覆盖。
  • Manifest合并：SDK中的AndroidManifest.xml在构建时会被合并到主App的Manifest中。你需要特别注意<application>标签下的属性（如android:theme、android:name）和组件声明（<activity>、<service>）。SDK中的Manifest不应设置android:theme或指定Application类，除非这是SDK的核心功能要求。对于组件，使用tools:replace或tools:ignore属性来处理可能的冲突。

3. 构建与打包：Gradle的魔法

现代Android SDK开发几乎完全基于Gradle。理解如何配置Gradle脚本来生成不同的发布包，是打包阶段的核心。

3.1 工程结构：Library Module是关键

你不需要一个独立的Android应用工程。在Android Studio中，直接创建一个新的Android LibraryModule。这个Module的类型决定了它可以编译生成.aar文件。与之相对的是ApplicationModule，生成的是.apk。

你的SDK代码、资源、Manifest都放在这个Library Module中。一个典型的SDK项目可能包含多个Library Module，通过api或implementation相互依赖，最终由一个主Library Module对外暴露统一API，并打包输出。

3.2 编写构建脚本：build.gradle.kts(Kotlin DSL) 详解

以下是SDK Library Module的build.gradle.kts文件核心配置解析：

plugins { id("com.android.library") // 关键：声明这是一个Android库 id("org.jetbrains.kotlin.android") // 如果用Kotlin // id("maven-publish") // 用于发布到Maven仓库 } android { namespace = "com.yourcompany.awesome.sdk" compileSdk = 34 // 编译SDK版本，建议与支持的最低版本保持合理跨度 defaultConfig { minSdk = 21 // 最小支持SDK版本，决定了你的SDK能覆盖多少设备 targetSdk = 34 // 目标SDK版本，应设置为最新的稳定版，以确保在新系统上的兼容性 testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" consumerProguardFiles("consumer-rules.pro") // 关键！为接入方提供混淆规则 } buildTypes { release { isMinifyEnabled = true // SDK自身代码是否混淆 proguardFiles( getDefaultProguardFile("proguard-android-optimize.txt"), "consumer-rules.pro" // 这里配置的是SDK自身的混淆规则 ) } debug { isMinifyEnabled = false } } // 关键配置：避免将某些依赖打包进AAR configurations { create("embedded") // 自定义一个配置项，用于存放需要“嵌入”的依赖 } // 指定Java版本 compileOptions { sourceCompatibility = JavaVersion.VERSION_1_8 targetCompatibility = JavaVersion.VERSION_1_8 } kotlinOptions { jvmTarget = "1.8" } // 可选：构建变体，例如区分免费版和付费版SDK flavorDimensions += "tier" productFlavors { create("free") { dimension = "tier" // 可以在这里定义不同的BuildConfig字段或资源 buildConfigField("String", "SDK_TIER", "\"FREE\"") } create("premium") { dimension = "tier" buildConfigField("String", "SDK_TIER", "\"PREMIUM\"") } } } dependencies { // 公开API依赖，会传递给使用者 api("androidx.core:core-ktx:1.12.0") // 内部实现依赖，不会传递 implementation("com.squareup.okhttp3:okhttp:4.12.0") implementation("com.google.code.gson:gson:2.10.1") // 测试依赖 testImplementation("junit:junit:4.13.2") androidTestImplementation("androidx.test.ext:junit:1.1.5") }

关键点解析：

  • consumerProguardFiles：这是SDK开发中极其重要但常被忽略的一环。你提供的SDK代码很可能被接入方App进行混淆。如果你的SDK中某些类、方法需要被外部通过反射调用（比如序列化框架、路由框架），这些元素一旦被接入方混淆，就会导致功能失效。consumer-rules.pro文件就是用来告诉接入方的ProGuard：“请保留我这些指定的类和成员，不要混淆它们”。例如，在里面加上-keep class com.yourcompany.sdk.model.** { *; }。
  • isMinifyEnabled：SDK自身的混淆。开启后能减小AAR包中代码的体积，并增加一定的反编译难度。但务必确保你的proguard-rules.pro（SDK自身的混淆规则）配置正确，不要混淆了需要公开的API。

3.3 生成AAR与JAR包

配置好Gradle后，打包过程就变得非常简单。

生成AAR包：

  1. 在Android Studio右侧的Gradle面板中，找到你的Library Module。
  2. 展开Tasks->build。
  3. 双击执行assembleRelease（或assembleFreeRelease等带变体的任务）。
  4. 构建完成后，AAR文件会生成在module目录/build/outputs/aar/下，命名格式通常为module名-flavor-buildtype.aar，例如awesome-sdk-free-release.aar。

这个AAR文件是一个标准的ZIP压缩包，你可以用解压软件打开它，里面包含了：

  • classes.jar：编译后的Java字节码。
  • res/：所有资源文件。
  • AndroidManifest.xml。
  • R.txt：资源映射表。
  • jni/：如果有原生库（.so文件），会在这里。
  • assets/：资产文件。
  • libs/：依赖的第三方JAR包（如果依赖项是implementation且未嵌入，部分依赖的JAR可能会出现在这里，但现代Gradle通常将依赖放在POM文件中声明，而非直接打包JAR）。

生成纯JAR包：有时，你的SDK是纯Java/Kotlin逻辑，不包含任何Android资源或组件，或者你需要提供一个轻量级的JAR给非Android项目（如后端）使用。这时你需要生成一个不包含Android资源的JAR。

  1. 在build.gradle.kts中添加一个自定义任务：
tasks.register<Jar>("sourcesJar") { archiveClassifier.set("sources") from(android.sourceSets["main"].java.srcDirs) } tasks.register<Jar>("javadocJar") { archiveClassifier.set("javadoc") from(tasks.named("dokkaHtml")) // 如果用Dokka生成文档 } // 核心：生成纯类JAR的任务 tasks.register<Jar>("generateReleaseJar") { archiveBaseName.set("awesome-sdk-core") archiveVersion.set(project.version.toString()) // 从编译输出的classes.jar中获取内容 from(zipTree(tasks.named("bundleReleaseAar").get().outputs.files.singleFile).matching { include("classes.jar") }) // 如果你需要将某些implementation依赖也打包进去（即生成fat jar），需要额外处理 // 但这通常不推荐，容易引起冲突。推荐使用`shadow`插件进行重打包。 dependsOn(tasks.named("bundleReleaseAar")) }
  1. 执行这个自定义任务generateReleaseJar，即可在build/libs/目录下得到纯JAR包。

注意：直接打包包含Android特定类（如Activity、Context）的JAR给纯Java项目用，会因为缺少Android运行时环境而无法使用。这种JAR通常用于代码共享，而非运行时。

4. 发布与集成：让开发者顺畅使用

打包出AAR/JAR只是第一步，如何交付给开发者并让他们方便地集成，是下一个关键环节。

4.1 本地集成：直接使用AAR文件

对于小范围测试或内部使用，最直接的方式是提供AAR文件。

  1. 将生成的.aar文件（如awesome-sdk-release.aar）复制到宿主App项目的libs目录下（通常在app模块下创建该目录）。
  2. 在App模块的build.gradle.kts中添加依赖：
dependencies { implementation(files("libs/awesome-sdk-release.aar")) }
  1. 同步Gradle即可。

踩坑点：如果SDK的AAR内部还依赖了其他第三方库（并且是以implementation方式依赖），这些依赖不会被自动传递。你需要在宿主App的build.gradle中手动声明这些依赖，否则会在运行时抛出ClassNotFoundException。这就是为什么前面强调要尽量减少SDK的传递性依赖，或者做好接口隔离。

4.2 远程仓库集成：专业之选

对于公开或公司内部的SDK，发布到Maven仓库是标准做法。开发者只需像集成其他开源库一样，添加一行依赖声明即可。

发布到本地Maven仓库（用于测试）：在SDK项目的根build.gradle.kts或模块build.gradle.kts中添加：

plugins { // ... 其他插件 `maven-publish` } afterEvaluate { publishing { publications { create<MavenPublication>("release") { // 指定要发布的组件，这里是Android库的release变体 from(components["release"]) // 配置Maven坐标 groupId = "com.yourcompany" artifactId = "awesome-sdk" version = "1.0.0" // 可选：附带源码包和文档包 artifact(tasks.named("sourcesJar").get()) artifact(tasks.named("javadocJar").get()) } } // 发布到本地目录 repositories { maven { url = uri("${project.buildDir}/repo") } } } }

执行publishReleasePublicationToMavenRepository任务，SDK的AAR、POM文件等就会被发布到build/repo目录。然后，在宿主App的根settings.gradle.kts中声明这个本地仓库：

dependencyResolutionManagement { repositories { mavenLocal() // 本地~/.m2仓库 maven { url = uri("file:///path/to/your/sdk-project/build/repo") } // 指定路径 google() mavenCentral() } }

之后就可以在App的dependencies中用implementation("com.yourcompany:awesome-sdk:1.0.0")来引用了。

发布到私有或公共仓库：流程类似，只需将publishing.repositories中的url改为你的私有Maven仓库地址（如Nexus、Artifactory），并配置相应的认证信息即可。发布到Maven Central或Google Maven仓库流程更复杂，需要注册账号、签名等，此处不展开。

5. 高级主题与避坑指南

5.1 混淆与代码保护

  • SDK自身混淆：在build.gradle的release构建类型中开启minifyEnabled true，并配置好proguard-rules.pro。切记保留所有Public API！一个简单的规则是保留所有public类和方法：-keep public class com.yourcompany.sdk.** { public *; }。更精细的控制可以配合@Keep注解。
  • 为接入方提供混淆规则（consumer-rules.pro）：这是责任所在。必须仔细分析SDK中哪些类、方法、字段可能被反射、序列化或JNI调用，并为之添加-keep规则。例如，所有数据模型（Model/Entity）类、继承自Parcelable的类、通过@SerializedName注解的字段等，都需要保留。

5.2 兼容性测试

SDK的兼容性挑战巨大。你需要建立一个设备矩阵进行测试，至少覆盖：

  • 系统版本：从minSdk到最新版，重点关注碎片化严重的版本（如Android 5.x, 6.x, 7.x, 8.x, 9, 10, 11+）。
  • 厂商ROM：华为（无GMS）、小米、OPPO、vivo、三星等主流厂商的系统，它们的后台管理、权限机制、通知渠道可能有定制，会影响SDK的保活、推送等功能。
  • CPU架构：如果包含JNI库（.so文件），务必在build.gradle中配置ndk { abiFilters "armeabi-v7a", "arm64-v8a", "x86", "x86_64" }，并在打包时生成全架构的AAR，或使用android.splits.abi来生成多个APK（对SDK来说，通常打包全架构）。

5.3 版本管理与向后兼容

  • 语义化版本（SemVer）：严格遵守主版本号.次版本号.修订号的规则。
    • 修订号递增：当你做了向下兼容的问题修正。
    • 次版本号递增：当你做了向下兼容的功能性新增。
    • 主版本号递增：当你做了不向下兼容的API变更。
  • 废弃（Deprecation）策略：当需要删除或修改一个Public API时，不要直接删除。先使用@Deprecated注解标记旧API，并在文档中说明替代方案。保留至少1-2个次要版本周期，给开发者迁移的时间，然后在下一个主版本中移除。

5.4 常见问题排查（FAQ）

  1. 集成后编译报错：Program type already present: com.xxx.xxx

    • 原因：最常见的依赖冲突。你的SDK和宿主App引入了同一个库的不同版本，或者两个不同的库包含了全限定名相同的类。
    • 排查：在宿主App执行./gradlew :app:dependencies查看依赖树。使用exclude排除冲突的模块，或强制指定统一版本。
    • 根治：SDK侧应尽可能使用implementation依赖，并对关键依赖进行接口隔离或重打包。

  2. 运行时崩溃：java.lang.NoClassDefFoundError或java.lang.NoSuchMethodError

    • 原因：类或方法在运行时找不到。可能是ProGuard混淆过度删除了必要的类；也可能是编译时和运行时使用的依赖版本不一致（常见于NoSuchMethodError）。
    • 排查：检查SDK提供的consumer-rules.pro是否完备。检查宿主App的依赖版本是否与SDK编译时使用的版本兼容。

  3. 资源找不到：android.content.res.Resources$NotFoundException

    • 原因：SDK中的资源ID与宿主App冲突，导致合并后资源被覆盖或分配了错误的ID。
    • 解决：确保SDK内所有资源名称都使用了唯一前缀。检查资源合并日志（在构建时添加--info或--debug标志）。

  4. AAR包中的依赖没有自动引入

    • 原因：AAR文件本身不包含传递性依赖信息。依赖信息记录在同时生成的.pom（Project Object Model）文件中。当通过Maven仓库集成时，Gradle会读取POM文件自动下载传递依赖。但直接使用本地AAR文件时，POM文件不存在，依赖不会自动引入。
    • 解决：要么发布到Maven仓库；要么在提供AAR文件时，明确列出所有必须的第三方依赖及其版本，要求接入方手动添加。

开发一个高质量的Android SDK是一项系统工程，它考验的不仅是编码能力，更是架构设计、生态思维和开发者体验的全面理解。从清晰的API设计开始，到严谨的依赖管理、完善的打包发布，再到周到的兼容性测试和版本维护，每一步都需要精心考量。

编程学习 学习日记 实战经验
← 返回列表