CargoBay错误处理完全指南：深入理解16种状态码和错误类型

CargoBay错误处理完全指南：深入理解16种状态码和错误类型

【免费下载链接】CargoBayThe Essential StoreKit Companion项目地址: https://gitcode.com/gh_mirrors/ca/CargoBay

CargoBay是iOS应用内购买的强大助手，它简化了StoreKit的复杂性，提供了完整的收据验证和交易管理功能。作为iOS开发者，处理应用内购买错误是确保应用稳定性和用户体验的关键。本文将为您全面解析CargoBay的错误处理机制，涵盖所有16种状态码和错误类型，帮助您快速定位和解决问题。💡

📋 CargoBay错误处理概述

CargoBay采用系统化的错误处理机制，将所有错误统一到CargoBayErrorDomain域中。这个设计让开发者能够轻松识别和处理各种应用内购买问题。错误分为两大类：自定义错误码和收据验证状态码。

核心错误域定义

在CargoBay.h文件中，CargoBay定义了统一的错误域：

extern NSString * const CargoBayErrorDomain;

这个统一的错误域确保了所有错误都在同一个命名空间下，便于集中处理。

🔍 6大自定义错误类型详解

CargoBay定义了6个核心自定义错误码，覆盖了应用内购买的主要验证场景：

1. 购买信息与收据不匹配错误

• 错误码:CargoBayErrorPurchaseInfoDoesNotMatchReceipt(1)
• 触发条件: 购买信息的Bundle ID、产品ID、数量或项目ID与收据不匹配
• 常见原因: 收据被篡改、应用Bundle ID更改、产品信息不一致

2. 交易与购买信息不匹配错误

• 错误码:CargoBayErrorTransactionDoesNotMatchesPurchaseInfo(2)
• 触发条件: 交易对象与提取的购买信息不一致
• 检查项: 产品ID、数量、交易ID的匹配性

3. 无法从交易收据提取购买信息错误

• 错误码:CargoBayErrorCannotExtractPurchaseInfoFromTransactionReceipt(3)
• 触发条件: 收据数据解析失败或签名验证失败
• 解决方案: 检查收据数据的完整性和有效性

4. 交易状态不正确错误

• 错误码:CargoBayErrorTransactionNotInPurchasedOrRestoredState(4)
• 触发条件: 交易不在已购买或已恢复状态
• 适用场景: 仅验证已完成的交易

5. 交易对象无效错误

• 错误码:CargoBayErrorTransactionNotValid(5)
• 触发条件: 交易对象为空或收据数据无效
• 预防措施: 确保交易对象完整性和收据可用性

6. 交易ID不唯一错误

• 错误码:CargoBayErrorTransactionIDNotUnique(6)
• 触发条件: 交易ID重复检测失败
• 重要性: 防止重复处理同一交易

📊 8大收据验证状态码解析

CargoBay还定义了8个收据验证状态码，这些直接对应苹果服务器的响应：

收据验证成功状态

• 状态码:CargoBayStatusOK(0)
• 含义: 收据验证成功，交易合法有效

常见验证失败状态码

特殊状态码处理

订阅过期状态

• 状态码:CargoBayStatusReceiptValidButSubscriptionExpired(21006)
• 含义: 收据有效但订阅已过期
• 处理建议: 提示用户续订

环境配置错误状态

🛠️ 错误处理最佳实践

1. 统一错误处理模式

CargoBay的所有API都采用统一的错误处理模式：

