255.SDK （SDK开发）

1. SDK 开发的基本概念和思路

1.1 什么是 SDK
SDK（Software Development Kit）是一套供其他开发者调用的库或工具集合，在 Android 平台上开发 SDK 意味着将某种功能或通用模块（如日志、统计、支付、网络请求、图片加载等）封装成一个库，然后发布给其他项目使用。SDK 必须具备以下特点：
  • 接口清晰、使用简单：调用者能快速集成并使用，无需了解内部实现。
  • 高内聚低耦合：内部逻辑与外部接口应当分离，便于后续扩展和维护。
  • 稳定性：SDK 作为对外接口库，其稳定性和兼容性极为重要。
  • 文档完备：良好的文档可以帮助使用者快速上手，还能减少后期问题反馈。

1.2 为什么开发自己的 SDK
开发 SDK 的好处在于，当你有一套通用功能时，可以将其抽象成 SDK 来供多个项目复用。这样可以统一管理、维护和更新，同时还能对外展示你们架构设计的能力。以日志打印为例，传统方式每个项目都可能实现一套日志处理逻辑，而将其封装为 SDK，则能保证多个应用间的一致性和可控性。

1.3 开发自己的 SDK 的流程
整个开发流程大致包含以下几个步骤：
  ① 需求分析和接口设计：明确 SDK 要提供的功能和对应的 API 接口；
  ② 项目搭建：创建 Android 库项目，并配置 Gradle 构建系统；
  ③ 模块开发：完成 SDK 内部核心功能的代码实现；
  ④ 测试：编写单元测试或示例应用验证 SDK 的稳定性；
  ⑤ 打包与发布：将项目打包成 aar 或 jar 包，并上传到私服或 Maven 中央仓库；
  ⑥ 文档编写：撰写接口文档及使用示例，方便他人调用和集成。

────────────────────────────── 2. 架构设计和项目搭建

在开始真正编写代码前，首先要设计好 SDK 的整体架构。以一个日志打印 SDK 为例，我们需要考虑以下几个模块：

2.1 模块说明
  • 核心日志管理器：管理日志输出逻辑、日志级别控制等；
  • 配置管理：提供类似 init() 接口，允许调用者配置日志级别、输出位置、是否开启调试等；
  • 日志输出通道：支持输出到控制台（Logcat）、文件、甚至网络上报；
  • 接口定义：对外提供一系列简单易用的 API，保证调用者友好性；
  • 内部辅助工具：例如格式化、线程处理等。

2.2 建立项目
在 Android Studio 中新建一个 Android 库项目。可以这样进行创建：
  1）选择 "New Project" -> "Android Library" 模板；File -> New -> New Module，而不是直接选择 New Project。因为 "Android Library" 通常是作为模块添加，而不是直接创建一个独立的应用项目。
  2）填写库的名称（例如 MyLogSDK），选择 Kotlin 作为开发语言；
  3）配置 Gradle 的相关属性，如编译 SDK 版本、最低 SDK 版本。

项目创建后，你的项目结构大致如下：
  MyLogSDK
   – build.gradle (Library 模块)
   – src/main/AndroidManifest.xml
   – src/main/java/com/example/mylogsdk/...
   – src/main/res/values/strings.xml 等

build.gradle:

plugins {
    // 使用 Android Library 插件，适用于库模块
    id("com.android.library")
    // 使用 Kotlin Android 插件
    id("org.jetbrains.kotlin.android")
}

android {
    // 指定库模块的命名空间，通常与包名一致
    namespace = "com.example.mylogsdk"
    // 设置编译 SDK 版本
    compileSdk = 35

    defaultConfig {
        // 指定 Android 测试运行器
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
        // 配置 consumer Proguard 文件，用于对外暴露接口时保留需要的类
        consumerProguardFiles("consumer-rules.pro")
    }

    buildTypes {
        release {
            // 关闭混淆功能，如需开启则设置为 true
            isMinifyEnabled = false
            // 设置 ProGuard 混淆规则
            proguardFiles(
                // 使用 Android 默认的 ProGuard 文件（优化版本）
                getDefaultProguardFile("proguard-android-optimize.txt"),
                // 自定义的 ProGuard 规则文件
                "proguard-rules.pro"
            )
            // 在发布版本中也添加 consumer ProGuard 文件配置
            consumerProguardFiles("consumer-rules.pro")
        }
    }

    compileOptions {
        // 指定 Java 编译的版本
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }

    kotlinOptions {
        // 设置 Kotlin 的 JVM 目标版本
        jvmTarget = "11"
    }
}

