mcpField
U
upgrade-stripe

upgrade-stripe

github.com/exceptionless开发2.5k46 次安装今天更新
代码仓库

关于 upgrade-stripe

面向开发者的 Stripe API 与 SDK 升级指南，涵盖版本差异、迁移步骤和测试方法，并分别说明服务端、网页及移动 SDK 的版本规则。

主要功能

  1. 01说明 API 版本变更类型
  2. 02介绍服务端 SDK 版本管理
  3. 03说明 Stripe.js 版本配对
  4. 04概述移动 SDK 版本规则
  5. 05提供升级与测试清单

适用场景

  1. 01规划 API 版本升级
  2. 02核对各 SDK 的版本规则
  3. 03发布前测试目标版本

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/exceptionless/exceptionless --skill upgrade-stripe

安装后在 Claude Code 中输入/upgrade-stripe确认已加载。

详细介绍

最新的 Stripe API 版本为 2026-02-25.clover——升级时请使用此版本，除非用户指定了其他目标版本。

升级 Stripe 版本

本指南介绍如何升级 Stripe API 版本、服务端 SDK、Stripe.js 和移动 SDK。

了解 Stripe API 版本控制

Stripe 使用基于日期的 API 版本（例如，2026-02-25.clover、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-02-25.clover'

Stripe.api_version = '2026-02-25.clover'

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-02-25.clover'
});

按请求覆盖：

stripe.Customer.create(
  email="[email protected]",
  stripe_version='2026-02-25.clover'
)
强类型语言（Java、Go、.NET）

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

最佳实践

请始终在代码中指定你集成所使用的 API 版本，而不要依赖账户的默认 API 版本：

// Good: Explicit version
const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-02-25.clover'
});

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

Stripe.js 版本控制

详情请参阅 Stripe.js 版本控制。

Stripe.js 采用常青模式，每年两次发布主要版本（Acacia、Basil、Clover）。

加载指定版本的 Stripe.js

通过脚本标签：

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

通过 npm：

npm install @stripe/stripe-js

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

API 版本配对

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

  • Clover Stripe.js 使用 2026-02-25.clover API
  • Acacia Stripe.js 使用 2024-12-18.acacia API

你无法覆盖此对应关系。

从 v3 迁移
  1. 在代码中确认当前 API 版本
  2. 查看变更日志，了解相关变更
  3. 考虑先逐步更新 API 版本，再切换 Stripe.js 版本
  4. Stripe 将无限期继续支持 v3

移动 SDK 版本控制

详情请参阅 移动 SDK 版本控制。

iOS 和 Android SDK

两个平台均采用语义化版本控制（MAJOR.MINOR.PATCH）：

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

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

React Native SDK

采用不同的版本模式（0.x.y 格式）：

  • 次要版本变更（x）：破坏性变更和新功能
  • 补丁更新（y）：仅修复关键错误
后端兼容性

除非文档另有说明，所有移动 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 脚本标签或 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-02-25.clover"

也可以在代码中设置：

const stripe = require('stripe')('sk_test_xxx', {
  apiVersion: '2026-02-25.clover'  // Test with new version
});

重要说明

  • webhook 监听器应能妥善处理不熟悉的事件类型
  • 升级前，请使用新版本的结构测试 webhook
  • 重大变更会按受影响的产品领域标记（Payments、Billing、Connect 等）
  • 多个 API 版本可以同时共存，便于分阶段采用

评论

支持 Markdown