NestJS Stripe Webhook 处理中的 JSON 解析问题解决方案

在使用 NestJS 结合 Stripe 处理支付回调时，开发者经常会遇到 "undefined" is not valid JSON 的错误。这个问题通常出现在 Stripe Webhook 的处理过程中，特别是在使用 @golevelup/nestjs-stripe 模块时。

问题根源分析

这个错误的根本原因在于请求的原始体（rawBody）未被正确设置。当 Stripe Webhook 发送事件到服务器时，@golevelup/nestjs-stripe 模块会尝试解析请求体，但如果 rawBody 不存在，就会抛出这个 JSON 解析错误。

解决方案实现

1. 创建 RawBody 中间件

我们需要创建一个专门的中间件来处理 Webhook 请求，确保 rawBody 被正确设置：

import { RawBodyRequest } from '@nestjs/common';
import { json, Request, Response } from 'express';

export interface RawBodyMiddlewareOptions {
  limit: string;
  rawBodyUrls: string[];
}

export function rawBodyMiddleware(options: RawBodyMiddlewareOptions): unknown {
  const rawBodyUrls = new Set(options.rawBodyUrls);

  return json({
    ...options,
    verify: (request: RawBodyRequest<Request>, _: Response, buffer: Buffer) => {
      if (rawBodyUrls.has(request.url) && Buffer.isBuffer(buffer)) {
        request.rawBody = Buffer.from(buffer);
      }
      return true;
    },
  });
}

这个中间件会检查请求 URL 是否在指定的 Webhook 路径列表中，如果是，则将请求体保存为 rawBody。

2. 应用中间件配置

在应用的主模块（通常是 main.ts）中，我们需要在标准 bodyParser 之前应用这个中间件：

app.use(
  rawBodyMiddleware({
    limit: '5mb',
    rawBodyUrls: ['/stripe/webhook', '/payment/test'],
  }),
);
app.use(bodyParser.json({ limit: '5mb' }));
app.use(bodyParser.urlencoded({ limit: '5mb', extended: true }));

注意中间件的顺序很重要，必须确保 rawBody 中间件在标准 JSON 解析器之前。

3. 配置 Stripe 模块

在 Stripe 模块配置中，我们需要明确指定使用 rawBody 作为请求体来源：

webhookConfig: {
  decorators: [SkipThrottle()],
  requestBodyProperty: 'rawBody',
  stripeSecrets: {
    account: configService.get('stripe.account', { infer: true }),
    accountTest: configService.get('stripe.account', { infer: true }),
  },
},

特别需要注意的是，在开发环境中使用 Stripe CLI 测试时，必须正确设置 accountTest 配置项，否则可能会遇到签名验证失败的问题。

常见问题排查

1. 签名验证失败：如果配置完成后出现 No signatures found matching the expected signature for payload 错误，请检查：

   • 是否正确设置了 accountTest 配置
   • 本地 Stripe CLI 是否使用了正确的 Webhook 密钥

2. 请求体大小限制：确保设置的 limit 足够大以容纳可能的 Webhook 数据，示例中使用了 5MB 的限制。

3. 中间件顺序：确保 rawBody 中间件在所有其他可能修改请求体的中间件之前执行。

最佳实践建议

1. 环境区分：为开发和生产环境配置不同的 Webhook 端点，避免测试数据影响生产环境。

2. 日志记录：在处理 Webhook 时添加详细的日志记录，便于问题排查。

3. 错误处理：实现完善的错误处理机制，确保 Webhook 失败时能够重试或通知相关人员。

4. 测试验证：创建专门的测试端点验证 rawBody 是否被正确设置，然后再集成 Stripe Webhook 处理逻辑。

通过以上配置和注意事项，开发者可以稳定可靠地处理 Stripe Webhook 事件，避免 JSON 解析错误和其他常见问题。