Stripe Ruby SDK 中 Customer 对象的 sources 属性访问问题解析

在使用 Stripe Ruby SDK 进行支付系统开发时，开发者可能会遇到一个看似矛盾的现象：当通过 Stripe::Customer.retrieve 方法获取客户对象后，虽然 deleted? 方法返回 false 表明客户存在，但尝试访问 sources 属性时却会抛出 NoMethodError 异常。

问题本质

这种现象并非 SDK 的缺陷，而是 Stripe API 设计中的预期行为。Stripe API 中存在一类被称为"可包含属性"(includable properties)的特殊字段，这些字段默认不会在 API 响应中返回，必须通过显式的"扩展"(expand)请求才能获取。

技术背景

在 Stripe API 的演进过程中，2020年8月27日的版本更新引入了一个重要变更：废弃了客户对象中 sources 属性的自动扩展功能。这一变更是 Stripe 向更现代化的支付方式架构演进的一部分。

解决方案

要正确获取客户对象的 sources 属性，开发者需要使用扩展参数：

stripe_customer = Stripe::Customer.retrieve(
  stripe_customer_token,
  expand: ['sources']
)

架构演进建议

值得注意的是，Stripe 早在2018年就推出了更现代的 PaymentMethod API 来替代传统的 sources 属性。对于新开发的系统，建议直接使用 PaymentMethod API，它不仅提供了更清晰的接口设计，还能更好地支持 Stripe 最新的支付功能。

最佳实践

1. 对于现有系统维护：使用扩展参数明确请求需要的数据
2. 对于新系统开发：优先采用 PaymentMethod API
3. 在代码中做好异常处理，考虑到属性可能不存在的情况
4. 定期检查 Stripe API 更新日志，了解接口变更

通过理解这些底层机制，开发者可以更有效地使用 Stripe Ruby SDK 构建健壮的支付系统，同时为未来的架构演进做好准备。