dependencies {
    // Kotlin 标准库的依赖
    implementation("org.jetbrains.kotlin:kotlin-stdlib:1.7.21")

    // AndroidX 相关依赖
    // 核心扩展库
    implementation(libs.androidx.core.ktx)
    // AppCompat 支持库，用于向后兼容旧版本 Android
    implementation(libs.androidx.appcompat)
    // Material Design 组件库
    implementation(libs.material)
    // Activity 组件库
    implementation(libs.androidx.activity)
    // 布局约束库，用于复杂布局设计
    implementation(libs.androidx.constraintlayout)

    // 测试相关依赖
    // JUnit 测试框架
    testImplementation(libs.junit)
    // AndroidX JUnit 扩展依赖
    androidTestImplementation(libs.androidx.junit)
    // Espresso 测试库，用于 UI 测试
    androidTestImplementation(libs.androidx.espresso.core)
}

────────────────────────────── 3. 接口设计与核心模块实现

3.1 接口设计
一个好的 SDK 要求对外接口简单明了。我们这里以日志输出为例，设计对外暴露的 API 函数，例如：
  • init()：初始化 SDK 参数，例如日志开关、日志级别、输出路径；
  • d()/e()/i()/w()：分别输出 debug、error、info、warn 等级别的日志；
  • setLogLevel()：动态修改日志等级。

设计原则：
  • 接口函数命名尽量贴近 Android Log 函数，降低使用难度；
  • 日志调用操作低耦合，内部管理流程隐藏复杂逻辑；
  • 保持线程安全，避免多线程调用时出错。

3.2 核心日志管理器实现
我们来实现一个简单的日志管理器（LogManager），用于接收外部调用，并依次触发日志输出。下面是一个示例：

package com.example.mylogsdk

import android.util.Log
import com.google.firebase.dataconnect.LogLevel

/**
 * LogManager 是 MyLogSDK 的核心类，提供对外日志打印接口
 */
object LogManager {
    // 日志开关
    private var debugEnabled = true

    // 设定的日志级别
    /*
    LogLevel 通常是一个枚举类（enum），用于定义不同的日志级别，例如 DEBUG、INFO、WARN、ERROR 等。
    不同的日志级别表示日志的重要性程度。例如：
    DEBUG：调试级别日志，通常用于开发和调试时输出详细信息。
    INFO：信息级别日志，表示正常运行的信息。
    WARN：警告级别日志，表示潜在问题或非正常行为。
    ERROR：错误级别日志，表示严重问题。
     */
    private var currentLogLevel = LogLevel.DEBUG

    // 初始化SDK，可以允许外部配置
    fun init(debug: Boolean, logLevel: LogLevel) {
        debugEnabled = debug
        currentLogLevel = logLevel
    }

    // 设定日志级别
    fun setLogLevel(level: LogLevel) {
        currentLogLevel = level
    }

    // 输出 debug 日志
    /*
    如果当前日志级别（currentLogLevel）的优先级低于或等于 DEBUG，则返回 true，表示满足条件，可以执行某些操作（比如输出日志）。
    如果当前日志级别（currentLogLevel）的优先级高于 DEBUG，则返回 false，表示不需要执行操作。
     */
    fun d(tag: String, message: String) {
        if (!debugEnabled) return
        if (currentLogLevel.ordinal <= LogLevel.DEBUG.ordinal) {
            Log.d(tag, message)
        }
    }

    // 输出 info 日志
    fun i(tag: String, message: String) {
        if (!debugEnabled) return
        if (currentLogLevel.ordinal <= LogLevel.INFO.ordinal) {
            Log.i(tag, message)
        }
    }

    // 输出 warn 日志
    fun w(tag: String, message: String) {
        if (!debugEnabled) return
        if (currentLogLevel.ordinal <= LogLevel.WARN.ordinal) {
            Log.w(tag, message)
        }
    }

    // 输出 error 日志
    fun e(tag: String, message: String) {
        if (!debugEnabled) return
        if (currentLogLevel.ordinal <= LogLevel.ERROR.ordinal) {
            Log.e(tag, message)
        }
    }
}

这里我们用到了一个日志级别枚举，说明不同级别的顺序关系。下面给出枚举的实现：

package com.example.mylogsdk

/**
 * 用于标识日志输出等级，数字越小代表输出的越详细
 */
/*
enum 是 枚举（enumeration） 的缩写，是一种特殊的数据类型，用于定义一组固定的常量值
在 Kotlin 中，enum 被用来表示一组有限的、明确的值集合。
 */
enum class LogLevel {
    DEBUG, INFO, WARN, ERROR;
}

3.3 提供简单使用接口
为了方便使用者调用日志模块，我们可以提供一个入口类 MyLog，可以将 LogManager 封装进去。这样使用者只需要引用 MyLog 类下的方法即可。

package com.example.mylogsdk

/**
 * MyLog 封装了 LogManager 的相关功能，对外提供可直接使用的 API
 */
object MyLog {
    fun init(debug: Boolean = true, logLevel: LogLevel = LogLevel.DEBUG) {
        LogManager.init(debug, logLevel)
    }

    fun setLogLevel(level: LogLevel) {
        LogManager.setLogLevel(level)
    }

    fun d(tag: String, message: String) {
        LogManager.d(tag, message)
    }

    fun i(tag: String, message: String) {
        LogManager.i(tag, message)
    }

