📚 课程目录第3章 SDK包集成方式

3. SDK 包集成方式

3.1 集成方式总览

支付SDK通常提供以下五种集成方式，覆盖Android、iOS、跨平台及桌面应用场景。选择哪种方式取决于项目构建工具链与团队技术栈。

集成方式	适用平台	主要配置文件	典型依赖声明
Maven	Android / Java (Gradle wrapper)	`build.gradle` (Project / Module)	compile / implementation + Maven Central
Gradle	Android / Kotlin Multiplatform	`build.gradle.kts` / `settings.gradle`	implementation + version catalog
CocoaPods	iOS / macOS (Objective-C/Swift)	`Podfile`	pod 'PaymentSDKName'
Swift Package Manager	iOS / macOS / tvOS	`Package.swift` 或 Xcode GUI	dependencies: [.package(url: ...)]
手动集成	所有平台	无（直接引入 .jar / .framework / .xcframework）	Link Binary With Libraries + Embed

3.2 Android 端集成：Maven / Gradle

支付SDK通常托管在 Maven Central 或 GitHub Packages。以Maven Central为例，首先在项目级的 build.gradle 或 settings.gradle 中添加仓库地址。

步骤1：配置仓库地址

// settings.gradle (推荐新版方式)
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        // 如果SDK在GitHub Packages，添加以下地址
        maven {
            url = uri("https://maven.pkg.github.com/YourOrg/YourSDK")
            credentials {
                username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_USER")
                password = project.findProperty("gpr.key") ?: System.getenv("GITHUB_")
            }
        }
    }
}

步骤2：添加依赖声明

// module-level build.gradle.kts
dependencies {
    // 核心SDK
    implementation("com.yourcompany:payment-sdk:2.5.0")
    
    // 扩展模块（可选）
    implementation("com.yourcompany:payment-sdk-wechat:2.5.0")
    implementation("com.yourcompany:payment-sdk-alipay:2.5.0")
    
    // 如果使用R8/ProGuard，确保规则未被移除
    implementation("com.yourcompany:payment-sdk-proguard:2.5.0")
}

⚠️ 版本号陷阱：请始终使用完全限定版本号（如 2.5.0），避免使用 + 通配符（2.5.+）。通配符可能导致构建时拉取非预期的破坏性版本，且无法复现历史构建。

3.3 iOS 端集成：CocoaPods

CocoaPods 是目前iOS第三方库的主流管理工具。支付SDK通常以静态库或动态框架形式发布。

# Podfile
platform :ios, '12.0'
use_frameworks!  # 如果SDK使用Swift或需要动态框架

target 'YourAppTarget' do
  pod 'PaymentSDK', '~> 3.1.0'
  pod 'PaymentSDK/WeChat', '~> 3.1.0'  # 子模块
  pod 'PaymentSDK/Alipay', '~> 3.1.0'
end

执行 pod install --repo-update 后，CocoaPods 会生成 .xcworkspace 文件。此后必须使用该工作空间打开项目。

💡 优化提示：如果集成后编译报 “No such module ‘PaymentSDK’”，请检查 use_frameworks! 是否启用，或尝试添加 use_frameworks! :linkage => :static 解决动态库依赖冲突。

3.4 iOS / macOS 端集成：Swift Package Manager

SPM 是Apple官方推荐的依赖管理工具，从Xcode 12起可直接集成。支付SDK需提供 Package.swift 清单。

在 Xcode 中添加：

File → Add Packages…
输入SDK仓库URL：https://github.com/YourOrg/payment-sdk-spm.git
选择 “Dependency Rule” → “Up to Next Major Version” → 3.1.0
选择目标Target，点击 “Add Package”

通过 Package.swift 手动添加（跨平台项目）：

// swift-tools-version:5.5
import PackageDescription

let package = Package(
    name: "YourApp",
    platforms: [
        .iOS(.v13),
        .macOS(.v10_15)
    ],
    dependencies: [
        .package(url: "https://github.com/YourOrg/payment-sdk-spm.git",
                 from: "3.1.0")
    ],
    targets: [
        .target(
            name: "YourTarget",
            dependencies: [
                .product(name: "PaymentSDK", package: "payment-sdk-spm"),
                .product(name: "PaymentSDKWeChat", package: "payment-sdk-spm")
            ])
    ]
)

3.5 手动集成（所有平台）

手动集成适用于以下场景：

网络受限的内网开发环境；
SDK未上架公共仓库（如企业内部SDK）；
需要定制SDK编译选项（如禁用部分模块）。

Android 手动集成步骤：

从发布页面下载 .aar 或 .jar 文件。
放入 app/libs/ 目录。
在 build.gradle 中添加：

// module-level build.gradle.kts
android {
    // …
}
dependencies {
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.aar", "*.jar"))))
    // 如果SDK有子依赖，需手动补充
    implementation("com.google.code.gson:gson:2.10.1")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
}

iOS 手动集成步骤：

下载 .xcframework 或 .framework 包。
拖入 Xcode Project Navigator 的 “Frameworks, Libraries, and Embedded Content” 区域。
确保 “Embed & Sign” 或 “Do Not Embed” 根据SDK类型设置正确。
在 “Build Settings” → “Framework Search Paths” 添加路径（如有嵌套）。
如果SDK包含资源包，还需添加到 “Copy Bundle Resources”。

⚠️ 手动集成常见错误：

Undefined symbols / Missing required architecture：检查 .xcframework 是否包含真机和模拟器切片，使用 lipo -info 验证。
NSInvalidArgumentException (unrecognized selector)：通常因缺少 -ObjC 或其他链接器标志，在 “Other Linker Flags” 中添加 -ObjC 和 -all_load。
dyld: Library not loaded：动态库未嵌入，改为 “Embed & Sign”。

3.6 集成验证

无论通过哪种方式集成，完成依赖配置后应执行一次干净构建，并通过以下方式确认SDK已正确链接：

Android： 在代码中引用任意公开类（如 PaymentClient），编译应不报 “unresolved reference”。
iOS： 在 ViewController.swift 中 import PaymentSDK，Xcode 应有自动补全提示。
日志： 在应用启动时调用SDK的版本查询方法，确认返回版本号与集成版本一致。

// 验证示例（Kotlin）
Log.d("SDKCheck", "SDK Version: ${PaymentSDK.version()}")  // 预期输出: 2.5.0

// 验证示例（Swift）
print("SDK Version: \(PaymentSDK.version())")  // 预期输出: 3.1.0

若日志输出版本号，说明SDK包已成功集成到工程中，可以进入下一阶段——注册与初始化配置。