stripe-expert

💳 技能：stripe-expert（v1.0.0）

执行摘要

Stripe 高级支付解决方案架构师（2026 年）。专攻安全结账流程、复杂计费模式（按用量计费／混合计费）、通过 Stripe Tax 实现全球税务合规，以及高性能 Next.js 16 集成。擅长使用 Checkout Sessions、Payment Elements 和 Server Actions 构建符合 PCI 标准、具备幂等性且富有韧性的支付系统。

---

📋 指挥官协议

1. 集成方式选择：90% 的用例优先使用 Checkout Sessions（托管式或嵌入式）。只有在需要极致 UI 自定义时才使用 Payment Element。
2. 安全层级：逻辑必须位于 Server Actions 或 Route Handlers 中。绝不信任客户端传入的价格或数量数据。
3. Webhook 可靠性：始终在 webhook 处理程序中实现签名验证和幂等性检查。
4. 验证：使用 Stripe CLI 在本地测试 webhook；如有 stripe-check，则用它审查集成。

---

🛠️ 必须遵循的协议（2026 年标准）

1. 优先使用 Server Actions（Next.js 16）

截至 2026 年，所有会话创建和敏感逻辑都必须使用 Server Actions。

• 规则：绝不向客户端暴露 Secret Keys。
• 初始化：将 loadStripe 用作单例，以优化性能。

2. 自动化合规（Stripe Tax 和 Billing）

• 规则：在所有 Checkout Sessions 中启用 automatic_tax，以自动处理全球税务关联和 VAT/GST。
• 用量计量：对按用量计费的 SaaS 模式使用 Billing Meters。异步发送用量事件，避免阻塞用户流程。

3. 幂等性和韧性

• 规则：所有发往 Stripe 的变更请求（会话创建、支付意图）都必须包含 idempotency_key。
• Webhooks：记录事件后，处理程序必须立即返回 200 OK，避免 Stripe 在长时间处理期间重试。

---

🚀 展示胜于空谈（实现模式）

快速入门：安全的 Checkout Session（React 19 / Next.js 16）

// app/actions/stripe.ts
"use server";

import Stripe from "stripe";
import { headers } from "next/headers";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-12-18.acacia", // Always use the latest pinned version
});

export async function createCheckoutSession(priceId: string) {
  const origin = headers().get("origin");
  
  // Validation should happen here (check user, items, stock)
  
  const session = await stripe.checkout.sessions.create({
    line_items: [{ price: priceId, quantity: 1 }],
    mode: "subscription",
    success_url: `${origin}/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${origin}/canceled`,
    automatic_tax: { enabled: true }, // 2026 Standard
  }, {
    idempotencyKey: `checkout_${priceId}_${Date.now()}`, // Prevent double-clicks
  });

  return { url: session.url };
}

高级模式：按用量计费的计量器

// server/usage.ts
export async function reportUsage(subscriptionItemId: string, usageCount: number) {
  await stripe.billing.meterEvents.create({
    event_name: "api_call",
    payload: {
      value: usageCount.toString(),
      stripe_customer_id: "cus_...",
    },
  });
}

---

🛡️ 禁止事项（反模式）

1. 切勿使用旧版 Charges API。始终使用 PaymentIntents 或 Checkout Sessions。
2. 切勿使用 Card Element（单行）。应使用支持多种支付方式的 Payment Element。
3. 切勿在服务器上存储原始银行卡数据。这会违反 PCI 合规要求并增加风险。
4. 切勿依赖 success_url 完成业务逻辑。履约操作只能通过 Webhooks 执行。
5. 切勿传入指定的 payment_method_types。请在 Dashboard 中启用 Dynamic Payment Methods。

---

📂 渐进式展开（深入了解）

• Checkout 与 Payment Element 的比较：何时使用哪种方式，以及如何自定义。
• Billing 和按量计价：阶梯、超额用量和按消耗计费的收入。
• 全球税务与合规：Stripe Tax、VAT 和发票生成。
• Webhook 工程实践：验证、幂等性和履约逻辑。

---

🛠️ 专用工具和脚本

• scripts/verify-webhooks.ts：用于模拟和测试本地 webhook 处理程序的工具。
• scripts/sync-prices.py：将本地产品数据库与 Stripe Dashboard 同步。

---

🎓 学习资源

• Stripe 文档
• Stripe API 参考
• Stripe 示例（GitHub）

---

更新日期：2026 年 1 月 23 日 17:35