SDK 设计核心关注
一、总览架构
┌──────────────────────────────────────────────────────────────────┐
│ SDK 设计关注维度 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ API 设计 │ │ 稳定性 │ │ 性能 │ │ 安全性 │ │
│ │ │ │ │ │ │ │ │ │
│ │ 易用性 │ │ 兼容性 │ │ 包体积 │ │ 隐私合规 │ │
│ │ 一致性 │ │ 容错 │ │ 内存 │ │ 数据安全 │ │
│ │ 可扩展 │ │ 隔离 │ │ 电量 │ │ 权限最小化│ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 集成体验 │ │ 可观测性 │ │ 测试 │ │ 发布维护 │ │
│ │ │ │ │ │ │ │ │ │
│ │ 文档 │ │ 日志 │ │ 单元测试 │ │ 版本管理 │ │
│ │ 初始化 │ │ 监控 │ │ 集成测试 │ │ 灰度发布 │ │
│ │ 示例代码 │ │ 调试支持 │ │ Mock │ │ 向后兼容 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────────────────────────────────────────────────┘
二、API 设计（最核心）
1. 易用性 --- 让接入方 5 分钟上手
// ✅ 好的 API: 简洁、符合直觉
// 最简使用只需一行
MySdk.init(context)
// 常见功能两三行
MySdk.track("purchase", mapOf("price" to 99.9))
// 高级用法链式配置
MySdk.builder(context)
.setAppKey("xxx")
.setDebug(BuildConfig.DEBUG)
.enableFeatureX()
.build()
// ❌ 坏的 API: 暴露过多概念
val config = MySdkConfig()
config.appKey = "xxx"
config.env = MySdkEnv.PROD
val transport = MySdkHttpTransport(OkHttpClient())
val serializer = MySdkJsonSerializer(GsonFactory.create())
val dispatcher = MySdkEventDispatcher(transport, serializer)
val engine = MySdkEngine(config, dispatcher)
engine.initialize(context)
engine.start()
// 接入方: "我只想打个点,为什么要了解这么多?"
2. 一致性 --- 统一的设计范式
// ✅ 命名一致
sdk.startTracking()
sdk.stopTracking()
sdk.isTracking() // is 前缀表示布尔
sdk.addListener(listener)
sdk.removeListener(listener)
sdk.clearListeners() // add/remove/clear 一套
// ✅ 参数风格一致
// 全部用 Builder 模式, 或全部用 DSL, 不要混搭
// Builder:
Request.Builder()
.url("...")
.header("key", "value")
.build()
// DSL:
request {
url = "..."
header("key", "value")
}
// ❌ 不一致的设计
sdk.init(key: String, secret: String, env: Int) // 参数列表
sdk.configure(Config.Builder().build()) // Builder
sdk.setOptions { it.timeout = 30 } // DSL
// 三种风格混在一起
3. 最少知识原则 --- 隐藏内部实现
┌──────────────────────────────────────────────────────────────┐
│ SDK 分层架构 │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Public API Layer (公开层) │ │
│ │ │ │
│ │ MySdk (入口) │ │
│ │ MySdkConfig (配置) │ │
│ │ EventListener (回调接口) │ │
│ │ Result<T> (返回类型) │ │
│ │ │ │
│ │ ← 接入方只需关心这一层 │ │
│ ├────────────────────────────────────────────────────────┤ │
│ │ Internal Layer (内部层, @RestrictTo / internal) │ │
│ │ │ │
│ │ EventDispatcher / EventQueue │ │
│ │ NetworkClient / CacheManager │ │
│ │ Serializer / Scheduler │ │
│ │ DatabaseHelper / FileStorage │ │
│ │ │ │
│ │ ← 内部实现, 对接入方不可见 │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ 可见性控制: │
│ Kotlin: internal 关键字 (模块内可见) │
│ Java: @RestrictTo(LIBRARY) + ProGuard 混淆 │
│ 包名: com.sdk.public / com.sdk.internal │
└──────────────────────────────────────────────────────────────┘
// ✅ 严格控制公开 API
// 公开接口
public interface MySdk {
fun track(event: String, params: Map<String, Any> = emptyMap())
fun setUserId(id: String)
fun flush()
companion object {
fun init(context: Context, config: Config = Config.default()): MySdk
}
}
// 内部实现 (接入方看不到)
internal class MySdkImpl(
private val context: Context,
private val config: Config
) : MySdk {
// 内部的线程池、缓存、网络请求等全部 internal
internal val eventQueue = EventQueue()
internal val networkClient = NetworkClient()
// ...
}
// ✅ 返回接口而非实现类
fun init(): MySdk // 返回接口
// ❌ 不要
fun init(): MySdkImpl // 暴露了实现类
4. 可扩展性 --- 预留扩展点
// ✅ 策略接口: 允许接入方自定义行为
interface MySdkConfig {
// 自定义网络层 (默认用内置的, 也可以用 OkHttp)
var httpClient: HttpClient?
// 自定义序列化 (默认 JSON, 也可以用 Protobuf)
var serializer: Serializer?
// 自定义日志
var logger: Logger?
// 自定义持久化
var storage: Storage?
// 拦截器 (请求/响应拦截)
fun addInterceptor(interceptor: Interceptor)
}
// 接入方可以替换任何组件
MySdk.init(context) {
httpClient = OkHttpClientAdapter(myOkHttpClient)
logger = TimberLogger()
addInterceptor(AuthInterceptor(tokenProvider))
}
5. 回调设计
// ✅ 提供多种回调方式, 适应不同项目
// 方式1: 接口回调 (Java 友好)
interface OnResultListener {
fun onSuccess(data: Data)
fun onError(error: SdkError)
}
sdk.fetch(listener)
// 方式2: Lambda (Kotlin 友好)
sdk.fetch(
onSuccess = { data -> },
onError = { error -> }
)
// 方式3: 挂起函数 (协程友好)
suspend fun fetch(): Result<Data>
// 方式4: Flow (响应式)
fun observeState(): Flow<State>
// 方式5: LiveData (Android 生命周期感知)
fun observeState(): LiveData<State>
// ✅ 好的实践: 内部用协程/Flow, 对外暴露多种适配
// 核心实现
internal suspend fun fetchInternal(): Data { ... }
// 适配层
fun fetch(listener: OnResultListener) {
scope.launch {
try {
val data = fetchInternal()
mainHandler.post { listener.onSuccess(data) }
} catch (e: Exception) {
mainHandler.post { listener.onError(e.toSdkError()) }
}
}
}
suspend fun fetchSuspend(): Result<Data> = runCatching { fetchInternal() }
fun fetchFlow(): Flow<Data> = flow { emit(fetchInternal()) }
6. 错误设计
// ✅ 定义清晰的错误体系
sealed class SdkError(
val code: Int,
override val message: String,
override val cause: Throwable? = null
) : Exception(message, cause) {
// 初始化错误
class NotInitialized : SdkError(1001, "SDK 未初始化, 请先调用 init()")
class InvalidConfig(detail: String) : SdkError(1002, "配置无效: $detail")
// 网络错误
class NetworkError(cause: Throwable) :
SdkError(2001, "网络请求失败", cause)
class ServerError(val httpCode: Int, body: String) :
SdkError(2002, "服务端错误: $httpCode - $body")
class Timeout : SdkError(2003, "请求超时")
// 业务错误
class AuthFailed : SdkError(3001, "鉴权失败")
class RateLimited(val retryAfterMs: Long) :
SdkError(3002, "请求过于频繁, ${retryAfterMs}ms 后重试")
// 未知错误
class Unknown(cause: Throwable) :
SdkError(9999, "未知错误: ${cause.message}", cause)
}
// ✅ 提供错误码文档
// ✅ 错误信息要有指导性 (告诉用户怎么解决)
// ❌ 不要只说 "Error occurred" 这种废话
三、稳定性
1. 容错 --- SDK 不能让宿主 App 崩溃
// ✅ 核心原则: SDK 的任何异常都不能影响宿主 App!
// 内部异常兜底
internal object SafeExecutor {
private val handler = CoroutineExceptionHandler { _, throwable ->
SdkLogger.e("SDK 内部异常, 已兜底", throwable)
// 上报但不崩溃
ErrorReporter.report(throwable)
}
val scope = CoroutineScope(
SupervisorJob() + Dispatchers.Default + handler
)
fun execute(block: () -> Unit) {
try {
block()
} catch (e: Exception) {
SdkLogger.e("执行异常", e)
ErrorReporter.report(e)
}
}
}
// 所有公开 API 都做防护
class MySdkImpl : MySdk {
override fun track(event: String, params: Map<String, Any>) {
SafeExecutor.execute {
// 即使内部实现出 bug, 也不会崩溃宿主 App
trackInternal(event, params)
}
}
}
2. 线程安全
// ✅ 公开 API 必须线程安全 (接入方可能从任何线程调用)
class MySdkImpl : MySdk {
@Volatile
private var isInitialized = false
// 方式1: 同步锁
private val lock = Any()
override fun track(event: String, params: Map<String, Any>) {
synchronized(lock) {
checkInitialized()
eventQueue.enqueue(Event(event, params))
}
}
// 方式2: 串行化 (推荐)
// 所有操作 post 到内部单线程, 天然线程安全
private val sdkHandler = HandlerThread("sdk-thread").apply { start() }
.let { Handler(it.looper) }
override fun track(event: String, params: Map<String, Any>) {
sdkHandler.post {
trackInternal(event, params)
}
}
// 方式3: 协程串行化
private val sdkScope = CoroutineScope(
SupervisorJob() + Dispatchers.Default.limitedParallelism(1)
)
}
3. 兼容性
// ✅ minSdk 尽量低 (覆盖更多设备)
// 推荐 minSdk 21 (Android 5.0, 覆盖 99%+ 设备)
// ✅ 依赖尽量少, 避免版本冲突
// ❌ 不要
dependencies {
api("com.squareup.okhttp3:okhttp:4.12.0") // 可能与宿主版本冲突!
api("com.google.code.gson:gson:2.10.1") // 同上
api("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
}
// ✅ 依赖最小化
dependencies {
// 核心功能用 Android 原生 API 实现
// 如果必须用第三方库, 使用 implementation (不传递依赖)
implementation("com.squareup.okhttp3:okhttp:4.12.0")
// 或者提供适配接口, 让宿主注入
compileOnly("com.squareup.okhttp3:okhttp:4.12.0")
}
// ✅ 编译选项
android {
compileSdk = 34
defaultConfig {
minSdk = 21
// 不要设置 targetSdk (由宿主 App 决定)
}
compileOptions {
sourceCompatibility = JavaVersion.VERSION_1_8
targetCompatibility = JavaVersion.VERSION_1_8
}
}
依赖冲突解决策略:
┌─────────────────────────────────────────────────────────────┐
│ │
│ 策略1: 不依赖第三方库 (最安全) │
│ 网络 → HttpURLConnection / 内置轻量封装 │
│ JSON → org.json (系统自带) / 手写解析 │
│ 线程 → Handler / ExecutorService │
│ 存储 → SharedPreferences / SQLiteOpenHelper │
│ │
│ 策略2: compileOnly + 运行时检测 │
│ compileOnly("com.squareup.okhttp3:okhttp:4.12.0") │
│ 运行时: 检测类是否存在, 存在则使用, 否则用内置实现 │
│ │
│ 策略3: 重打包 (Shade/Relocate) │
│ 用 shadow 插件将第三方库重命名包名 │
│ com.squareup.okhttp3 → com.mysdk.internal.okhttp3 │
│ 完全避免冲突, 但增加包体积 │
│ │
│ 策略4: 提供多 Artifact │
│ mysdk-core (纯净, 无依赖) │
│ mysdk-okhttp (OkHttp 适配器) │
│ mysdk-gson (Gson 适配器) │
│ 接入方按需引入 │
│ │
└─────────────────────────────────────────────────────────────┘
4. 隔离 --- 不影响宿主
// ✅ 独立线程池 (不占用宿主线程资源)
internal val sdkExecutor = ThreadPoolExecutor(
1, 2, 30, TimeUnit.SECONDS,
ArrayBlockingQueue(128),
NamedThreadFactory("mysdk"),
ThreadPoolExecutor.DiscardOldestPolicy() // 满了丢弃旧的, 不抛异常
)
// ✅ 独立数据库 (不与宿主冲突)
// 数据库文件用 SDK 特有前缀
private const val DB_NAME = "mysdk_internal.db"
// ✅ 独立 SharedPreferences
private const val SP_NAME = "mysdk_prefs"
val prefs = context.getSharedPreferences(SP_NAME, Context.MODE_PRIVATE)
// ✅ 独立文件目录
val sdkDir = File(context.filesDir, "mysdk_data")
sdkDir.mkdirs()
// ✅ 独立进程 (极端隔离, 谨慎使用)
// <service android:name=".SdkService" android:process=":mysdk" />
// 优点: 完全隔离, SDK crash 不影响主进程
// 缺点: 进程间通信开销, 内存增加
四、性能
1. 初始化性能 --- 不能拖慢 App 启动
// ✅ 异步初始化 + 延迟初始化
class MySdk {
companion object {
@Volatile
private var instance: MySdkImpl? = null
// 轻量同步初始化 (< 5ms)
fun init(context: Context, config: Config = Config.default()) {
val appContext = context.applicationContext
instance = MySdkImpl(appContext, config)
// 重量级初始化放到后台
instance!!.initAsync()
}
}
}
internal class MySdkImpl(context: Context, config: Config) {
fun initAsync() {
sdkScope.launch(Dispatchers.IO) {
// 耗时操作异步执行
initDatabase()
loadCachedConfig()
startHeartbeat()
preloadResources()
}
}
// 在需要时才初始化的组件
val networkClient by lazy { NetworkClient(config) }
val analyticsEngine by lazy { AnalyticsEngine(database) }
}
// ✅ 支持 App Startup (Jetpack)
class MySdkInitializer : Initializer<MySdk> {
override fun create(context: Context): MySdk {
return MySdk.init(context) // 自动初始化
}
override fun dependencies() = emptyList<Class<out Initializer<*>>>()
}
2. 包体积 --- 越小越好
┌──────────────────────────────────────────────────────────────┐
│ 包体积优化策略 │
├──────────────────────────────────────────────────────────────┤
│ │
│ 1. 减少依赖 │
│ 尽量用 Android 原生 API │
│ 每引入一个库 = 增加 几十KB~几MB │
│ │
│ 2. ProGuard / R8 混淆 │
│ consumerProguardFiles("proguard-rules.pro") │
│ 打包到 AAR 中, 自动应用到宿主 │
│ │
│ 3. 资源最小化 │
│ ├── 不包含不必要的资源 (图片/布局/字符串) │
│ ├── 资源名加 SDK 前缀 (mysdk_ 避免冲突) │
│ ├── VectorDrawable 替代 PNG │
│ └── resConfigs 只保留需要的语言 │
│ │
│ 4. 按需加载 │
│ 核心功能在主包, 高级功能动态下发 │
│ 或拆分为多个 artifact (mysdk-core / mysdk-ui) │
│ │
│ 5. 代码精简 │
│ 避免使用大型注解处理器 (如 Dagger 全家桶) │
│ 避免 Kotlin 反射 (kotlin-reflect 2.5MB!) │
│ │
│ 目标: 核心 SDK < 100KB ~ 500KB │
│ │
└──────────────────────────────────────────────────────────────┘
3. 内存 / CPU / 电量
// ✅ 内存控制
// 限制内部缓存大小
private val cache = LruCache<String, ByteArray>(maxSize = 2 * 1024 * 1024) // 2MB
// 及时释放大对象
fun onTrimMemory(level: Int) {
if (level >= ComponentCallbacks2.TRIM_MEMORY_RUNNING_LOW) {
cache.evictAll()
bitmapPool.clear()
}
}
// ✅ CPU 控制
// 后台任务降低线程优先级
Process.setThreadPriority(Process.THREAD_PRIORITY_BACKGROUND)
// 批量处理, 减少唤醒次数
private val eventBatch = mutableListOf<Event>()
private val flushRunnable = Runnable {
if (eventBatch.isNotEmpty()) {
sendBatch(ArrayList(eventBatch))
eventBatch.clear()
}
}
override fun track(event: Event) {
eventBatch.add(event)
if (eventBatch.size >= BATCH_SIZE) {
handler.removeCallbacks(flushRunnable)
handler.post(flushRunnable)
} else {
handler.removeCallbacks(flushRunnable)
handler.postDelayed(flushRunnable, FLUSH_INTERVAL) // 30秒
}
}
// ✅ 电量优化
// 合并网络请求, 减少无线电唤醒
// 使用 WorkManager 做非紧急上传
WorkManager.getInstance(context).enqueueUniquePeriodicWork(
"sdk_sync",
ExistingPeriodicWorkPolicy.KEEP,
PeriodicWorkRequestBuilder<SyncWorker>(1, TimeUnit.HOURS).build()
)
五、安全性
┌──────────────────────────────────────────────────────────────┐
│ 安全性关注点 │
├──────────────────────────────────────────────────────────────┤
│ │
│ 1. 数据传输安全 │
│ ✅ 所有网络请求走 HTTPS │
│ ✅ Certificate Pinning (证书锁定) │
│ ✅ 敏感数据加密传输 │
│ │
│ 2. 数据存储安全 │
│ ✅ 敏感信息不明文存储 (EncryptedSharedPreferences) │
│ ✅ 数据库加密 (SQLCipher) │
│ ✅ 日志中不打印敏感信息 (token/密码/手机号) │
│ │
│ 3. 密钥管理 │
│ ✅ AppKey/Secret 不硬编码在代码中 │
│ ✅ 使用 Android Keystore 存储密钥 │
│ ✅ 服务端动态下发配置 │
│ │
│ 4. 防篡改 / 防调试 │
│ ✅ ProGuard/R8 混淆 │
│ ✅ 签名校验 (验证宿主 App 签名) │
│ ✅ 关键逻辑放 Native 层 (NDK) │
│ │
│ 5. 权限最小化 │
│ ✅ 只申请必要权限 │
│ ✅ 运行时权限动态检查, 没有权限则降级 │
│ ✅ 不要申请与 SDK 功能无关的权限 │
│ │
│ 6. 隐私合规 (GDPR/CCPA/个保法) │
│ ✅ 提供用户数据删除接口 │
│ ✅ 提供数据采集开关 (opt-in / opt-out) │
│ ✅ 隐私政策中说明采集了什么数据 │
│ ✅ 在用户同意前不采集任何数据 │
│ ✅ 不采集 IMEI/MAC 等不可重置标识符 │
│ │
└──────────────────────────────────────────────────────────────┘
// ✅ 隐私合规示例
class MySdk {
companion object {
private var isConsentGiven = false
// 必须先获得用户同意
fun setConsentStatus(consent: Boolean) {
isConsentGiven = consent
if (!consent) {
// 用户撤回同意 → 停止采集 + 删除已采集数据
instance?.stopCollection()
instance?.deleteAllUserData()
}
}
fun init(context: Context, config: Config) {
// 初始化时不采集数据, 等用户同意后才开始
instance = MySdkImpl(context, config)
}
}
}
internal class MySdkImpl {
fun track(event: String) {
if (!isConsentGiven) {
SdkLogger.d("用户未同意, 跳过数据采集")
return
}
// 正常采集
}
fun deleteAllUserData() {
database.clearAll()
preferences.clear()
cache.evictAll()
SdkLogger.i("已删除所有用户数据")
}
}
六、初始化设计
// ✅ 推荐: 多种初始化方式并存
// 方式1: 手动初始化 (最明确)
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
MySdk.init(this) {
appKey = "xxx"
debug = BuildConfig.DEBUG
}
}
}
// 方式2: App Startup 自动初始化 (零代码接入)
// AndroidManifest.xml
<provider
android:name="androidx.startup.InitializationProvider"
android:authorities="${applicationId}.androidx-startup">
<meta-data
android:name="com.mysdk.MySdkInitializer"
android:value="androidx.startup" />
</provider>
// 方式3: ContentProvider 自动初始化 (无需 App Startup)
// 适合不依赖 Jetpack 的场景
internal class MySdkAutoInitProvider : ContentProvider() {
override fun onCreate(): Boolean {
MySdk.init(context!!)
return true
}
// ... 其他方法返回空/false
}
// ✅ 防重复初始化
class MySdk {
companion object {
@Volatile
private var initialized = false
fun init(context: Context, block: Config.Builder.() -> Unit = {}) {
if (initialized) {
SdkLogger.w("SDK 已初始化, 忽略重复调用")
return
}
synchronized(this) {
if (initialized) return
// ... 初始化逻辑
initialized = true
}
}
}
}
// ✅ 未初始化时给出友好提示
override fun track(event: String) {
if (!initialized) {
SdkLogger.e("SDK 未初始化! 请先调用 MySdk.init()")
// 不崩溃, 但记录错误
return
}
}
七、可观测性
日志系统
// ✅ 完善的日志系统
// 1. 分级日志
enum class LogLevel { VERBOSE, DEBUG, INFO, WARN, ERROR, NONE }
object SdkLogger {
var level: LogLevel = LogLevel.WARN // 默认只输出 WARN+
var delegate: LogDelegate? = null // 允许接入方接管日志
fun d(msg: String, t: Throwable? = null) {
if (level <= LogLevel.DEBUG) {
delegate?.log(LogLevel.DEBUG, TAG, msg, t)
?: Log.d(TAG, msg, t)
}
}
// ...
}
// 2. 接入方可以接管日志
interface LogDelegate {
fun log(level: LogLevel, tag: String, msg: String, throwable: Throwable?)
}
MySdk.init(context) {
logger = object : LogDelegate {
override fun log(level: LogLevel, tag: String, msg: String, t: Throwable?) {
Timber.tag(tag).d(t, msg) // 接入方用自己的日志框架
}
}
logLevel = if (BuildConfig.DEBUG) LogLevel.VERBOSE else LogLevel.WARN
}
// 3. Release 版本默认关闭详细日志
// 4. 日志中脱敏 (不打印 token/密码等)
fun maskToken(token: String): String {
if (token.length <= 8) return "****"
return token.take(4) + "****" + token.takeLast(4)
}
监控与回调
// ✅ 提供生命周期回调, 让接入方了解 SDK 状态
interface SdkStateListener {
fun onInitialized()
fun onError(error: SdkError)
fun onNetworkStateChanged(connected: Boolean)
fun onConfigUpdated(config: RemoteConfig)
}
// ✅ 提供统计信息
interface SdkMonitor {
val pendingEventCount: Int
val lastSyncTime: Long
val errorCount: Int
fun getDiagnosticInfo(): Map<String, Any> // 排查问题用
}
// 排查问题时:
Log.d("Diag", MySdk.getDiagnosticInfo().toString())
// {version=2.1.0, events_pending=12, last_sync=2024-01-15T10:30:00,
// errors_24h=3, network=WiFi, storage_used=1.2MB}
八、测试
┌──────────────────────────────────────────────────────────────┐
│ SDK 测试策略 │
├──────────────────────────────────────────────────────────────┤
│ │
│ 1. 单元测试 (80%+覆盖率) │
│ ├── 核心逻辑: 事件处理/序列化/去重/采样 │
│ ├── Mock 网络/存储/Context │
│ └── 边界条件: 空值/超大数据/并发 │
│ │
│ 2. 集成测试 │
│ ├── 端到端: 从 API 调用到数据上报 │
│ ├── 生命周期: Activity/Fragment 各生命周期 │
│ └── 配置变更: 旋转屏幕/多窗口 │
│ │
│ 3. 兼容性测试 │
│ ├── 多 Android 版本 (API 21~34) │
│ ├── 多厂商 (Samsung/Xiaomi/Huawei/Oppo) │
│ ├── 多分辨率/屏幕尺寸 │
│ └── 与主流 SDK 共存 (Firebase/友盟/Bugly) │
│ │
│ 4. 性能测试 │
│ ├── 启动时间影响 (< 5ms 同步初始化) │
│ ├── 内存占用 (< 5MB 常驻) │
│ ├── CPU 占用 (< 1% 平均) │
│ ├── 电量消耗 (不显著增加) │
│ └── 包体积 (< 500KB) │
│ │
│ 5. 稳定性测试 │
│ ├── Monkey 测试 (长时间随机操作) │
│ ├── 弱网测试 (2G/断网/网络切换) │
│ ├── 内存不足场景 │
│ └── 进程杀死/恢复 │
│ │
│ 6. 提供 Mock / 测试工具 │
│ ├── MySdk.setTestMode(true) → 数据不上报 │
│ ├── FakeMySdk 实现 → 接入方方便写测试 │
│ └── 内存存储替代磁盘存储 → 测试不留痕 │
│ │
└──────────────────────────────────────────────────────────────┘
// ✅ 提供测试辅助
// 让接入方容易 Mock SDK
interface MySdk {
fun track(event: String)
// ...
}
// 提供假实现
class FakeMySdk : MySdk {
val trackedEvents = mutableListOf<String>()
override fun track(event: String) {
trackedEvents.add(event) // 记录而不真正上报
}
}
// 接入方测试
@Test
fun `purchase should track event`() {
val fakeSdk = FakeMySdk()
MySdk.setInstance(fakeSdk) // 测试时替换
viewModel.onPurchase()
assertEquals("purchase", fakeSdk.trackedEvents.last())
}
九、版本管理与发布
┌──────────────────────────────────────────────────────────────┐
│ 版本管理策略 │
├──────────────────────────────────────────────────────────────┤
│ │
│ 语义化版本: MAJOR.MINOR.PATCH │
│ MAJOR: 不兼容的 API 变更 (1.x → 2.0) │
│ MINOR: 向后兼容的功能新增 (2.1 → 2.2) │
│ PATCH: 向后兼容的 Bug 修复 (2.2.0 → 2.2.1) │
│ │
│ API 废弃策略: │
│ 1. 标记 @Deprecated + 提供替代方案 │
│ 2. 至少保留 2 个大版本 (1.x 废弃 → 3.0 才移除) │
│ 3. 迁移指南文档 │
│ │
│ 发布流程: │
│ 开发 → 内部测试 → 灰度发布(1%) → 扩大灰度(10%) │
│ → 全量发布 → 监控 → Hotfix(如需要) │
│ │
│ 分发方式: │
│ ✅ Maven Central / Google Maven │
│ ✅ 私有 Maven (公司内部) │
│ ✅ AAR 直接分发 (离线场景) │
│ ✅ GitHub Packages │
│ │
│ Changelog: │
│ 每个版本详细列出: │
│ - 新增功能 │
│ - 修复 Bug │
│ - 破坏性变更 (Breaking Changes) │
│ - 废弃的 API │
│ - 迁移指南 │
│ │
└──────────────────────────────────────────────────────────────┘
// ✅ 优雅的 API 废弃
// v2.1: 原 API
fun trackEvent(name: String, properties: HashMap<String, String>) { ... }
// v2.2: 标记废弃, 提供新 API
@Deprecated(
message = "使用 track() 替代, 支持更多参数类型",
replaceWith = ReplaceWith("track(name, properties)"),
level = DeprecationLevel.WARNING // 先警告
)
fun trackEvent(name: String, properties: HashMap<String, String>) {
track(name, properties.toMap()) // 内部桥接到新 API
}
// 新 API
fun track(name: String, properties: Map<String, Any> = emptyMap()) { ... }
// v3.0: 提升废弃级别或移除
@Deprecated(level = DeprecationLevel.ERROR) // 编译错误, 强制迁移
fun trackEvent(...)
十、文档与集成体验
┌──────────────────────────────────────────────────────────────┐
│ 文档体系 │
├──────────────────────────────────────────────────────────────┤
│ │
│ 1. 快速开始 (5 分钟集成指南) │
│ ├── 一行依赖配置 │
│ ├── 一行初始化代码 │
│ ├── 一行功能调用 │
│ └── 运行效果截图/Gif │
│ │
│ 2. API 文档 (KDoc/Javadoc) │
│ ├── 每个公开类/方法都有文档注释 │
│ ├── 参数说明 + 返回值说明 │
│ ├── 代码示例 │
│ └── @throws 说明可能的异常 │
│ │
│ 3. 进阶指南 │
│ ├── 自定义配置 │
│ ├── 高级功能 │
│ ├── 最佳实践 │
│ └── 性能优化建议 │
│ │
│ 4. 迁移指南 │
│ ├── 版本间 API 变化对比 │
│ ├── 自动迁移脚本 (如可能) │
│ └── 常见迁移问题 FAQ │
│ │
│ 5. 示例项目 │
│ ├── 最小集成示例 (sample-minimal) │
│ ├── 完整功能示例 (sample-full) │
│ ├── Java 示例 + Kotlin 示例 │
│ └── 各种架构示例 (MVVM/MVI/Compose) │
│ │
│ 6. 常见问题 FAQ │
│ ├── 集成问题 (依赖冲突/混淆/多模块) │
│ ├── 运行时问题 (崩溃/ANR/内存) │
│ └── 错误码速查表 │
│ │
│ 7. Changelog │
│ 每个版本的详细变更记录 │
│ │
└──────────────────────────────────────────────────────────────┘
// ✅ 优秀的 KDoc 示例
/**
* 追踪用户事件。
*
* 事件会先缓存在本地, 达到阈值后批量上报。
* 可以调用 [flush] 强制立即上报。
*
* **线程安全**: 可以在任意线程调用。
*
* @param eventName 事件名称, 不能为空, 长度不超过 128 字符。
* 建议使用 snake_case 命名, 如 "button_clicked"。
* @param properties 事件属性, key 不超过 64 字符, value 支持
* String/Int/Long/Double/Boolean 类型。
* 默认为空。
*
* @throws SdkError.NotInitialized 如果 SDK 未初始化
*
* @sample com.mysdk.samples.TrackingSample.trackPurchaseEvent
*
* @see flush
* @see setUserId
* @since 2.0.0
*/
fun track(
eventName: String,
properties: Map<String, Any> = emptyMap()
)
十一、完整 SDK 架构示例
mysdk/
├── mysdk-core/ ← 核心模块
│ ├── src/main/java/com/mysdk/
│ │ ├── MySdk.kt ← 公开: 唯一入口
│ │ ├── Config.kt ← 公开: 配置
│ │ ├── SdkError.kt ← 公开: 错误类型
│ │ ├── EventListener.kt ← 公开: 回调接口
│ │ │
│ │ └── internal/ ← 内部实现
│ │ ├── MySdkImpl.kt ← 核心实现
│ │ ├── SafeExecutor.kt ← 异常兜底
│ │ ├── SdkLogger.kt ← 日志
│ │ │
│ │ ├── event/
│ │ │ ├── EventQueue.kt ← 事件队列
│ │ │ ├── EventBatcher.kt ← 批量处理
│ │ │ └── EventSerializer.kt ← 序列化
│ │ │
│ │ ├── network/
│ │ │ ├── HttpClient.kt ← 网络接口
│ │ │ ├── DefaultHttpClient.kt ← 默认实现
│ │ │ └── RetryPolicy.kt ← 重试策略
│ │ │
│ │ ├── storage/
│ │ │ ├── Storage.kt ← 存储接口
│ │ │ ├── SpStorage.kt ← SP 实现
│ │ │ └── DbStorage.kt ← 数据库实现
│ │ │
│ │ └── lifecycle/
│ │ ├── AppStateTracker.kt ← 前后台监听
│ │ └── NetworkMonitor.kt ← 网络状态
│ │
│ ├── proguard-rules.pro ← 混淆规则 (打入AAR)
│ └── consumer-rules.pro ← 消费者混淆规则
│
├── mysdk-okhttp/ ← OkHttp 适配器 (可选)
│ └── OkHttpClientAdapter.kt
│
├── mysdk-compose/ ← Compose 扩展 (可选)
│ └── SdkComposables.kt
│
├── sample/ ← 示例 App
│ ├── sample-java/
│ └── sample-kotlin/
│
└── docs/ ← 文档
├── quick-start.md
├── api-reference.md
├── migration-guide.md
└── changelog.md
十二、核心 Checklist
┌──────────────────────────────────────────────────────────────────┐
│ SDK 设计 Checklist │
├──────────────────────────────────────────────────────────────────┤
│ │
│ API 设计 │
│ □ 最简使用不超过 3 行代码 │
│ □ 公开 API 尽量少, 内部 internal/private │
│ □ 返回接口不返回实现类 │
│ □ 命名一致, 风格统一 │
│ □ 错误类型清晰, 带指导性错误信息 │
│ □ 支持 Java 和 Kotlin 调用 │
│ □ 提供回调/协程/Flow 多种方式 │
│ │
│ 稳定性 │
│ □ SDK 异常不会导致宿主崩溃 │
│ □ 所有公开 API 线程安全 │
│ □ 参数校验 + 友好错误提示 │
│ □ 防重复初始化 │
│ □ 未初始化时有明确提示而非崩溃 │
│ │
│ 性能 │
│ □ 同步初始化 < 5ms │
│ □ 包体积 < 500KB (核心) │
│ □ 常驻内存 < 5MB │
│ □ 不影响 App 启动速度 │
│ □ 批量处理, 减少网络/磁盘操作 │
│ │
│ 兼容性 │
│ □ minSdk 21+ │
│ □ 依赖最小化, 无版本冲突 │
│ □ 资源名加前缀防冲突 │
│ □ ProGuard 规则打入 AAR │
│ │
│ 安全与隐私 │
│ □ HTTPS + 证书锁定 │
│ □ 敏感数据加密存储 │
│ □ 日志脱敏 │
│ □ 隐私合规 (同意前不采集/可删除/可关闭) │
│ □ 权限最小化 │
│ │
│ 可观测性 │
│ □ 分级日志 + 可接管 │
│ □ Debug/Release 日志级别不同 │
│ □ 提供诊断信息接口 │
│ □ 提供状态回调 │
│ │
│ 发布维护 │
│ □ 语义化版本 │
│ □ Changelog │
│ □ API 废弃有过渡期 │
│ □ 发布到 Maven 仓库 │
│ □ 完整文档 + 示例项目 │
│ │
│ 测试 │
│ □ 单元测试 > 80% 覆盖 │
│ □ 提供 Fake/Mock 实现给接入方测试 │
│ □ 提供测试模式 (数据不真正上报) │
│ □ 兼容性测试覆盖主流机型 │
│ │
└──────────────────────────────────────────────────────────────────┘