# @boring-stack-pkg/eslint-plugin-stripe-webhooks 中文文档

规范地址：https://npmcn.com/package/%40boring-stack-pkg/eslint-plugin-stripe-webhooks/

版本：0\.1\.2
npm 元数据更新时间：2026-05-25T07:54:07.156Z
中文译文更新时间：2026-11-08T11:42:00.300Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40boring-stack-pkg/eslint-plugin-stripe-webhooks
原文对照：https://npmcn.com/package/%40boring-stack-pkg/eslint-plugin-stripe-webhooks/?lang=original
项目主页：https://github.com/boringstack-xyz/eslint-plugins#readme
源码仓库：https://github.com/boringstack-xyz/eslint-plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：142 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^20\.0\.0 \|\| ^22\.0\.0 \|\| \>=24\.0\.0
- 运行依赖：1 个
- peer 依赖：@typescript-eslint/parser \>=8\.0\.0，eslint 8\.57\.0 \|\| ^9\.0\.0，typescript \>=5\.0\.0
- 首次发布：2026-05-19T19:39:59.793Z
- 最新版本发布：2026-05-25T07:54:06.985Z
- 近 30 天下载量：2237（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

ESLint 插件,用于执行 Frede webhooks 的安全和正确规则.

## 安装

```sh
npm install @boring-stack-pkg/eslint-plugin-stripe-webhooks
```

也可以使用：`pnpm add @boring-stack-pkg/eslint-plugin-stripe-webhooks`、`yarn add @boring-stack-pkg/eslint-plugin-stripe-webhooks`、`bun add @boring-stack-pkg/eslint-plugin-stripe-webhooks`

## README

# 埃斯林特- plugin- stripe- webhooks (西班牙语)