    fun w(tag: String, message: String) {
        LogManager.w(tag, message)
    }

    fun e(tag: String, message: String) {
        LogManager.e(tag, message)
    }
}

这样，一套简单的日志 SDK 的核心代码就完成了。使用者在项目中引用 SDK 后，只需要调用 MyLog.init() 来初始化，然后在需要的位置直接调用 MyLog.d()/MyLog.e() 等函数。

────────────────────────────── 5. SDK 测试与示例应用

为了确保你的 SDK 工作正常，我们推荐同时开发一个示例应用让其他开发者明白如何使用你的 SDK。这一般称为 "sample" 模块，集成你的 SDK 作为依赖，然后利用简单的界面展示使用方法。

示例应用步骤如下：

5.1 单独创建一个 Android 应用项目，将你的 SDK 包含为依赖（例如通过 Gradle 的 project 引用）。

在示例应用的 module-level build.gradle 文件中，添加如下依赖（假设 SDK 模块名称为 mylogsdk）：

dependencies {
    implementation project(":mylogsdk")
    // 其他依赖
}

5.2 编写一个简单的 Activity，在 onCreate() 中调用 SDK 的函数。

package com.example.sampleapp

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.example.mylogsdk.MyLog
import com.example.mylogsdk.LogLevel

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 通常会使用 setContentView 设置布局，这里为了简单就不做复杂布局演示
        MyLog.init(debug = true, logLevel = LogLevel.DEBUG)
        MyLog.d("MainActivity", "这是一个调试日志")
        MyLog.i("MainActivity", "这是一条信息日志")
        MyLog.w("MainActivity", "这是一条警告日志")
        MyLog.e("MainActivity", "这是一条错误日志")
    }
}

这样，当你运行示例应用后，可以在 Logcat 中看到你的 SDK 输出的信息，并验证日志格式是否符合预期。

────────────────────────────── 6. SDK 打包与发布

当你的 SDK 开发完成后，下一步就是打包成 aar（Android Archive）包，然后发布给外部使用者。

6.1 打包 aar 包
在 Android Studio 中，选择菜单 Build -> Make Project，然后通过命令行调用 Gradle task：
  ./gradlew assembleRelease
执行完毕后，生成的 aar 包会位于 build/outputs/aar 目录下。

6.2 发布到 Maven 仓库
如果你打算发布到 MavenCentral 或私有仓库，需要在 build.gradle 中增加相应的发布插件配置。常用的有 maven-publish 插件。例如：

apply plugin: 'maven-publish'

publishing {
    publications {
        release(MavenPublication) {
            groupId 'com.example'
            artifactId 'mylogsdk'
            version '1.0.0'
            artifact("$buildDir/outputs/aar/mylogsdk-release.aar")
        }
    }
    repositories {
        maven {
            url = "https://your.maven.repo/url"
            credentials {
                username = project.findProperty("repoUser") ?: ""
                password = project.findProperty("repoPassword") ?: ""
            }
        }
    }
}

根据需要，完成项目发布时的签名、版本管理等流程。
如果是对外分享，也可以直接提供 aar 包给使用者。

────────────────────────────── 7. 编写文档与示例代码

一个成熟的 SDK 必须配套完善的文档，以便使用者能快速上手。文档可以采用 Markdown 格式编写，内容应包括：

  • SDK 介绍与功能概述
  • 快速集成指南：如何添加依赖、如何调用接口
  • 接口详细说明：每个方法的参数、返回值、异常说明；
  • 使用示例代码：展示典型的调用方式
  • FAQ 与注意事项

你可以提供一个 README.md 文件，下面是一个简单示例：

# MyLogSDK

MyLogSDK 是一个简单的日志输出 SDK，支持多等级日志、格式化输出及多种日志输出途径。

## 快速开始

1. 在你的项目根目录下的 settings.gradle 中添加：
```gradle
include ':mylogsdk'
```

2. 在 app 模块的 build.gradle 中添加依赖：
```gradle
implementation project(":mylogsdk")
```

3. 初始化 SDK：
```kotlin
MyLog.init(debug = true, logLevel = LogLevel.DEBUG)
```

4. 输出日志：
```kotlin
MyLog.d("MainActivity", "调试日志")
MyLog.i("MainActivity", "信息日志")
MyLog.w("MainActivity", "警告日志")
MyLog.e("MainActivity", "错误日志")
```

## 接口说明

- `MyLog.init(debug: Boolean, logLevel: LogLevel)`：初始化 SDK，设置是否开启调试及默认日志级别。
- `MyLog.setLogLevel(level: LogLevel)`：动态修改日志等级。
- `MyLog.d(tag: String, message: String)`：输出 debug 日志，其他日志方法类似。

## 注意事项

- 在正式发布时，请关闭日志输出或切换到较高日志级别
- 如果需要扩展其他输出方式，请实现 `ILogOutput` 接口，然后注册到 LogManager 中。

## 示例工程

请参考 sample 文件夹内提供的示例工程，查看完整的使用方式。