返回技能市场
开发运维 安全

upgrade-stripe

@admin/upgrade-stripe

Guide for upgrading Stripe API versions and SDKs

admin 热度 285v0.0.1

最新的 Stripe API 版本是 2026-08-26.dahlia - 除非用户指定了不同的目标版本，否则在升级时使用此版本。

升级 Stripe 版本

本指南涵盖升级 Stripe API 版本、服务端 SDK、Stripe.js 和移动 SDK。

理解 Stripe API 版本管理

Stripe 使用基于日期的 API 版本（例如，2026-08-26.dahlia、2025-08-27.basil、2024-12-18.acacia）。你的账户的 API 版本决定请求/响应行为。

变更类型

向后兼容变更（不需要代码更新）：

  • 新 API 资源
  • 新可选请求参数
  • 现有响应中的新属性
  • 不透明字符串长度变更（例如，对象 ID）
  • 新 Webhook 事件类型

破坏性变更（需要代码更新）：

  • 字段重命名或删除
  • 行为修改
  • 已移除的端点或参数

查看 API 更新日志 以了解版本之间的所有变更。

服务端 SDK 版本管理

查看 SDK 版本管理 了解详情。

动态类型语言（Ruby、Python、PHP、Node.js）

这些 SDK 提供灵活的版本控制：

全局配置：

import stripe
stripe.api_version = '2026-08-26.dahlia'
Stripe.api_version = '2026-08-26.dahlia'
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-08-26.dahlia'
});

按请求覆盖：

stripe.Customer.create(
  email="customer@example.com",
  stripe_version='2026-08-26.dahlia'
)

强类型语言（Java、Go、.NET）

这些语言使用与 SDK 发布日期匹配的固定 API 版本。不要为强类型语言设置不同的 API 版本，因为响应对象可能与 SDK 中的强类型不匹配。相反，更新 SDK 以目标新的 API 版本。

最佳实践

始终在代码中指定你正在集成的 API 版本，而不是依赖你账户的默认 API 版本：

// Good: Explicit version
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-08-26.dahlia'
});

// Avoid: Relying on account default
const stripe = require('stripe')('sk_test_xxx');

Stripe.js 版本管理

查看 Stripe.js 版本管理 了解详情。

Stripe.js 使用常青模型，每半年进行一次主要发布（Acacia、Basil、Clover、Dahlia）。

加载版本化 Stripe.js

通过 Script 标签：

<script src="https://js.stripe.com/dahlia/stripe.js"></script>

通过 npm：

npm install @stripe/stripe-js

主要 npm 版本对应特定的 Stripe.js 版本。

API 版本配对

每个 Stripe.js 版本都会自动与其对应的 API 版本配对。例如：

  • Dahlia Stripe.js 使用 2026-08-26.dahlia API
  • Acacia Stripe.js 使用 2024-12-18.acacia API

你不能覆盖此关联。

从 v3 迁移

  1. 在代码中识别当前 API 版本
  2. 查看更新日志以了解相关变更
  3. 考虑在切换 Stripe.js 版本之前逐步更新你的 API 版本
  4. Stripe 无限期继续支持 v3

移动 SDK 版本管理

查看 移动 SDK 版本管理 了解详情。

iOS 和 Android SDK

两个平台都遵循语义化版本控制（MAJOR.MINOR.PATCH）：

  • MAJOR：破坏性 API 变更
  • MINOR：新功能（向后兼容）
  • PATCH：Bug 修复（向后兼容）

新功能和修复仅在最新主要版本上发布。请定期升级以获取改进。

React Native SDK

使用不同的模型（0.x.y schema）：

  • 次要版本变更（x）：破坏性变更和新功能
  • 补丁更新（y）：仅关键 Bug 修复

后端兼容性

除非文档另有说明，否则所有移动 SDK 都适用于你在后端使用的任何 Stripe API 版本。

升级清单

  1. 查看 API 更新日志 以了解当前版本和目标版本之间的变更
  2. 查看 升级指南 以获取迁移指导
  3. 更新服务端 SDK 包版本（例如，npm update stripe、pip install --upgrade stripe）
  4. 更新 Stripe 客户端初始化中的 apiVersion 参数
  5. 使用 Stripe-Version 标头针对新 API 版本测试你的集成
  6. 更新 Webhook 处理程序以处理新事件结构
  7. 如有需要，更新 Stripe.js script 标签或 npm 包版本
  8. 如有需要，在你的包管理器中更新移动 SDK 版本
  9. 将 Stripe 对象 ID 存储在最多可容纳 255 个字符（区分大小写排序规则）的数据库中

测试 API 版本变更

使用 Stripe-Version 标头针对新版本测试代码，而无需更改默认值：

curl https://api.stripe.com/v1/customers \
  -u sk_test_xxx: \
  -H "Stripe-Version: 2026-08-26.dahlia"

或在代码中：

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-08-26.dahlia'  // Test with new version
});

重要说明

  • 你的 Webhook 监听器应妥善处理未知事件类型
  • 在升级前使用新版本结构测试 Webhook
  • 破坏性变更会按受影响的产品领域进行标记（Payments、Billing、Connect 等）
  • 多个 API 版本同时共存，从而支持分阶段采用
qianwen skills install @admin/upgrade-stripe