1. 项目概述iOS内购的“最后一公里”难题做iOS开发这么多年内购In-App Purchase IAP这套流程从沙盒测试到上架审核大家应该都轻车熟路了。但不知道你有没有遇到过这样的场景用户怒气冲冲地找过来说“我刚买的月卡怎么没到账”或者“我孩子误操作买了东西能退吗”。这时候如果你只能让用户去翻邮箱找苹果的收据或者冷冰冰地回复一句“请自行联系苹果客服申请退款”那用户体验基本就跌到谷底了。WWDC21上苹果悄然但有力地推出了几项StoreKit 2的更新在我看来这恰恰是为我们开发者补上了内购生态的“最后一公里”——App内退款、历史订单查询以及更可靠的用户绑定防掉单机制。以前这些功能要么依赖复杂的服务器验证要么根本不在开发者的可控范围内。现在借助新的StoreKit API我们终于可以把这些能力集成到自己的App里给用户提供一个闭环的、无缝的消费体验。这不仅仅是几个新API更是一种产品思维和用户服务理念的升级。想象一下用户能在你的App里一键查询所有购买记录、自助提交退款申请、并且每一次消费都能稳稳地和自己的账号绑定这能极大提升用户信任感和满意度减少客服压力甚至降低因支付纠纷导致的差评。接下来我就结合WWDC21的内容和后续的实践把这“三步曲”的里里外外、坑坑洼洼都给你捋清楚。2. 核心能力拆解新StoreKit 2带来了什么StoreKit 2并非在WWDC21上首次亮相但这一届大会确实为其添加了至关重要的“售后服务”拼图。要理解这三步曲我们得先看看手中的“新工具”有哪些。2.1 Transaction交易对象的进化StoreKit 2的核心是新的Transaction模型Transaction协议和VerificationResult枚举。它取代了旧版基于SKPaymentTransaction的繁琐流程。每一个Transaction都包含了一次购买的完整、可验证的信息并且有一个全局唯一的id。这个id和苹果服务器上的交易记录直接对应是我们实现后续所有功能的基础。注意StoreKit 1和StoreKit 2的API可以共存但数据模型不互通。如果你要迁移需要处理新旧两套交易记录的映射问题尤其是处理那些“掉单”的历史订单。2.2 关键新增API一览退款申请引入了beginRefundRequest(for:in:)方法。开发者可以在App内针对某个仍在退款有效期内的Transaction发起退款流程。系统会弹出一个原生界面引导用户完成向苹果提交退款申请的步骤。历史订单查询提供了Transaction.all这个异步序列。通过它我们可以获取当前用户App Store账户在此App下的所有历史交易记录包括已经消费的、订阅的、甚至已经退款的。这是实现“订单中心”功能的数据基础。强化授权与监听通过AppTransaction可以获取应用下载时的原始交易信息并结合Transaction.updates这个Task来监听实时交易状态变化。这为更精准地绑定用户和防止掉单提供了更可靠的机制。3. 第一步App内集成退款流程以前退款是用户和苹果之间的事。用户需要记住购买时间、商品信息然后到苹果官网或报告问题页面reportaproblem.apple.com去操作流程割裂且复杂。现在我们可以把这个入口集成到App内。3.1 实现原理与前置条件App内退款本质上是一个“引导”流程。开发者调用API后系统会接管并弹出原生界面用户在此界面确认退款理由并提交。最终审批权仍在苹果退款金额也会原路返回至用户的支付账户。整个过程你的App无法知道用户具体选择了什么退款理由也无法干预审批结果但可以获知退款申请是否已成功提交给苹果系统。前置条件至关重要仅支持使用StoreKit 2 API处理的交易即Transaction对象。交易必须处于可退款状态。通常苹果对大部分内购项目提供购买后90天内的退款窗口但具体政策以苹果为准。API会自行校验。用户设备需运行iOS 15.0, iPadOS 15.0, macOS 12.0或更高版本。该功能不支持在Mac Catalyst应用中使用。3.2 代码实操与状态处理假设我们有一个订单列表每个订单项对应一个Transaction。当用户点击“申请退款”按钮时import StoreKit MainActor func requestRefund(for transactionId: UInt64) async { // 1. 根据transactionId获取对应的Transaction对象 // 通常你需要维护一个当前用户的Transaction数组 guard let transaction await Transaction(verificationResult: .verified(.init(id: transactionId))) else { // 处理未找到交易的情况 showAlert(title: 错误, message: 未找到对应的购买记录。) return } // 2. 检查当前交易状态是否可退款非必须API内部会校验但提前判断可提升体验 guard transaction.refund ! .notAvailable else { showAlert(title: 无法退款, message: 该购买记录不符合退款条件或已超过退款期限。) return } // 3. 调用退款API指定在哪个windowScene中弹出界面 guard let windowScene UIApplication.shared.connectedScenes.first as? UIWindowScene else { return } do { // 这是关键调用 let refundStatus try await Transaction.beginRefundRequest( for: transaction.id, in: windowScene ) // 4. 处理退款申请提交结果 switch refundStatus { case .userCancelled: // 用户在原生退款界面中取消了操作 print(用户取消了退款申请。) case .success: // 退款申请已成功提交至苹果系统 showAlert(title: 已提交, message: 您的退款申请已提交请等待苹果审核。) // 重要更新本地UI或状态例如将订单标记为“退款申请中” updateTransactionLocalState(transactionId, newState: .refundRequested) unknown default: break } } catch { // 处理错误例如网络问题、交易状态不符等 showAlert(title: 提交失败, message: 退款申请提交失败\(error.localizedDescription)) } }实操心得状态管理beginRefundRequest返回的RefundRequestStatus只代表“申请提交”是否成功不代表退款是否获批。获批结果需要通过监听Transaction.updates或定期查询Transaction.all来获取。当交易状态更新为revoked时表示退款已获批准并处理。UI时机这个API会触发一个系统模态页面。请确保在用户操作如点击按钮后直接调用不要在其他动画或转场过程中调用以免界面层级混乱。错误处理最常见的错误是StoreKitError.unsupportedPlatform在Catalyst上调用和StoreKitError.refundNotAvailable。务必做好用户友好的错误提示。4. 第二步构建用户历史订单查询系统有了Transaction.all为用户打造一个“我的订单”页面变得前所未有的简单。这个异步序列返回的是当前App Store账户在此App下的所有交易按时间倒序排列。4.1 获取与展示所有历史交易import StoreKit import SwiftUI // 示例使用SwiftUI struct OrderHistoryView: View { State private var allTransactions: [Transaction] [] State private var isLoading false State private var errorMessage: String? var body: some View { NavigationView { List { if isLoading { ProgressView(加载订单历史...) } else if let error errorMessage { Text(加载失败: \(error)) .foregroundColor(.red) } else { ForEach(allTransactions, id: \.id) { transaction in TransactionRow(transaction: transaction) } } } .navigationTitle(购买记录) .task { await loadTransactionHistory() } .refreshable { await loadTransactionHistory() } } } private func loadTransactionHistory() async { isLoading true errorMessage nil do { // 关键调用获取所有交易 var transactions: [Transaction] [] for await transaction in Transaction.all { // 这里可以对transaction进行验证但.all返回的已经是验证过的序列 // 通常我们只处理验证通过的.verified switch transaction { case .verified(let verifiedTx): transactions.append(verifiedTx) case .unverified(_, let error): // 记录或忽略未验证的交易 print(发现未验证的交易错误: \(error)) } } // 按购买日期倒序排列 self.allTransactions transactions.sorted { $0.purchaseDate $1.purchaseDate } } catch { self.errorMessage error.localizedDescription } isLoading false } } struct TransactionRow: View { let transaction: Transaction var body: some View { VStack(alignment: .leading, spacing: 4) { HStack { Text(transaction.productID) .font(.headline) Spacer() // 显示交易状态 StatusBadge(state: transaction.transactionState) } Text(金额: \(transaction.currencyCode) \(transaction.price, format: .number)) .font(.caption) .foregroundColor(.secondary) Text(日期: \(transaction.purchaseDate, format: .dateTime)) .font(.caption) .foregroundColor(.secondary) if let revocationDate transaction.revocationDate { Text(退款时间: \(revocationDate, format: .dateTime)) .font(.caption) .foregroundColor(.orange) } } .padding(.vertical, 4) } }4.2 关键细节与性能优化数据量Transaction.all返回的数据可能非常多特别是对于老用户或高频消费App。务必做分页或虚拟滚动不要试图一次性渲染成千上万条记录。虽然API是异步流但内存中持有大量Transaction对象也可能有压力。验证开销Transaction.all返回的序列中的每一项已经过初步验证。对于展示列表使用.verified的数据即可。只有当需要对某笔交易进行关键业务操作如发放虚拟商品时才需要调用Transaction(verificationResult:)进行独立的、更严格的验证。本地缓存考虑到网络和性能可以对获取到的交易列表进行本地缓存例如使用Core Data或SQLite。但需要建立缓存更新机制例如在App启动、用户下拉刷新、或收到Transaction.updates通知时增量更新缓存。状态展示Transaction的transactionState属性非常重要它包含了.purchased,.revoked已退款,.pending等待中如需要家庭共享确认等状态。在UI上清晰地区分这些状态能减少用户困惑。常见问题排查问题Transaction.all返回空数组。排查首先确认设备登录的App Store账号是否有购买记录。其次检查是否在Sandbox环境下测试沙盒环境的交易记录是独立的。确保用测试账号在沙盒环境完成过购买。问题交易记录加载非常慢。排查首次加载或记录非常多时可能较慢。这是网络请求。务必在UI上显示加载状态并考虑实现本地缓存首次加载后后续展示缓存数据后台静默更新。5. 第三步绑定用户与防掉单的终极策略“掉单”是IAP开发中最头疼的问题之一用户付了钱但由于网络中断、App崩溃、验证失败等原因服务器没能成功记录并发放商品。StoreKit 2的机制大大降低了概率但结合用户绑定我们能做得更保险。5.1 利用AppTransaction绑定设备与用户AppTransaction包含了App首次下载或购买时的一些元数据其中包含一个重要的originalAppVersion属性。虽然它不直接是用户ID但可以用于生成一个与设备和App安装相关的唯一标识符的组成部分。import StoreKit MainActor class UserBindingManager: ObservableObject { Published var appTransactionID: String? func setupAppTransaction() async { do { // 获取AppTransaction并验证 let appTransaction try await AppTransaction.shared switch appTransaction { case .verified(let verifiedAppTransaction): // 这是一个可靠的标识符基础 let uniqueDeviceAppHash \(verifiedAppTransaction.originalPurchaseDate.timeIntervalSince1970)_\(verifiedAppTransaction.originalAppVersion) // 你可以将此hash与你的服务器用户ID关联存储 self.appTransactionID uniqueDeviceAppHash await sendToServer(userId: getCurrentUserId(), deviceAppHash: uniqueDeviceAppHash) case .unverified(let unverifiedAppTransaction, let error): // 验证失败不能信任此数据 print(AppTransaction验证失败: \(error)。数据: \(unverifiedAppTransaction)) self.appTransactionID nil } } catch { print(获取AppTransaction失败: \(error)) } } }这个deviceAppHash可以和你后台的用户系统绑定。当发生交易时除了交易本身的信息也把这个hash传给服务器。这样即使交易验证回调因为极端情况丢失服务器也可以通过这个hash关联到具体的设备和用户结合后续补单查询极大降低掉单风险。5.2 坚不可摧的Transaction监听与补单机制这是防掉单的核心。你需要建立一个全局的、持久化的监听任务。import StoreKit import BackgroundTasks // 用于后台任务 MainActor class TransactionObserver { static let shared TransactionObserver() private var updatesTask: TaskVoid, Never? nil func startObserving() { guard updatesTask nil else { return } updatesTask Task.detached(priority: .background) { for await update in Transaction.updates { // 这个循环会持续监听交易状态更新 await self.handle(transactionUpdate: update) } } } private func handle(transactionUpdate update: Transaction.TransactionUpdate) async { switch update { case .verified(let transaction): // 交易已验证通过这是最可靠的状态 await self.processValidatedTransaction(transaction) // 关键步骤完成交易告诉StoreKit可以结束了 await transaction.finish() case .unverified(let transaction, let error): // 交易验证失败可能存在篡改风险 print(收到未验证的交易更新ID: \(transaction.id), 错误: \(error)) // 通常不发放商品并记录日志用于排查 await transaction.finish() // 仍然需要结束它 } } private func processValidatedTransaction(_ transaction: Transaction) async { let transactionId transaction.id let productId transaction.productID let purchaseDate transaction.purchaseDate // 1. 检查是否已处理过防重入 if await hasTransactionBeenProcessedOnServer(transactionId) { print(交易 \(transactionId) 已处理跳过。) return } // 2. 获取或生成与当前App/设备关联的用户标识结合上文AppTransaction方案 let userDeviceIdentifier await getCurrentUserDeviceIdentifier() // 3. 调用服务器API传递交易ID、商品ID、购买时间、用户设备标识 let success await sendToServerForDelivery( transactionId: transactionId, productId: productId, purchaseDate: purchaseDate, userDeviceIdentifier: userDeviceIdentifier, transactionJsonString: transaction.jsonRepresentation // 可选传递完整收据信息供服务器二次验证 ) // 4. 根据服务器响应处理 if success { print(商品发放成功交易ID: \(transactionId)) // 更新本地状态标记为已处理 await markTransactionAsProcessedLocally(transactionId) } else { print(警告商品发放失败交易ID: \(transactionId)。需要加入重试队列。) // 加入一个失败队列通过后台任务或下次启动时重试 await addToRetryQueue(transaction) } // 5. 特别处理退款撤销状态 if transaction.transactionState .revoked { print(交易 \(transactionId) 已被撤销退款。) await sendToServerForRevocation(transactionId: transactionId, productId: productId) // 服务器应执行相应的商品收回逻辑如扣除游戏币、取消VIP权限 } } }防掉单策略总结持久化监听在App启动后立即启动Transaction.updates监听任务并确保其在整个App生命周期内存活。服务器幂等服务器端处理交易逻辑必须是幂等的即同一笔transaction.id多次请求结果一致只发放一次商品。这是应对网络重试、App崩溃重启后监听任务重新收到同一交易的关键。本地去重在客户端也可以做一个简单的已处理交易ID缓存避免不必要的网络请求。失败重试对于发放商品失败的交易不能简单丢弃。应将其存入一个持久化的队列如UserDefaults或本地数据库并建立重试机制例如每次App启动、网络恢复时重试。结合用户标识将交易与AppTransaction衍生的设备标识或你自身的用户系统绑定。这样即使极端情况下某笔交易的监听彻底丢失你也可以通过定期调用Transaction.all来“扫表”找出当前用户所有未处理的、已完成的.purchased交易进行补单。这可以作为最后一道防线。5.3 后台处理与静默补单对于订阅类商品或需要确保关键交付的场景可以结合BGAppRefreshTask实现后台静默补单。在AppDelegate或Scene中注册后台任务。在后台任务被系统唤醒时执行以下操作调用Transaction.all获取最新交易列表。与服务器同步找出本地记录中状态为“未处理”或服务器缺失的交易。调用Transaction(verificationResult:)验证这些交易并尝试重新向服务器提交。无论成功与否都调用setTaskCompleted(success:)告知系统。这样即使用户在购买后立即关闭了App系统也有机会在后台完成商品交付。6. 完整集成架构与最佳实践将这三步曲融合到一个生产级应用中需要一个清晰的架构。我推荐采用“状态中心”的模式。6.1 推荐架构设计┌─────────────────────────────────────────────────────────────┐ │ Client (iOS App) │ ├───────────────┬─────────────────┬───────────────────────────┤ │ StoreKit │ Local Cache │ User Interface │ │ Manager │ (Core Data) │ (订单页、退款入口) │ ├───────────────┼─────────────────┼───────────────────────────┤ │ - 监听Updates │ - 缓存Transaction│ - 展示订单历史 │ │ - 处理退款请求│ - 记录处理状态 │ - 触发退款流程 │ │ - 查询All │ - 存储失败队列 │ - 绑定用户状态显示 │ └───────────────┴─────────────────┴───────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Backend Server │ ├─────────────────────────────────────────────────────────────┤ │ - 验证收据 (JWS格式) │ │ - 幂等处理交易 发放商品 │ │ - 处理退款撤销通知 │ │ - 管理用户-交易绑定关系 │ └─────────────────────────────────────────────────────────────┘核心管理器伪代码结构class IAPManager: ObservableObject { static let shared IAPManager() private let transactionObserver TransactionObserver() private let localCache IAPLocalCache() Published var currentUserTransactions: [Transaction] [] Published var isRefundRequestInProgress false func configure() async { // 1. 启动全局监听 transactionObserver.startObserving() // 2. 验证并绑定AppTransaction await bindAppTransactionToUser() // 3. 加载本地缓存的历史订单为了快速UI展示 loadCachedTransactions() // 4. 从网络拉取最新全量订单并更新缓存 await refreshTransactionHistoryFromNetwork() // 5. 检查并处理失败队列中的交易 await processFailedTransactionQueue() } func requestRefund(for transaction: Transaction) async - RefundRequestStatus { // ... 实现退款逻辑 } func refreshHistory() async { // ... 刷新订单列表 } // ... 其他私有方法 }6.2 避坑指南与实操心得沙盒环境与生产环境退款功能在沙盒环境下的行为可能与生产环境不同。苹果为沙盒退款提供了专门的测试流程通常有更短的审批时间。务必在沙盒环境充分测试退款UI流程和状态回调。退款资格与频率苹果对退款有不成文的“信用”系统。一个账户频繁退款可能会被限制功能。你的App内集成退款是为了提供便利但不能鼓励滥用。可以在用户点击退款前友好地提示退款政策和可能的影响。交易验证的服务器职责尽管StoreKit 2提供了本地验证但对于涉及虚拟货币、解锁关键功能等敏感操作服务器端必须使用苹果的JWSJSON Web Signature验证接口进行二次验证。客户端传过去的transaction.jsonRepresentation或transaction.jwsRepresentation就是用于这个目的。永远不要只相信客户端的状态。订阅状态处理历史订单查询 (Transaction.all) 包含订阅的购买、续期和过期/退款记录。但对于用户当前的订阅状态更推荐使用Product.SubscriptionInfo.Status相关API来获取它们提供了更结构化的续期、升级、降级信息。用户隐私展示订单历史时注意用户隐私。避免在列表中过度显示敏感信息如原始收据字符串。确保你的隐私政策涵盖了这些数据的收集和使用。网络与错误处理所有StoreKit 2 API都是网络请求。必须做好全面的错误处理无网络、超时、服务器错误等并提供重试机制和友好的用户提示。兼容StoreKit 1如果你的App尚未完全迁移到StoreKit 2需要维护两套逻辑。对于历史订单查询可以考虑先展示StoreKit 2获取的订单对于更早的、StoreKit 2无法获取的订单可以引导用户查看邮箱或通过服务器查询如果你之前有服务器端收据存储的话。7. 常见问题排查与调试技巧即使按照最佳实践在实际开发中还是会遇到各种问题。这里记录一些我踩过的坑和解决方法。问题1调用beginRefundRequest立刻返回错误提示平台不支持。原因最可能的原因是在Mac Catalyst构建的App中调用此API或者设备系统版本低于iOS/iPadOS 15.0, macOS 12.0。解决使用available进行API可用性检查并在不支持的环境下隐藏退款按钮或给出提示。if #available(iOS 15.0, *), #available(macCatalyst, unavailable) { // 显示退款按钮 } else { // 隐藏或禁用提示“请在iOS 15或更高版本的iPhone/iPad上使用此功能” }问题2Transaction.all在真机上返回空但在沙盒正常。原因测试用的真机设备登录的Apple ID从未在此App的生产版本上有过任何购买包括免费项目。Transaction.all查询的是生产环境记录。解决要测试生产环境逻辑非常困难。通常我们依赖沙盒环境进行全流程测试。确保你的沙盒测试账号在沙盒环境下有完整的购买记录。对于生产环境的问题排查只能依赖用户提供的原始交易ID或收据在服务器端通过苹果的验证接口进行查询。问题3监听不到Transaction.updates用户购买后商品没发放。排查步骤检查监听任务是否启动确保在App启动早期如App的init或第一个视图的.task修饰符内就启动了监听任务并且该任务没有被意外取消。检查交易是否已完成用户可能在购买时遇到了“等待中”如需要家庭共享确认状态。此时交易不会立即进入.verified流。你需要同时处理Transaction.all中的.pending状态交易。检查网络和服务器监听能收到更新但商品发放失败。查看客户端日志和服务器日志确认网络请求是否发出、服务器验证收据是否成功、业务逻辑是否执行。极端情况交易丢失如果以上都正常可能是极罕见的StoreKit内部错误。此时最后的保障就是“补单机制”定期如每次App启动运行一个后台任务获取Transaction.all与服务器核对补发漏掉的商品。问题4退款申请提交后如何知道退款结果流程用户提交申请 → 苹果审核时间不定→ 审核通过后原交易的transactionState会变为.revoked并且revocationDate会被设置。同时该交易会出现在Transaction.updates流中。实现因此你的全局Transaction.updates监听器必须能处理.revoked状态。一旦收到立即同步给服务器服务器执行收回商品或权益的操作如扣除游戏币、取消VIP身份。重要即使退款苹果的分成通常不会退回给开发者所以你的服务器必须执行“收回”逻辑否则会造成资产损失。问题5服务器如何验证JWS格式的收据客户端将transaction.jwsRepresentation一个字符串发送给服务器。服务器端不需要连接苹果服务器进行二次验证对于StoreKit 2。JWS本身是经过签名的你可以使用苹果提供的公钥可以从苹果官网获取来验证这个签名的有效性并直接解析JWS payload一个JSON对象来获取交易信息。这比StoreKit 1时代需要频繁调用苹果验证服务器要高效和可靠得多。各大后端语言都有成熟的JWS验证库。将这三步曲完整地集成到你的App中无疑会增加前期的开发工作量。但从长远来看它构建的是一个更健壮、更用户友好、更能赢得信任的内购体系。它把支付的后端支持从单纯的“收款发货”扩展到了“订单管理”和“售后服务”让整个虚拟商品消费链路变得更加完整和健康。从WWDC21到现在这套API已经相当稳定是时候为你的用户提供这份“高端”服务了。 
长河君 · 2026/8/13 22:41:29 · 阅读 1.2k iOS内购进阶：StoreKit 2实现App内退款、订单查询与防掉单
1. 项目概述iOS内购的“最后一公里”难题做iOS开发这么多年内购In-App Purchase IAP这套流程从沙盒测试到上架审核大家应该都轻车熟路了。但不知道你有没有遇到过这样的场景用户怒气冲冲地找过来说“我刚买的月卡怎么没到账”或者“我孩子误操作买了东西能退吗”。这时候如果你只能让用户去翻邮箱找苹果的收据或者冷冰冰地回复一句“请自行联系苹果客服申请退款”那用户体验基本就跌到谷底了。WWDC21上苹果悄然但有力地推出了几项StoreKit 2的更新在我看来这恰恰是为我们开发者补上了内购生态的“最后一公里”——App内退款、历史订单查询以及更可靠的用户绑定防掉单机制。以前这些功能要么依赖复杂的服务器验证要么根本不在开发者的可控范围内。现在借助新的StoreKit API我们终于可以把这些能力集成到自己的App里给用户提供一个闭环的、无缝的消费体验。这不仅仅是几个新API更是一种产品思维和用户服务理念的升级。想象一下用户能在你的App里一键查询所有购买记录、自助提交退款申请、并且每一次消费都能稳稳地和自己的账号绑定这能极大提升用户信任感和满意度减少客服压力甚至降低因支付纠纷导致的差评。接下来我就结合WWDC21的内容和后续的实践把这“三步曲”的里里外外、坑坑洼洼都给你捋清楚。2. 核心能力拆解新StoreKit 2带来了什么StoreKit 2并非在WWDC21上首次亮相但这一届大会确实为其添加了至关重要的“售后服务”拼图。要理解这三步曲我们得先看看手中的“新工具”有哪些。2.1 Transaction交易对象的进化StoreKit 2的核心是新的Transaction模型Transaction协议和VerificationResult枚举。它取代了旧版基于SKPaymentTransaction的繁琐流程。每一个Transaction都包含了一次购买的完整、可验证的信息并且有一个全局唯一的id。这个id和苹果服务器上的交易记录直接对应是我们实现后续所有功能的基础。注意StoreKit 1和StoreKit 2的API可以共存但数据模型不互通。如果你要迁移需要处理新旧两套交易记录的映射问题尤其是处理那些“掉单”的历史订单。2.2 关键新增API一览退款申请引入了beginRefundRequest(for:in:)方法。开发者可以在App内针对某个仍在退款有效期内的Transaction发起退款流程。系统会弹出一个原生界面引导用户完成向苹果提交退款申请的步骤。历史订单查询提供了Transaction.all这个异步序列。通过它我们可以获取当前用户App Store账户在此App下的所有历史交易记录包括已经消费的、订阅的、甚至已经退款的。这是实现“订单中心”功能的数据基础。强化授权与监听通过AppTransaction可以获取应用下载时的原始交易信息并结合Transaction.updates这个Task来监听实时交易状态变化。这为更精准地绑定用户和防止掉单提供了更可靠的机制。3. 第一步App内集成退款流程以前退款是用户和苹果之间的事。用户需要记住购买时间、商品信息然后到苹果官网或报告问题页面reportaproblem.apple.com去操作流程割裂且复杂。现在我们可以把这个入口集成到App内。3.1 实现原理与前置条件App内退款本质上是一个“引导”流程。开发者调用API后系统会接管并弹出原生界面用户在此界面确认退款理由并提交。最终审批权仍在苹果退款金额也会原路返回至用户的支付账户。整个过程你的App无法知道用户具体选择了什么退款理由也无法干预审批结果但可以获知退款申请是否已成功提交给苹果系统。前置条件至关重要仅支持使用StoreKit 2 API处理的交易即Transaction对象。交易必须处于可退款状态。通常苹果对大部分内购项目提供购买后90天内的退款窗口但具体政策以苹果为准。API会自行校验。用户设备需运行iOS 15.0, iPadOS 15.0, macOS 12.0或更高版本。该功能不支持在Mac Catalyst应用中使用。3.2 代码实操与状态处理假设我们有一个订单列表每个订单项对应一个Transaction。当用户点击“申请退款”按钮时import StoreKit MainActor func requestRefund(for transactionId: UInt64) async { // 1. 根据transactionId获取对应的Transaction对象 // 通常你需要维护一个当前用户的Transaction数组 guard let transaction await Transaction(verificationResult: .verified(.init(id: transactionId))) else { // 处理未找到交易的情况 showAlert(title: 错误, message: 未找到对应的购买记录。) return } // 2. 检查当前交易状态是否可退款非必须API内部会校验但提前判断可提升体验 guard transaction.refund ! .notAvailable else { showAlert(title: 无法退款, message: 该购买记录不符合退款条件或已超过退款期限。) return } // 3. 调用退款API指定在哪个windowScene中弹出界面 guard let windowScene UIApplication.shared.connectedScenes.first as? UIWindowScene else { return } do { // 这是关键调用 let refundStatus try await Transaction.beginRefundRequest( for: transaction.id, in: windowScene ) // 4. 处理退款申请提交结果 switch refundStatus { case .userCancelled: // 用户在原生退款界面中取消了操作 print(用户取消了退款申请。) case .success: // 退款申请已成功提交至苹果系统 showAlert(title: 已提交, message: 您的退款申请已提交请等待苹果审核。) // 重要更新本地UI或状态例如将订单标记为“退款申请中” updateTransactionLocalState(transactionId, newState: .refundRequested) unknown default: break } } catch { // 处理错误例如网络问题、交易状态不符等 showAlert(title: 提交失败, message: 退款申请提交失败\(error.localizedDescription)) } }实操心得状态管理beginRefundRequest返回的RefundRequestStatus只代表“申请提交”是否成功不代表退款是否获批。获批结果需要通过监听Transaction.updates或定期查询Transaction.all来获取。当交易状态更新为revoked时表示退款已获批准并处理。UI时机这个API会触发一个系统模态页面。请确保在用户操作如点击按钮后直接调用不要在其他动画或转场过程中调用以免界面层级混乱。错误处理最常见的错误是StoreKitError.unsupportedPlatform在Catalyst上调用和StoreKitError.refundNotAvailable。务必做好用户友好的错误提示。4. 第二步构建用户历史订单查询系统有了Transaction.all为用户打造一个“我的订单”页面变得前所未有的简单。这个异步序列返回的是当前App Store账户在此App下的所有交易按时间倒序排列。4.1 获取与展示所有历史交易import StoreKit import SwiftUI // 示例使用SwiftUI struct OrderHistoryView: View { State private var allTransactions: [Transaction] [] State private var isLoading false State private var errorMessage: String? var body: some View { NavigationView { List { if isLoading { ProgressView(加载订单历史...) } else if let error errorMessage { Text(加载失败: \(error)) .foregroundColor(.red) } else { ForEach(allTransactions, id: \.id) { transaction in TransactionRow(transaction: transaction) } } } .navigationTitle(购买记录) .task { await loadTransactionHistory() } .refreshable { await loadTransactionHistory() } } } private func loadTransactionHistory() async { isLoading true errorMessage nil do { // 关键调用获取所有交易 var transactions: [Transaction] [] for await transaction in Transaction.all { // 这里可以对transaction进行验证但.all返回的已经是验证过的序列 // 通常我们只处理验证通过的.verified switch transaction { case .verified(let verifiedTx): transactions.append(verifiedTx) case .unverified(_, let error): // 记录或忽略未验证的交易 print(发现未验证的交易错误: \(error)) } } // 按购买日期倒序排列 self.allTransactions transactions.sorted { $0.purchaseDate $1.purchaseDate } } catch { self.errorMessage error.localizedDescription } isLoading false } } struct TransactionRow: View { let transaction: Transaction var body: some View { VStack(alignment: .leading, spacing: 4) { HStack { Text(transaction.productID) .font(.headline) Spacer() // 显示交易状态 StatusBadge(state: transaction.transactionState) } Text(金额: \(transaction.currencyCode) \(transaction.price, format: .number)) .font(.caption) .foregroundColor(.secondary) Text(日期: \(transaction.purchaseDate, format: .dateTime)) .font(.caption) .foregroundColor(.secondary) if let revocationDate transaction.revocationDate { Text(退款时间: \(revocationDate, format: .dateTime)) .font(.caption) .foregroundColor(.orange) } } .padding(.vertical, 4) } }4.2 关键细节与性能优化数据量Transaction.all返回的数据可能非常多特别是对于老用户或高频消费App。务必做分页或虚拟滚动不要试图一次性渲染成千上万条记录。虽然API是异步流但内存中持有大量Transaction对象也可能有压力。验证开销Transaction.all返回的序列中的每一项已经过初步验证。对于展示列表使用.verified的数据即可。只有当需要对某笔交易进行关键业务操作如发放虚拟商品时才需要调用Transaction(verificationResult:)进行独立的、更严格的验证。本地缓存考虑到网络和性能可以对获取到的交易列表进行本地缓存例如使用Core Data或SQLite。但需要建立缓存更新机制例如在App启动、用户下拉刷新、或收到Transaction.updates通知时增量更新缓存。状态展示Transaction的transactionState属性非常重要它包含了.purchased,.revoked已退款,.pending等待中如需要家庭共享确认等状态。在UI上清晰地区分这些状态能减少用户困惑。常见问题排查问题Transaction.all返回空数组。排查首先确认设备登录的App Store账号是否有购买记录。其次检查是否在Sandbox环境下测试沙盒环境的交易记录是独立的。确保用测试账号在沙盒环境完成过购买。问题交易记录加载非常慢。排查首次加载或记录非常多时可能较慢。这是网络请求。务必在UI上显示加载状态并考虑实现本地缓存首次加载后后续展示缓存数据后台静默更新。5. 第三步绑定用户与防掉单的终极策略“掉单”是IAP开发中最头疼的问题之一用户付了钱但由于网络中断、App崩溃、验证失败等原因服务器没能成功记录并发放商品。StoreKit 2的机制大大降低了概率但结合用户绑定我们能做得更保险。5.1 利用AppTransaction绑定设备与用户AppTransaction包含了App首次下载或购买时的一些元数据其中包含一个重要的originalAppVersion属性。虽然它不直接是用户ID但可以用于生成一个与设备和App安装相关的唯一标识符的组成部分。import StoreKit MainActor class UserBindingManager: ObservableObject { Published var appTransactionID: String? func setupAppTransaction() async { do { // 获取AppTransaction并验证 let appTransaction try await AppTransaction.shared switch appTransaction { case .verified(let verifiedAppTransaction): // 这是一个可靠的标识符基础 let uniqueDeviceAppHash \(verifiedAppTransaction.originalPurchaseDate.timeIntervalSince1970)_\(verifiedAppTransaction.originalAppVersion) // 你可以将此hash与你的服务器用户ID关联存储 self.appTransactionID uniqueDeviceAppHash await sendToServer(userId: getCurrentUserId(), deviceAppHash: uniqueDeviceAppHash) case .unverified(let unverifiedAppTransaction, let error): // 验证失败不能信任此数据 print(AppTransaction验证失败: \(error)。数据: \(unverifiedAppTransaction)) self.appTransactionID nil } } catch { print(获取AppTransaction失败: \(error)) } } }这个deviceAppHash可以和你后台的用户系统绑定。当发生交易时除了交易本身的信息也把这个hash传给服务器。这样即使交易验证回调因为极端情况丢失服务器也可以通过这个hash关联到具体的设备和用户结合后续补单查询极大降低掉单风险。5.2 坚不可摧的Transaction监听与补单机制这是防掉单的核心。你需要建立一个全局的、持久化的监听任务。import StoreKit import BackgroundTasks // 用于后台任务 MainActor class TransactionObserver { static let shared TransactionObserver() private var updatesTask: TaskVoid, Never? nil func startObserving() { guard updatesTask nil else { return } updatesTask Task.detached(priority: .background) { for await update in Transaction.updates { // 这个循环会持续监听交易状态更新 await self.handle(transactionUpdate: update) } } } private func handle(transactionUpdate update: Transaction.TransactionUpdate) async { switch update { case .verified(let transaction): // 交易已验证通过这是最可靠的状态 await self.processValidatedTransaction(transaction) // 关键步骤完成交易告诉StoreKit可以结束了 await transaction.finish() case .unverified(let transaction, let error): // 交易验证失败可能存在篡改风险 print(收到未验证的交易更新ID: \(transaction.id), 错误: \(error)) // 通常不发放商品并记录日志用于排查 await transaction.finish() // 仍然需要结束它 } } private func processValidatedTransaction(_ transaction: Transaction) async { let transactionId transaction.id let productId transaction.productID let purchaseDate transaction.purchaseDate // 1. 检查是否已处理过防重入 if await hasTransactionBeenProcessedOnServer(transactionId) { print(交易 \(transactionId) 已处理跳过。) return } // 2. 获取或生成与当前App/设备关联的用户标识结合上文AppTransaction方案 let userDeviceIdentifier await getCurrentUserDeviceIdentifier() // 3. 调用服务器API传递交易ID、商品ID、购买时间、用户设备标识 let success await sendToServerForDelivery( transactionId: transactionId, productId: productId, purchaseDate: purchaseDate, userDeviceIdentifier: userDeviceIdentifier, transactionJsonString: transaction.jsonRepresentation // 可选传递完整收据信息供服务器二次验证 ) // 4. 根据服务器响应处理 if success { print(商品发放成功交易ID: \(transactionId)) // 更新本地状态标记为已处理 await markTransactionAsProcessedLocally(transactionId) } else { print(警告商品发放失败交易ID: \(transactionId)。需要加入重试队列。) // 加入一个失败队列通过后台任务或下次启动时重试 await addToRetryQueue(transaction) } // 5. 特别处理退款撤销状态 if transaction.transactionState .revoked { print(交易 \(transactionId) 已被撤销退款。) await sendToServerForRevocation(transactionId: transactionId, productId: productId) // 服务器应执行相应的商品收回逻辑如扣除游戏币、取消VIP权限 } } }防掉单策略总结持久化监听在App启动后立即启动Transaction.updates监听任务并确保其在整个App生命周期内存活。服务器幂等服务器端处理交易逻辑必须是幂等的即同一笔transaction.id多次请求结果一致只发放一次商品。这是应对网络重试、App崩溃重启后监听任务重新收到同一交易的关键。本地去重在客户端也可以做一个简单的已处理交易ID缓存避免不必要的网络请求。失败重试对于发放商品失败的交易不能简单丢弃。应将其存入一个持久化的队列如UserDefaults或本地数据库并建立重试机制例如每次App启动、网络恢复时重试。结合用户标识将交易与AppTransaction衍生的设备标识或你自身的用户系统绑定。这样即使极端情况下某笔交易的监听彻底丢失你也可以通过定期调用Transaction.all来“扫表”找出当前用户所有未处理的、已完成的.purchased交易进行补单。这可以作为最后一道防线。5.3 后台处理与静默补单对于订阅类商品或需要确保关键交付的场景可以结合BGAppRefreshTask实现后台静默补单。在AppDelegate或Scene中注册后台任务。在后台任务被系统唤醒时执行以下操作调用Transaction.all获取最新交易列表。与服务器同步找出本地记录中状态为“未处理”或服务器缺失的交易。调用Transaction(verificationResult:)验证这些交易并尝试重新向服务器提交。无论成功与否都调用setTaskCompleted(success:)告知系统。这样即使用户在购买后立即关闭了App系统也有机会在后台完成商品交付。6. 完整集成架构与最佳实践将这三步曲融合到一个生产级应用中需要一个清晰的架构。我推荐采用“状态中心”的模式。6.1 推荐架构设计┌─────────────────────────────────────────────────────────────┐ │ Client (iOS App) │ ├───────────────┬─────────────────┬───────────────────────────┤ │ StoreKit │ Local Cache │ User Interface │ │ Manager │ (Core Data) │ (订单页、退款入口) │ ├───────────────┼─────────────────┼───────────────────────────┤ │ - 监听Updates │ - 缓存Transaction│ - 展示订单历史 │ │ - 处理退款请求│ - 记录处理状态 │ - 触发退款流程 │ │ - 查询All │ - 存储失败队列 │ - 绑定用户状态显示 │ └───────────────┴─────────────────┴───────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Backend Server │ ├─────────────────────────────────────────────────────────────┤ │ - 验证收据 (JWS格式) │ │ - 幂等处理交易 发放商品 │ │ - 处理退款撤销通知 │ │ - 管理用户-交易绑定关系 │ └─────────────────────────────────────────────────────────────┘核心管理器伪代码结构class IAPManager: ObservableObject { static let shared IAPManager() private let transactionObserver TransactionObserver() private let localCache IAPLocalCache() Published var currentUserTransactions: [Transaction] [] Published var isRefundRequestInProgress false func configure() async { // 1. 启动全局监听 transactionObserver.startObserving() // 2. 验证并绑定AppTransaction await bindAppTransactionToUser() // 3. 加载本地缓存的历史订单为了快速UI展示 loadCachedTransactions() // 4. 从网络拉取最新全量订单并更新缓存 await refreshTransactionHistoryFromNetwork() // 5. 检查并处理失败队列中的交易 await processFailedTransactionQueue() } func requestRefund(for transaction: Transaction) async - RefundRequestStatus { // ... 实现退款逻辑 } func refreshHistory() async { // ... 刷新订单列表 } // ... 其他私有方法 }6.2 避坑指南与实操心得沙盒环境与生产环境退款功能在沙盒环境下的行为可能与生产环境不同。苹果为沙盒退款提供了专门的测试流程通常有更短的审批时间。务必在沙盒环境充分测试退款UI流程和状态回调。退款资格与频率苹果对退款有不成文的“信用”系统。一个账户频繁退款可能会被限制功能。你的App内集成退款是为了提供便利但不能鼓励滥用。可以在用户点击退款前友好地提示退款政策和可能的影响。交易验证的服务器职责尽管StoreKit 2提供了本地验证但对于涉及虚拟货币、解锁关键功能等敏感操作服务器端必须使用苹果的JWSJSON Web Signature验证接口进行二次验证。客户端传过去的transaction.jsonRepresentation或transaction.jwsRepresentation就是用于这个目的。永远不要只相信客户端的状态。订阅状态处理历史订单查询 (Transaction.all) 包含订阅的购买、续期和过期/退款记录。但对于用户当前的订阅状态更推荐使用Product.SubscriptionInfo.Status相关API来获取它们提供了更结构化的续期、升级、降级信息。用户隐私展示订单历史时注意用户隐私。避免在列表中过度显示敏感信息如原始收据字符串。确保你的隐私政策涵盖了这些数据的收集和使用。网络与错误处理所有StoreKit 2 API都是网络请求。必须做好全面的错误处理无网络、超时、服务器错误等并提供重试机制和友好的用户提示。兼容StoreKit 1如果你的App尚未完全迁移到StoreKit 2需要维护两套逻辑。对于历史订单查询可以考虑先展示StoreKit 2获取的订单对于更早的、StoreKit 2无法获取的订单可以引导用户查看邮箱或通过服务器查询如果你之前有服务器端收据存储的话。7. 常见问题排查与调试技巧即使按照最佳实践在实际开发中还是会遇到各种问题。这里记录一些我踩过的坑和解决方法。问题1调用beginRefundRequest立刻返回错误提示平台不支持。原因最可能的原因是在Mac Catalyst构建的App中调用此API或者设备系统版本低于iOS/iPadOS 15.0, macOS 12.0。解决使用available进行API可用性检查并在不支持的环境下隐藏退款按钮或给出提示。if #available(iOS 15.0, *), #available(macCatalyst, unavailable) { // 显示退款按钮 } else { // 隐藏或禁用提示“请在iOS 15或更高版本的iPhone/iPad上使用此功能” }问题2Transaction.all在真机上返回空但在沙盒正常。原因测试用的真机设备登录的Apple ID从未在此App的生产版本上有过任何购买包括免费项目。Transaction.all查询的是生产环境记录。解决要测试生产环境逻辑非常困难。通常我们依赖沙盒环境进行全流程测试。确保你的沙盒测试账号在沙盒环境下有完整的购买记录。对于生产环境的问题排查只能依赖用户提供的原始交易ID或收据在服务器端通过苹果的验证接口进行查询。问题3监听不到Transaction.updates用户购买后商品没发放。排查步骤检查监听任务是否启动确保在App启动早期如App的init或第一个视图的.task修饰符内就启动了监听任务并且该任务没有被意外取消。检查交易是否已完成用户可能在购买时遇到了“等待中”如需要家庭共享确认状态。此时交易不会立即进入.verified流。你需要同时处理Transaction.all中的.pending状态交易。检查网络和服务器监听能收到更新但商品发放失败。查看客户端日志和服务器日志确认网络请求是否发出、服务器验证收据是否成功、业务逻辑是否执行。极端情况交易丢失如果以上都正常可能是极罕见的StoreKit内部错误。此时最后的保障就是“补单机制”定期如每次App启动运行一个后台任务获取Transaction.all与服务器核对补发漏掉的商品。问题4退款申请提交后如何知道退款结果流程用户提交申请 → 苹果审核时间不定→ 审核通过后原交易的transactionState会变为.revoked并且revocationDate会被设置。同时该交易会出现在Transaction.updates流中。实现因此你的全局Transaction.updates监听器必须能处理.revoked状态。一旦收到立即同步给服务器服务器执行收回商品或权益的操作如扣除游戏币、取消VIP身份。重要即使退款苹果的分成通常不会退回给开发者所以你的服务器必须执行“收回”逻辑否则会造成资产损失。问题5服务器如何验证JWS格式的收据客户端将transaction.jwsRepresentation一个字符串发送给服务器。服务器端不需要连接苹果服务器进行二次验证对于StoreKit 2。JWS本身是经过签名的你可以使用苹果提供的公钥可以从苹果官网获取来验证这个签名的有效性并直接解析JWS payload一个JSON对象来获取交易信息。这比StoreKit 1时代需要频繁调用苹果验证服务器要高效和可靠得多。各大后端语言都有成熟的JWS验证库。将这三步曲完整地集成到你的App中无疑会增加前期的开发工作量。但从长远来看它构建的是一个更健壮、更用户友好、更能赢得信任的内购体系。它把支付的后端支持从单纯的“收款发货”扩展到了“订单管理”和“售后服务”让整个虚拟商品消费链路变得更加完整和健康。从WWDC21到现在这套API已经相当稳定是时候为你的用户提供这份“高端”服务了。