移动端应用的内购收入校验是很多做海外市场的团队绕不开的一道坎。尤其是安卓平台用户完成付款后客户端拿到的凭证只是一串字符串真正决定这笔订单是否有效、是否该给用户发货的是服务端拿着这串凭证去官方接口做一次核验。标题里提到的Google.Apis.AndroidPublisher.v3就是 .NET 生态里对接这套服务端校验能力的官方客户端库。我所在的团队做的是订阅制工具类应用日活不算大但付费转化率还行服务端用的是 C# 技术栈所以这套方案从选型到上线踩了不少坑也积累了一些文档里不太会写的细节。这篇内容适合正在做安卓内购服务端校验的 C# 后端同学也适合想搞清楚“客户端付款成功之后服务端到底该做什么”的产品和测试同学。我会从整体设计思路讲起把库的接入、凭证校验、订阅状态查询、异常处理、幂等设计这些环节拆开揉碎配上可直接参考的代码和参数说明尽量让你看完就能动手复现。1. 整体方案设计与技术选型思路1.1 为什么服务端必须做二次校验先把最核心的逻辑讲清楚客户端调用支付流程成功后拿到的所谓“购买凭证”本质上是一段由平台签发的数据客户端可以把它传给服务端但服务端绝对不能仅凭“客户端说付款成功了”就给用户开通权益。原因很直接客户端运行在用户设备上处于不可信环境凭证可能被伪造、被重放、被篡改。服务端拿着凭证去官方接口核验相当于让权威方来背书这笔交易的真实性只有核验通过、状态符合预期才进入发货逻辑。这个思路在订阅制场景里更加重要。一次性商品校验一次就完事订阅商品则涉及续订、取消、宽限期、账户保留期等一系列状态变化服务端需要持续跟踪订阅的有效性而不是付款那一刻校验完就撒手不管。所以整套方案的设计目标不只是“验一次”而是建立一个可查询、可对账、可补偿的订单状态同步机制。1.2 选官方客户端库还是裸调 REST 接口对接这套校验能力有两条路一是直接用HttpClient拼 REST 请求自己处理鉴权、序列化、重试二是用官方提供的 .NET 客户端库Google.Apis.AndroidPublisher.v3。我们最终选了后者理由有几个。第一是鉴权封装。官方接口走的是服务账号的 OAuth 2.0 流程需要签发 JWT、换取访问令牌、处理令牌过期刷新。裸调的话这些都得自己写虽然不算特别难但容易在时钟偏移、令牌缓存这些细节上翻车。客户端库把这层封装好了传入服务账号的 JSON 密钥文件路径即可令牌的获取和刷新由库内部管理。第二是类型安全。库根据接口定义生成了强类型模型请求参数、响应结构都有对应的 C# 类编译期就能发现字段拼写错误比手拼 JSON 再解析要稳得多。尤其是订阅相关的响应结构字段多、嵌套深强类型带来的可维护性优势很明显。第三是版本跟进。平台侧的接口会迭代字段会增补官方库跟着版本走升级依赖就能拿到新能力省去自己盯着接口文档改代码的精力。当然代价也有库的体积不小依赖链比较长首次接入时对依赖版本冲突要留个心眼另外库的抽象层次偏高出问题时排查链路会比裸调长一些。综合下来对于服务端校验这种“调用频率不高但正确性要求极高”的场景官方库的收益大于成本。1.3 服务账号与权限的最小化配置服务端要调用校验接口身份是服务账号。这里有个容易被忽略的点服务账号需要在后台被授予对应的权限否则接口会返回权限不足。常见做法是在后台的项目设置里创建一个服务账号生成 JSON 格式的密钥文件然后把该服务账号的邮箱加到应用的授权列表里赋予查看财务数据、管理订单相关的权限。我的建议是遵循最小权限原则只授予校验和对账必需的权限不要图省事给管理员权限。密钥文件属于高敏感凭证绝对不能提交到代码仓库应该通过环境变量或密钥管理服务注入并且定期轮换。我们早期图方便把密钥文件放进了配置目录后来做安全审计时被点名改成了运行时从密钥管理服务拉取这个教训值得记一笔。提示密钥文件的泄露等同于服务账号被完全接管务必做好访问控制与轮换机制本地开发环境也不要使用生产密钥。2. 核心细节解析与接入实操要点2.1 依赖引入与版本选择在 C# 项目里引入这个库通过包管理器添加Google.Apis.AndroidPublisher.v3即可它会连带引入Google.Apis和Google.Apis.Auth等基础包。版本选择上建议锁定一个较新的稳定版本不要用浮动版本号避免某次构建时依赖悄悄升级引入行为变化。我们用的是 1.6x 系列的稳定版实测下来与 .NET 6 及以上运行时配合良好。dotnet add package Google.Apis.AndroidPublisher.v3 --version 1.68.0.3600版本号的后半段对应的是接口定义的修订号升级时留意变更日志里是否有涉及订阅或商品校验的字段调整。如果项目里同时引用了其他 Google 相关库注意Google.Apis基础包的版本要统一否则可能出现程序集加载冲突表现为运行时找不到方法或类型。这类问题在本地不一定复现往往在部署后才暴露所以构建流水线里加一步依赖树检查是有必要的。2.2 服务账号凭证的加载方式加载凭证有两种常见写法。一种是从文件路径加载适合密钥文件挂载在容器里的场景另一种是从 JSON 字符串或流加载适合密钥从密钥管理服务动态获取的场景。后者更灵活也更符合安全实践。using Google.Apis.Auth.OAuth2; using Google.Apis.AndroidPublisher.v3; using Google.Apis.Services; // 方式一从挂载的文件加载 var credential GoogleCredential.FromFile(/path/to/service-account.json) .CreateScoped(AndroidPublisherService.Scope.Androidpublisher); // 方式二从密钥管理服务拿到的 JSON 字符串加载 var credential GoogleCredential.FromJson(jsonFromSecretStore) .CreateScoped(AndroidPublisherService.Scope.Androidpublisher); var service new AndroidPublisherService(new BaseClientService.Initializer { HttpClientInitializer credential, ApplicationName order-verifier });这里的关键是CreateScoped指定的作用域。校验接口需要androidpublisher这个作用域漏掉或者写错会导致鉴权失败。ApplicationName建议填一个有辨识度的名字方便在后台的调用统计里定位来源。服务实例本身是线程安全的可以做成单例复用不必每次校验都新建避免重复的令牌获取开销。2.3 一次性商品校验的请求构造一次性商品的校验接口需要三个核心参数包名、商品 ID、购买令牌。购买令牌就是客户端付款成功后拿到的那串凭证。请求构造如下var request service.Purchases.Products.Get(packageName, productId, purchaseToken); var result await request.ExecuteAsync(); if (result.PurchaseState 0 result.PurchaseType 0) { // 购买状态为已购买且为正常购买类型可以进入发货逻辑 }响应里的PurchaseState是判断核心0 表示已购买1 表示已取消2 表示待处理。待处理状态在部分支付方式下会出现比如某些延迟结算的场景这时候不能直接发货要等状态流转。PurchaseType用来区分是正常购买还是测试购买测试购买不应该计入真实收入也不应该给真实权益这个字段在联调阶段特别有用可以避免测试订单污染生产数据。还有一个ConsumptionState字段针对可消耗商品0 表示未消耗1 表示已消耗。如果你的商品是可消耗类型比如游戏币发货后需要调用消耗接口把令牌标记为已消耗否则同一令牌可能被重复使用。这个环节是很多团队容易漏掉的漏掉之后会出现“同一笔订单反复发货”的问题。2.4 订阅商品校验的差异点订阅商品的校验接口和一次性商品不同参数是包名、订阅 ID、购买令牌var request service.Purchases.Subscriptions.Get(packageName, subscriptionId, purchaseToken); var result await request.ExecuteAsync();订阅响应里字段更多重点看PaymentState和ExpiryTimeDateTimeOffset。PaymentState为 0 表示待支付1 表示已支付2 表示免费试用3 表示待处理延迟付款。只有已支付或免费试用状态才应该开通权益。ExpiryTimeDateTimeOffset是订阅到期时间服务端要据此判断当前是否仍在有效期内不能只看付款状态。订阅场景还有一个容易踩的坑续订。用户订阅后平台会在每个计费周期自动扣款续订成功后购买令牌可能保持不变但到期时间会往后推。所以服务端不能只在首次购买时校验一次而应该在每次用户访问付费功能时或者通过定时任务定期重新校验订阅状态确保权益与真实状态一致。我们采用的是“访问时校验加每日对账”的双保险访问时校验保证实时性每日对账兜底处理漏掉的续订和退款。2.5 实时开发者通知的配合使用光靠轮询校验有个天然缺陷状态变化有延迟。用户取消订阅、发生退款服务端如果只靠定时查询中间会有一段权益与真实状态不符的窗口。更稳妥的做法是配合实时开发者通知平台在订阅状态变化时会向指定的回调地址推送消息服务端收到推送后触发一次校验及时更新本地状态。通知本身不携带完整的订单信息只带一个消息标识服务端收到后仍需调用校验接口拉取最新状态。所以通知的作用是“触发时机”校验接口才是“数据来源”两者配合才能做到既及时又准确。回调地址需要做鉴权防止伪造推送同时要做好幂等同一条通知可能重复投递。3. 完整实操流程与关键环节实现3.1 从客户端凭证到服务端发货的完整链路把整条链路串起来看客户端完成支付拿到购买令牌和商品信息提交给服务端服务端先做基础校验包名、商品 ID 是否在允许列表内再调用官方接口核验凭证核验通过后检查本地订单表是否已存在该令牌做幂等判断确认是新订单后写入订单记录并发放权益最后根据商品类型决定是否需要调用消耗接口。这个顺序里幂等判断必须在发货之前而且要用购买令牌作为唯一键。购买令牌在同一笔交易里是稳定的用它做去重最可靠。我们早期用“用户 ID 加商品 ID”做去重结果用户在订阅续订后再次提交同一令牌时被误判为重复订单权益没有续上后来改成令牌唯一键才解决。public async TaskVerifyResult VerifyAsync(string packageName, string productId, string purchaseToken, string userId) { // 1. 基础校验 if (!AllowedProducts.Contains(productId)) return VerifyResult.Rejected(product not allowed); // 2. 幂等检查 var existing await _orderRepo.FindByTokenAsync(purchaseToken); if (existing ! null existing.Status OrderStatus.Delivered) return VerifyResult.Duplicated(existing); // 3. 调用官方接口核验 var request _service.Purchases.Products.Get(packageName, productId, purchaseToken); var result await request.ExecuteAsync(); if (result.PurchaseState ! 0) return VerifyResult.Rejected($purchase state {result.PurchaseState}); // 4. 写入订单并发放权益 var order await _orderRepo.CreateAsync(new Order { Token purchaseToken, UserId userId, ProductId productId, PurchasedAt DateTimeOffset.UtcNow, Status OrderStatus.Delivered }); await _entitlementService.GrantAsync(userId, productId); return VerifyResult.Success(order); }这段代码是简化版真实场景里还要处理并发同一令牌可能被并发提交两次两个请求同时通过幂等检查然后都去发货。解决办法是在订单表上对令牌字段加唯一索引靠数据库约束兜底捕获唯一键冲突异常后返回重复结果。这个细节很关键纯靠应用层检查在并发下不可靠。3.2 订阅状态查询与到期时间处理订阅的到期时间处理有几个细节值得展开。响应里的到期时间字段是带时区的解析时要统一转成 UTC 再比较避免服务器时区不同导致判断偏差。另外订阅可能存在宽限期宽限期内用户虽然扣款失败但权益仍应保留这个状态在响应里有对应字段标识服务端要识别并区别对待不能一刀切地按到期时间停权。var expiry result.ExpiryTimeDateTimeOffset; var now DateTimeOffset.UtcNow; if (result.PaymentState 1 || result.PaymentState 2) { if (expiry now) { // 订阅有效 } else if (result.UserCancellationTimeMillis ! null) { // 用户已取消但可能仍在有效期内到期后停权 } }宽限期和账户保留期的处理逻辑建议单独抽一个状态机来管理把“有效、宽限期、保留期、已失效”这几个状态和迁移条件写清楚比散落在各处的 if 判断好维护得多。我们最初就是一堆 if 嵌套后来重构为状态机排查问题时清晰了很多。3.3 消耗接口的调用时机可消耗商品的消耗接口调用时机有讲究。应该在权益发放成功之后再调用消耗而不是之前。如果先消耗再发货发货失败时令牌已被标记消耗用户付了钱却没拿到东西补偿起来很麻烦。正确顺序是核验通过、发货成功、调用消耗。消耗失败不影响已发放的权益可以记录待补偿任务异步重试。var consumeRequest _service.Purchases.Products.Consume(packageName, productId, purchaseToken); await consumeRequest.ExecuteAsync();消耗接口本身是幂等的重复调用同一令牌不会报错所以重试是安全的。但要注意如果商品配置为不可消耗类型调用消耗接口会失败所以调用前要确认商品类型别对订阅商品误调消耗。3.4 退款与撤销的处理退款是收入侧绕不开的话题。用户退款后平台侧订单状态会变化服务端通过校验接口能查到撤销状态。一次性商品的响应里有PurchaseState变为取消的情况订阅则有对应的撤销标识。服务端在定期对账时发现撤销状态应该回收已发放的权益并记录退款原因。回收权益要谨慎尤其是用户可能已经消耗了部分权益的场景。我们的做法是记录撤销事件按商品类型执行不同的回收策略订阅直接停权可消耗商品标记欠款后续购买时优先抵扣。这个策略没有标准答案取决于业务形态但核心原则是“以官方状态为准本地记录可追溯”。4. 常见问题与排查技巧实录4.1 鉴权失败的典型原因鉴权失败是接入初期最高频的问题表现通常是调用接口抛出异常提示未授权或权限不足。排查顺序建议这样走先确认服务账号的 JSON 密钥是否完整、是否过期再确认服务账号是否被授予了应用的相关权限然后确认CreateScoped的作用域是否正确最后检查服务器时间是否准确时钟偏差过大会导致 JWT 签名校验失败。我们遇到过一次很隐蔽的情况服务器容器的时间同步没做好偏差几分钟令牌签发后立即被判无效报错信息指向鉴权失败但根因是时间。后来在所有节点上强制开启时间同步问题消失。这个坑值得单独记一笔因为报错信息完全不会提示时间问题。4.2 购买令牌无效或已使用的判断调用校验接口返回令牌无效常见原因有几个令牌拼写错误客户端传参时被截断或转义、令牌对应的商品与请求的商品 ID 不匹配、令牌已被消耗或已过期。排查时先把原始令牌打日志确认长度和字符完整再核对商品 ID 是否一致。订阅令牌和一次性商品令牌不能混用混用也会报无效。还有一种情况是测试环境与生产环境的令牌混用。测试购买产生的令牌只能在对应环境校验拿到另一个环境会失败。联调阶段要明确区分环境日志里带上环境标识避免排查时混淆。4.3 并发重复发货的根治办法前面提过并发问题这里展开讲根治方案。应用层的“先查后写”在并发下必然有窗口唯一可靠的兜底是数据库唯一约束。在订单表的令牌字段上建唯一索引两个并发请求同时插入时只有一个成功另一个抛唯一键冲突捕获后按重复订单处理。这个方案简单有效不依赖分布式锁也不怕多实例部署。如果订单表已经存在历史数据且令牌有重复加唯一索引前要先清洗数据否则建索引会失败。清洗时保留最早的一条其余标记为重复并人工核对别直接删留痕很重要。4.4 常见问题速查表问题现象可能原因排查方向调用抛未授权异常密钥无效、权限不足、作用域错误、时钟偏差逐项核对密钥、权限、作用域、服务器时间返回令牌无效令牌错误、商品 ID 不匹配、令牌已消耗、环境混用打印原始令牌、核对商品 ID、确认环境重复发货幂等检查缺失或并发窗口令牌唯一索引兜底、捕获冲突异常订阅权益未续上只校验一次、未处理续订访问时校验加定时对账消耗接口报错商品类型不可消耗、令牌已消耗确认商品类型、检查调用顺序退款后权益未回收未做定期对账增加对账任务、识别撤销状态4.5 几个实操心得第一日志要打全但别打敏感信息。购买令牌属于敏感数据日志里建议脱敏或只打哈希方便排查又不泄露。第二校验接口的调用要有超时和重试但重试要区分错误类型鉴权失败重试没意义网络超时和限流才值得重试。第三把校验结果和原始响应落库出问题时能回溯比事后猜要强得多。第四联调阶段多用测试购买把各种状态成功、取消、待处理、退款都走一遍别只测成功路径。这套方案上线后跑了挺长时间订阅续订和对账的稳定性比最初版本好了不少。我个人在实际操作中的体会是服务端校验这件事难点不在调通接口而在把状态同步、幂等、异常补偿这些边角做扎实。接口调用本身半小时能跑通但要让整套链路在生产环境扛住并发和异常得花几倍的时间打磨细节。后续如果业务扩展到多平台这套“凭证核验加状态机加对账”的骨架可以直接复用换的只是具体的接口和字段。
