# @cungminh2710/graphql-depth-limit 中文文档

规范地址：https://npmcn.com/package/%40cungminh2710/graphql-depth-limit/

版本：1\.0\.0
npm 元数据更新时间：2023-01-17T22:32:44.204Z
中文译文更新时间：2026-11-11T04:44:27.751Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cungminh2710/graphql-depth-limit
原文对照：https://npmcn.com/package/%40cungminh2710/graphql-depth-limit/?lang=original
项目主页：https://github.com/cungminh2710/graphql-depth-limiter#readme
源码仓库：https://github.com/stems/graphql-depth-limit

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

- 包体积（解压后）：16.6 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14\.0\.0
- 运行依赖：0 个
- peer 依赖：graphql ^16
- 首次发布：2023-01-17T22:32:43.785Z
- 最新版本发布：2023-01-17T22:32:44.015Z
- 近 30 天下载量：4014（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

基于深度限制您的 GraphQL 查询的复杂性 .

## 安装

```sh
npm install @cungminh2710/graphql-depth-limit
```

也可以使用：`pnpm add @cungminh2710/graphql-depth-limit`、`yarn add @cungminh2710/graphql-depth-limit`、`bun add @cungminh2710/graphql-depth-limit`

## README

# 图QL 深度限制

叉子从 [图QL 深度限制](https://www.npmjs.com/package/graphql-depth-limit)

死而复生地防御无限制的GraphQL查询. 仅通过查询限制查询的复杂性 _深度_。 。 。 .

## 为什么?

如果你有一个 `Album` 类型有列表 `Song`编号.

```graphql
{
  album(id: 42) {
    songs {
      title
      artists
    }
  }
}
```

或许你有一个不同的切入点 `Song` 类型允许您返回 `Album`。 。 。 .

```graphql
{
  song(id: 1337) {
    title
    album {
      title
    }
  }
}
```

这让你的服务器打开了周期性查询的可能性!

```graphql
query evil {
  album(id: 42) {
    songs {
      album {
        songs {
          album {
            songs {
              album {
                songs {
                  album {
                    songs {
                      album {
                        songs {
                          album {
                            # and so on...
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

如果查询深度为一万, 您的服务器将如何处理 ? 这可能会成为一个非常昂贵的操作,在某个时候将CPU钉入服务器或数据库. 这可能是监督事务司的脆弱性. 我们想要一种方法来验证收到的询问的复杂性.

此执行允许您限制 **总深度** 每个操作.

## 量化复杂性

准确决定 _何时_ a GraphQL 查询“太复杂”是一种细微而微妙的艺术. 感觉有点像决定需要多少粒砂来作"一叠砂". 其他一些库有开发者指定 **费用** ,并添加每个查询的累计费用.

[图克l-验证-复杂](https://github.com/4Catalyzer/graphql-validation-complexity) 以 _类型_, (中文(简体) ), 财务报告和审定财务报表 [图克-克-复杂度](https://github.com/ivome/graphql-query-complexity) 是否基于每个 _字段_。 。 。 .

增加成本可能对某些后端有效,但并不总是忠实地代表复杂性. 通过增加每个深度的成本,就好像复杂度随着深度的增大而呈线性增长. 有时复杂程度会增加 **指数** 深处,例如如果请求一个字段意味着做另一个 SQL `JOIN`。 。 。 .

此库验证了查询(和突变)的总深度.

### 下面是一些深度为0的查询

```graphql
# simplest possible query
query shallow1 {
  thing1
}

# inline fragments don't actually increase the depth
query shallow2 {
  thing1
  ... on Query {
    thing2
  }
}

# neither do named fragments
query shallow3 {
  ...queryFragment
}

fragment queryFragment on Query {
  thing1
}
```

### 更深的查询

```graphql
# depth = 1
query deep1_1 {
  viewer {
    name
  }
}

query deep1_2 {
  viewer {
    ... on User {
      name
    }
  }
}

# depth = 2
query deep2 {
  viewer {
    albums {
      title
    }
  }
}

# depth = 3
query deep3 {
  viewer {
    albums {
      ...musicInfo
      songs{
        ...musicInfo
      }
    }
  }
}

fragment musicInfo on Music {
  id
  title
  artists
}
```

## 使用量

```shell
$ npm install @cungminh2710/graphql-depth-limit
```

和我们一起工作 [表达式ql](https://github.com/graphql/express-graphql) 财务报告和审定财务报表 [地图](https://github.com/chentsulin/koa-graphql)。 。 。 . 以下是快递公司的例子.

```js
import depthLimit from 'graphql-depth-limit'
import express from 'express'
import graphqlHTTP from 'express-graphql'
import schema from './schema'

const app = express()

app.use('/graphql', graphqlHTTP((req, res) => ({
  schema,
  validationRules: [ depthLimit(10) ]
})))
```

第一个论点是总深度限制。 这将为询问(或突变)扔出一个验证错误,其深度为11个或更多.  
第二个参数是一个选项对象,您可以在此指定被忽略的字段。 反省字段默认被忽略.  
第三个论点是: `Object` 它是一个每个操作深度的地图.  

```js
depthLimit(
  10,
  { ignore: [ /_trusted$/, 'idontcare' ] },
  depths => console.log(depths)
)
```

现在之前的邪恶查询会告诉客户:

```js
{
  "errors": [
    {
      "message": "'evil' exceeds maximum operation depth of 10",
      "locations": [
        {
          "line": 13,
          "column": 25
        }
      ]
    }
  ]
}
```

## 未来工作

-   [ ] 类型特定子深度限制,例如,您只能从一个 `Album` 类型,从 `User` 类型等.
-   [ ] 更多定制选项, 如自定义错误 .

## 文档

### 深度( 最大深度 , \[选项\] , \[召回\]) QQ `function`

为 GraphQL 查询深度创建验证符

**仁爱**:全球职能  
**回返**数字 : `function` - GraphQL 验证阶段的验证器功能.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| 最大深度 | `Number` | GraphQL 文档中任何操作的最大允许深度 . |
| \[可选 | `Object` |  |
| 选项 | `String` | `RegExp` | `function` | 停止基于字段名的递归深度检查。 或匹配名称的字符串或 regexp, 或返回布尔函数 . |
| \[召回\] | `function` | 每次验证运行时都会调用. 接收每个操作深度的映射对象. |

## 常见问题

### @cungminh2710/graphql-depth-limit 是什么？

基于深度限制您的 GraphQL 查询的复杂性 \.

### 如何安装 @cungminh2710/graphql-depth-limit？

在项目目录运行 npm install @cungminh2710/graphql-depth-limit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：graphql（^16）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cungminh2710/graphql-depth-limit 支持 TypeScript 吗？

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

### @cungminh2710/graphql-depth-limit 支持 ESM 还是 CommonJS？

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

### @cungminh2710/graphql-depth-limit 需要什么版本的 Node\.js？

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

### @cungminh2710/graphql-depth-limit 可以商用吗？

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

### @cungminh2710/graphql-depth-limit 的下载量有多少？

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

### @cungminh2710/graphql-depth-limit 还在维护吗？

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