[[CargoBay sharedManager] verifyTransaction:transaction password:nil success:^(NSDictionary *receipt) { // 处理成功 } failure:^(NSError *error) { // 统一错误处理 [self handleCargoBayError:error]; }];

2. 错误分类处理策略

在CargoBay.m中，错误处理分为几个层次：

// 网络错误处理 failure:^(__unused AFHTTPRequestOperation *operation, NSError *error) { if (failure) { failure(error); } }]; // 服务器状态码处理 switch (status) { case CargoBayStatusOK: // 成功处理 break; case CాలుBayStatusSandboxReceiptSentToProduction: // 环境切换 break; default: // 创建错误对象 NSError *error = [[NSError alloc] initWithDomain:CargoBayErrorDomain code:status userInfo:userInfo]; failure(error); break; }

3. 详细的错误信息

每个错误都包含详细的本地化描述和失败原因：

NSDictionary *userInfo = [NSMutableDictionary dictionary]; [userInfo setValue:[NSString stringWithFormat:NSLocalizedStringFromTable( @"Purchase info does not match receipt because purchase info's bundle ID (%@) does not match receipt's bundle ID (%@).", @"CargoBay", nil), purchaseInfoBundleID, receiptBundleID] forKey:NSLocalizedDescriptionKey]; [userInfo setValue:[NSString stringWithFormat:NSLocalizedStringFromTable( @"Purchase info's bundle ID (%@) does not match receipt's bundle ID (%@).", @"CargoBay", nil), purchaseInfoBundleID, receiptBundleID] forKey:NSLocalizedFailureReasonErrorKey];

🎯 实用错误调试技巧

1. 环境配置检查

• 沙盒环境:kCargoBaySandboxReceiptVerificationURLString
• 生产环境:kCargoBayProductionReceiptVerificationURLString
• 常见错误: 环境不匹配导致状态码21007或21008

2. 收据验证流程

1. 提取购买信息- 从交易收据中解析数据
2. 验证签名安全- 确保收据未被篡改
3. 匹配购买信息- 检查Bundle ID、产品ID等
4. 验证交易信息- 确认交易与购买信息一致
5. 检查唯一性- 防止重复处理

3. 错误日志记录

建议记录完整的错误信息，包括：

• 错误域和错误码
• 本地化描述
• 失败原因
• 相关交易信息

📈 错误处理性能优化

1. 异步处理

CargoBay的所有验证操作都是异步执行的，不会阻塞主线程。

2. 缓存机制

使用NSUserDefaults缓存已知交易ID，避免重复验证。

3. 网络请求优化

自动处理SSL证书验证，确保与苹果服务器的安全通信。

🔧 自定义错误处理扩展

1. 交易ID唯一性验证

您可以通过设置自定义验证块来扩展唯一性检查：

[[CargoBay sharedManager] setTransactionIDUniquenessVerificationWithBlock:^BOOL(NSString *transactionID) { // 自定义唯一性检查逻辑 return [self isTransactionIDUnique:transactionID]; }];

2. 自定义验证端点

支持自定义验证服务器端点：

[cargoBay verifyTransactionWithMethod:@"POST" endpoint:customEndpoint receipt:receiptData password:sharedSecret success:success failure:failure];

🚀 快速故障排除指南

常见问题及解决方案

📚 深入学习资源

官方文档参考

• StoreKit官方文档 - 苹果StoreKit框架参考
• CargoBay核心实现 - 完整错误处理逻辑源码

测试用例学习

查看CargoBay测试文件中的错误处理测试案例，了解各种错误场景的处理方式。

🎉 总结

CargoBay提供了完整而强大的错误处理机制，涵盖了应用内购买的所有关键验证点。通过理解这16种状态码和错误类型，您可以：

1. 快速定位问题- 根据错误码立即识别问题类型
2. 精准调试- 利用详细的错误信息进行针对性调试
3. 提升用户体验- 优雅处理各种购买场景
4. 确保应用安全- 防止无效或欺诈交易

掌握CargoBay的错误处理，让您的应用内购买功能更加稳定可靠！🌟

提示: 在实际开发中，建议结合CargoBay示例项目进行测试，确保所有错误场景都得到妥善处理。

【免费下载链接】CargoBayThe Essential StoreKit Companion项目地址: https://gitcode.com/gh_mirrors/ca/CargoBay