[![npm](https://img.shields.io/npm/v/@boring-stack-pkg/eslint-plugin-stripe-webhooks?logo=npm)](https://www.npmjs.com/package/@boring-stack-pkg/eslint-plugin-stripe-webhooks) [![source](https://img.shields.io/badge/source-github-blue?logo=github)](https://github.com/boringstack-xyz/eslint-plugins/tree/main/eslint-plugin-stripe-webhooks)

为 Frede Webhook 处理器执行安全和正确规则的ESLint插件.

## 为什么

花脸网呼克有两个出名的失败模式:

1.  **未验证的有效载荷.** 阅读或解析请求正文之前 `*.constructEvent(...)` 成功意味着攻击者可以向您的端点发送一个被whook形状的有效载荷,而您的操作者会向数据库发火,在数据库上写/队列任务/电子邮件. 签名检查从没有机会拒绝.
2.  **非一能而有型盲所处理.** 在瞬变故障上花边重排事件 — 一个处理器, 无需调试 `event.id` 将重复充电,双电子邮件,双推。 一个没有分枝的操作员 `event.type` 每类事件都将运行相同的逻辑.

这六条规则定下了阻止两者的规律.

## 安装

```sh
pnpm add -D @boring-stack-pkg/eslint-plugin-stripe-webhooks @typescript-eslint/parser
```

## 用法(平面配置)

```js
// eslint.config.mjs
import tsParser from "@typescript-eslint/parser";
import stripeWebhooks from "@boring-stack-pkg/eslint-plugin-stripe-webhooks";

export default [
  {
    files: ["**/*.{ts,tsx}"],
    languageOptions: {
      parser: tsParser,
      parserOptions: { ecmaVersion: "latest", sourceType: "module" },
    },
    plugins: { "stripe-webhooks": stripeWebhooks },
    rules: stripeWebhooks.configs.recommended.rules,
  },
];
```

建议的预设使所有六项规则都能够在 `"error"`通过标准的ESLint机制推翻规则.

## 规则

| 规则 | 级别 | 说明 |
| --- | --- | --- |
| [`handler-must-verify-signature`](https://npmcn.com/package/%40boring-stack-pkg/eslint-plugin-stripe-webhooks/docs/rules/handler-must-verify-signature.md) | **1号线安全** | 取消阅读或转发 Webhook 有效载荷 `*.constructEvent(...)` 成功 . |
| [`no-parsed-body-before-verification`](https://npmcn.com/package/%40boring-stack-pkg/eslint-plugin-stripe-webhooks/docs/rules/no-parsed-body-before-verification.md) | 警卫 | 解析身体 API(`request.json()`, (中文(简体) ), `JSON.parse(body)`, (中文(简体) ), `req.body`, (中文(简体) ), `express.json()`在核查之前. |
| [`require-stripe-signature-header`](https://npmcn.com/package/%40boring-stack-pkg/eslint-plugin-stripe-webhooks/docs/rules/require-stripe-signature-header.md) | 警卫 | 要求通过签字 `constructEvent(...)` ;禁止硬码 `whsec_*` 秘密,我们有秘密. |
| [`handler-must-handle-event-type`](https://npmcn.com/package/%40boring-stack-pkg/eslint-plugin-stripe-webhooks/docs/rules/handler-must-handle-event-type.md) | 正确性 | 条纹事件处理器必须打开分支 `event.type`。 。 。 . |
| [`handler-must-be-idempotent`](https://npmcn.com/package/%40boring-stack-pkg/eslint-plugin-stripe-webhooks/docs/rules/handler-must-be-idempotent.md) | 正确性 | 执行副作用的 Webhook 处理器必须咨询 `event.id` 为去杜普. |
| [`service-must-construct-event`](https://npmcn.com/package/%40boring-stack-pkg/eslint-plugin-stripe-webhooks/docs/rules/service-must-construct-event.md) | 公约 | 花纹感知课程 `webhook`\- 命名方法还必须有验证方法调用 `constructEvent`。 。 。 . |

## 实例

### 处理器-必须核实-签名

```ts
// ❌
export async function POST(request: Request) {
  const body = await request.json();
  const event = stripe.webhooks.constructEvent(body, sig, k);
}

// ✅
export async function POST(request: Request) {
  const body = await request.text();
  const sig = request.headers.get("stripe-signature");
  const event = stripe.webhooks.constructEvent(
    body,
    sig,
    process.env.WEBHOOK_SECRET!,
  );
}
```

### 处理者-必须-有能力

```ts
// ❌
export async function handle(event: Stripe.Event) {
  if (event.type === "payment_intent.succeeded") {
    await db.payments.insert({
      /* ... */
    });
  }
}

// ✅
export async function handle(event: Stripe.Event) {
  if (await alreadyProcessed(event.id)) return;
  if (event.type === "payment_intent.succeeded") {
    await db.payments.insert({
      /* ... */
    });
  }
}
```

完整的规则文件及文件节选请参见 [`docs/rules/`](https://npmcn.com/package/%40boring-stack-pkg/eslint-plugin-stripe-webhooks/docs/rules/) 和可运行的 [`examples/`](https://npmcn.com/package/%40boring-stack-pkg/eslint-plugin-stripe-webhooks/examples/) (Next.js App路由器,快车,Elysia/Hono,班级服务).

## 安全理念

这些规则是 **最佳静态分析**发现常见的错误——阅读 `req.body` 在此之前 `constructEvent`,硬码 `whsec_*` 秘密,失踪 `event.type` 分枝——但是他们不能证明一个网钩处理器是正确的. 具体来说,这里的任何规则本身都不足以解决问题。 与之对等的是:

-   端到端测试 [条纹 CLI](https://docs.stripe.com/cli) 网络模拟器.
-   对公关时间每个网路入口进行TIER 1安全审查.
-   集中核查(见 `service-must-construct-event`因此,核查步骤存在于一个地方.

## 静态分析的局限性

-   **没有交叉函数数据流 .** 一个身体参数传递到另一个文件中的帮助者没有被跟踪.
-   **无有能知之类推.** `Stripe.Event` 参数检测依赖于字形类型名称+一个字条导入在同一个文件中存在. 通用包装器类型( X)`MyEvent<Stripe.Event>`)不被承认.
-   **同上,《抽查情况报告》.** 抽象去dupe逻辑的帮助函数必须指定为每个 `allowedCheckFunctionPatterns`. DB独有的受约束的去dupe不可见.
-   **中间软件核查** 这条规则不承认 将看起来像"不核查"规则.

当怀疑时, 更喜欢明确, 手持 `constructEvent` 给一个聪明的抽象点打电话——这是规则的优化模式.

## 发展

```sh
pnpm install
pnpm test
pnpm typecheck
pnpm build
```

## 释放

标记 a `v*` 本地版本并按下标签. `.github/workflows/release.yml` 运行 `pnpm publish --access public --no-git-checks` 与 `NPM_TOKEN`。 。 。 .

## 许可证

麻省理工学院.

## 常见问题

### @boring-stack-pkg/eslint-plugin-stripe-webhooks 是什么？

ESLint 插件,用于执行 Frede webhooks 的安全和正确规则\.

### 如何安装 @boring-stack-pkg/eslint-plugin-stripe-webhooks？

在项目目录运行 npm install @boring-stack-pkg/eslint-plugin-stripe-webhooks，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@typescript-eslint/parser（\>=8\.0\.0）、eslint（8\.57\.0 \|\| ^9\.0\.0）、typescript（\>=5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @boring-stack-pkg/eslint-plugin-stripe-webhooks 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @boring-stack-pkg/eslint-plugin-stripe-webhooks 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @boring-stack-pkg/eslint-plugin-stripe-webhooks 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.0\.0 \|\| ^22\.0\.0 \|\| \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @boring-stack-pkg/eslint-plugin-stripe-webhooks 可以商用吗？

@boring-stack-pkg/eslint-plugin-stripe-webhooks 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @boring-stack-pkg/eslint-plugin-stripe-webhooks 的下载量有多少？

根据 npm 官方下载统计，@boring-stack-pkg/eslint-plugin-stripe-webhooks 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,237 次，日均约 75 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @boring-stack-pkg/eslint-plugin-stripe-webhooks 还在维护吗？

最新版本 0\.1\.2 发布于 2026/05/25（5 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/05/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。