xdz-ios/SDK打包完整指南.md

iOS SDK 打包完整指南

✅ 哪些可以打包为 SDK？

所有 Swift Package 都可以打包为 SDK！

从 Package.swift 中的 products 配置可以看到：

products: [
    .library(
        name: "BaseCore",        // ✅ 可以打包
        targets: ["BaseCore"]
    )
]

可打包的模块

模块	类型	可打包	说明
BaseCore	基础核心层	✅	基础接口和实现
BaseCommon	业务封装层	✅	业务通用功能
CapabilityPush	能力层	✅	推送能力 SDK
CapabilityShare	能力层	✅	分享能力 SDK（待创建）
CapabilitySocketIO	能力层	✅	SocketIO 能力 SDK（待创建）

📦 打包方式

方式一：Swift Package Manager（推荐，最简单）

1. 本地打包（用于开发测试）

cd /Users/Zhuanz/Documents/code/xindazhou/xdz_ios/BaseCore
swift build                    # 编译
swift test                     # 运行测试

2. 发布到 Git（用于分发）

cd /Users/Zhuanz/Documents/code/xindazhou/xdz_ios/BaseCore

# 1. 提交代码
git add .
git commit -m "Release BaseCore 1.0.0"

# 2. 打标签
git tag 1.0.0
git push origin main
git push origin 1.0.0

# 3. 在其他项目中使用
# 在 Package.swift 或 Xcode 中添加：
# .package(url: "https://github.com/your-org/BaseCore.git", from: "1.0.0")

3. 本地路径依赖（用于开发）

// 在其他项目的 Package.swift 中
dependencies: [
    .package(path: "../BaseCore")  // 本地路径
]

方式二：XCFramework（用于分发二进制 SDK）

1. 使用 xcodebuild 构建

cd /Users/Zhuanz/Documents/code/xindazhou/xdz_ios/BaseCore

# 创建临时 Xcode 项目（如果需要）
# 或者直接使用 Swift Package

# 构建 XCFramework
xcodebuild archive \
  -scheme BaseCore \
  -destination "generic/platform=iOS" \
  -archivePath "./build/BaseCore-iOS.xcarchive" \
  SKIP_INSTALL=NO \
  BUILD_LIBRARY_FOR_DISTRIBUTION=YES

# 创建 XCFramework
xcodebuild -create-xcframework \
  -archive "./build/BaseCore-iOS.xcarchive" \
  -framework "BaseCore.framework" \
  -output "./build/BaseCore.xcframework"

2. 分发 XCFramework

将生成的 BaseCore.xcframework 打包分发：

cd build
zip -r BaseCore.xcframework.zip BaseCore.xcframework

方式三：CocoaPods（可选）

如果需要支持 CocoaPods，创建 .podspec 文件：

# BaseCore.podspec
Pod::Spec.new do |s|
  s.name             = 'BaseCore'
  s.version          = '1.0.0'
  s.summary          = '基础核心层 SDK'
  s.homepage         = 'https://github.com/your-org/BaseCore'
  s.license          = { :type => 'MIT' }
  s.author           = { 'Your Name' => 'your@email.com' }
  s.source           = { :git => 'https://github.com/your-org/BaseCore.git', :tag => s.version }
  s.ios.deployment_target = '15.0'
  s.source_files = 'Sources/BaseCore/**/*.swift'
end

🎯 能力层打包示例（CapabilityPush）

步骤 1：确保 Package.swift 配置正确

// CapabilityPush/Package.swift
let package = Package(
    name: "CapabilityPush",
    products: [
        .library(
            name: "CapabilityPush",  // ✅ 定义为 library，可以打包
            targets: ["CapabilityPush"]
        )
    ],
    dependencies: [
        .package(path: "../BaseCore")  // 依赖 BaseCore
    ],
    // ...
)

步骤 2：本地测试打包

cd /Users/Zhuanz/Documents/code/xindazhou/xdz_ios/CapabilityPush

# 编译测试
swift build

# 运行测试
swift test

步骤 3：发布到 Git

cd /Users/Zhuanz/Documents/code/xindazhou/xdz_ios/CapabilityPush

# 1. 初始化 Git（如果还没有）
git init
git add .
git commit -m "Initial commit: CapabilityPush 1.0.0"

# 2. 添加远程仓库
git remote add origin https://github.com/your-org/CapabilityPush.git

# 3. 打标签并推送
git tag 1.0.0
git push origin main
git push origin 1.0.0

步骤 4：在其他项目中使用

// 其他项目的 Package.swift
dependencies: [
    .package(url: "https://github.com/your-org/CapabilityPush.git", from: "1.0.0"),
    .package(url: "https://github.com/your-org/BaseCore.git", from: "1.0.0")
]

📋 打包检查清单

打包前检查

• Package.swift 中定义了 .library product
• 版本号已更新
• 所有依赖已正确配置
• 代码编译通过：swift build
• 测试通过：swift test
• README.md 已更新使用说明

打包后验证

• 可以正常导入：import CapabilityPush
• 所有公开 API 可用
• 依赖关系正确（BaseCore 自动传递）

🔧 快速打包脚本

创建 build_sdk.sh：

#!/bin/bash
# 快速打包 SDK 脚本

PACKAGE_NAME=$1
VERSION=$2

if [ -z "$PACKAGE_NAME" ] || [ -z "$VERSION" ]; then
    echo "用法: ./build_sdk.sh <PackageName> <Version>"
    echo "示例: ./build_sdk.sh CapabilityPush 1.0.0"
    exit 1
fi

cd "$PACKAGE_NAME"

echo "=== 打包 $PACKAGE_NAME v$VERSION ==="

# 1. 编译
echo "1. 编译..."
swift build
if [ $? -ne 0 ]; then
    echo "❌ 编译失败"
    exit 1
fi

# 2. 测试
echo "2. 运行测试..."
swift test
if [ $? -ne 0 ]; then
    echo "❌ 测试失败"
    exit 1
fi

# 3. 打标签（如果使用 Git）
if [ -d ".git" ]; then
    echo "3. 创建 Git 标签..."
    git tag "$VERSION"
    git push origin main
    git push origin "$VERSION"
    echo "✅ 标签已创建: $VERSION"
fi

echo "✅ $PACKAGE_NAME v$VERSION 打包完成！"

使用方法：

chmod +x build_sdk.sh
./build_sdk.sh CapabilityPush 1.0.0

📊 各模块打包说明

BaseCore

• 类型：基础核心层
• 依赖：无（只依赖系统框架）
• 打包方式：Swift Package 或 XCFramework
• 使用场景：其他模块的基础依赖

BaseCommon

• 类型：业务封装层
• 依赖：BaseCore（传递依赖）
• 打包方式：Swift Package 或 XCFramework
• 使用场景：业务通用功能

CapabilityPush

• 类型：能力层 SDK
• 依赖：BaseCore（传递依赖）
• 打包方式：Swift Package 或 XCFramework
• 使用场景：独立的推送能力 SDK，可以单独分发

🎯 最佳实践

1. 版本管理：使用语义化版本（Semantic Versioning）

   • 主版本号：不兼容的 API 修改
   • 次版本号：向下兼容的功能性新增
   • 修订号：向下兼容的问题修正

2. 依赖管理：

   • 能力层只依赖 BaseCore（不依赖 BaseCommon）
   • BaseCommon 依赖 BaseCore
   • 业务项目依赖 BaseCommon 和所需的能力层

3. 文档：每个 SDK 都应该有：

   • README.md（使用说明）
   • API 文档（代码注释）
   • 示例代码

4. 测试：确保每个 SDK 都有完整的测试

💡 总结

所有模块都可以打包为 SDK：

• ✅ BaseCore - 基础核心 SDK
• ✅ BaseCommon - 业务封装 SDK
• ✅ CapabilityPush - 推送能力 SDK
• ✅ 其他能力层 - 都可以打包

推荐打包方式：

1. 开发阶段：使用本地路径依赖
2. 内部使用：发布到私有 Git 仓库
3. 对外分发：使用 XCFramework 或 CocoaPods