# @dudousxd/nestjs-filter 中文文档

规范地址：https://npmcn.com/package/%40dudousxd/nestjs-filter/

版本：2\.1\.0
npm 元数据更新时间：2026-11-13T00:18:56.213Z
中文译文更新时间：2026-11-12T23:52:45.545Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dudousxd/nestjs-filter
原文对照：https://npmcn.com/package/%40dudousxd/nestjs-filter/?lang=original
项目主页：https://davidecarvalho.github.io/aviary/docs/filter
源码仓库：https://github.com/DavideCarvalho/nestjs-filter

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

- 包体积（解压后）：819 kB，185 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- peer 依赖：rxjs \>=7\.0\.0，@nestjs/core \>=10\.0\.0，@nestjs/i18n \>=0\.0\.3 \<1\.0\.0，@nestjs/common \>=10\.0\.0，class-validator \>=0\.14\.0，reflect-metadata \>=0\.1\.13，class-transformer \>=0\.5\.0，@dudousxd/nestjs-context \>=0\.1\.0
- 首次发布：2026-05-25T14:12:35.859Z
- 最新版本发布：2026-11-13T00:18:55.912Z
- 近 30 天下载量：4052（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

NestJS过滤库——核心抽象,跑道,装饰.

## 安装

```sh
npm install @dudousxd/nestjs-filter
```

也可以使用：`pnpm add @dudousxd/nestjs-filter`、`yarn add @dudousxd/nestjs-filter`、`bun add @dudousxd/nestjs-filter`

## README

# @dudousxd/nestjs-filter (英语)

巢-过滤器的核心软件包——声明式,ORM-不可知式滤波类,用于雀巢JS.

提供 `BaseFilter`, (中文(简体) ), `FilterRunner`,装饰器(`@Filterable`, (中文(简体) ), `@FilterFor`, (中文(简体) ), `@ApplyFilter`, (中文(简体) ), `FilterModule`、例外处理和测试公用事业.

## 安装

```bash
pnpm add @dudousxd/nestjs-filter
```

您还需要一个 ORM 适配软件包 :

```bash
# MikroORM
pnpm add @dudousxd/nestjs-filter-mikro-orm

# TypeORM
pnpm add @dudousxd/nestjs-filter-typeorm
```

## 快速启动

```typescript
import { Injectable } from '@nestjs/common';
import { Filterable, FilterFor, BaseFilter, FilterModule, ApplyFilter } from '@dudousxd/nestjs-filter';

// 1. Define a filter
@Injectable()
@Filterable({ entity: User })
class UserFilter extends BaseFilter<QueryBuilder> {
  @FilterFor('name')
  applyName(value: string) {
    this.$query.andWhere({ name: value });
  }
}

// 2. Register
@Module({
  imports: [
    FilterModule.forRoot({ inputNormalizer: 'camelCase' }),
    FilterModule.forFeature([UserFilter]),
  ],
})
class AppModule {}

// 3. Use in controller
@Controller('users')
class UsersController {
  @Get()
  list(@ApplyFilter(UserFilter) qb: QueryBuilder) {
    return qb.getResultList();
  }
}
```

## API 参考

### 装饰者

-   **`@Filterable({ entity, allowed?, blocked? })`** - 级装饰师。 将过滤器与实体联系起来. `allowed` 白名单密钥; `blocked` 黑名单 黑名单密钥被禁止完全过滤: 它在结构化发送中被跳过 **财务报告和审定财务报表** 放弃 `where` 列过滤器(匹配条款以警告方式被忽略,在任何深度,而不是拒绝)。 运行时间 `blacklistMethod(key)` 行为相同; `whitelistMethod`编号 :`allowed` 允许发送访问和提供 **没有** 约束 `where`。 。 。 .
-   **`@FilterFor(inputKey?)`** ——方法装饰. 绘制方法的输入键。 省略方法名的默认值.
-   **`@ApplyFilter(FilterClass, options?)`** - 参数装饰器。 解析请求中的输入, 运行过滤器, 并注入 QueryBuilder。 选项 : `source` (单位:千美元)`'auto'|'query'|'body'|Function`, (中文(简体) ), `dto`, (中文(简体) ), `resolve` (动态过滤器选择).

### 类

-   **`BaseFilter<TQuery>`** - 抽象基础类。 提供 `$query`, (中文(简体) ), `$input`, (中文(简体) ), `$context`, (中文(简体) ), `$adapter` 通过 Async 本地服务器。 可选 `setup()` 钩.
-   **`FilterRunner`** - 可注射服务. `apply(FilterClass, input, qb, context?)` 程序上运行过滤器.
-   **`FilterModule`** - 说吧 `forRoot(options?)` 登记全球基础设施. `forFeature(filters)` 注册过滤类.

### 例外

-   `FilterException` - 抽象基础.
-   `FilterNotRegisteredException` - 不在 DI 容器中的过滤类.
-   `FilterMissingEntityException` 失踪 `@Filterable({ entity })`。 。 。 .
-   `FilterStateUnavailableException` -- 访问 `$query` 外部 `FilterRunner.apply()`。 。 。 .
-   `UnknownFilterKeyException` -- 未知的密钥当 `onUnknownKey: 'throw'`。 。 。 .
-   `FilterValidationException` -- 类验证器验证失败 .
-   `FilterMethodException` - 过滤方法(或 `setup()`)扔出一个错误.

### 例外过滤器

-   **`FilterExceptionFilter`** - 渔获 `FilterValidationException` 返回时 `{ statusCode: 400, message, errors }`。 。 。 .

客户端消息(这个和跑者400s)通过 [`@nestjs/i18n`](https://docs.nestjs.com/techniques/i18n) 当应用程序将其注册时(可选的对等点,qq 0.0.3 < 1.0),作为 `filter.*` 密钥; 合并 `@dudousxd/nestjs-filter/i18n/en.json` 编号 : `pt-BR.json` 进入你的目录。 失踪 键用英语。 见"主计长指南" ("译文").

### 测试(从 `@dudousxd/nestjs-filter/testing`(中文(简体) )

-   **`FilterTestingModule`** - 说吧 `forRoot(options?)` 财务报告和审定财务报表 `forFeature(filters)`默认为 `validation: 'off'`。 。 。 .
-   **`makeMockQueryBuilder<E>()`** - 基于代理的模拟QB,记录所有的通话. 通过 `qb.calls`。 。 。 .

### 类型

-   **`FilterInput<F>`** -- 从过滤类中提取输入形状.
-   **`FilterContext`** - 说吧 `{ req?, user?, raw? }`。 。 。 .
-   **`FilterModuleOptions`** - 说吧 `{ inputNormalizer?, dropId?, onUnknownKey?, validation? }`。 。 。 .
-   **`ApplyFilterOptions`** - 说吧 `{ source?, dto?, resolve? }`。 。 。 .
-   **`InputSource`** - 说吧 `'auto' | 'query' | 'body' | ((req) => Record<string, unknown>)`。 。 。 .

## 配置

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `inputNormalizer` | `'camelCase' | 'snakeCase' | fn` | `'camelCase'` | 将输入键规范化 . |
| `dropId` | `boolean` | _明确设置_ | 脱去线索 `Id`编号 :`_id`。有效的默认值目前在代码中不一致——当运行到 `FilterRunner`编号 :`@ApplyFilter` 后缀被剥去,除非你通过 `dropId: false`。 。 。 . |
| `onUnknownKey` | `'ignore' | 'warn' | 'throw'` | `'ignore'` | 未确认的政策 **结构化 `filter` 密钥** (无) `@FilterFor`,自动字段,关系,计算出字段或聚合路径). a 内未知列 `where[]` 条款受下列条款制约: `throwOnInvalid` 换句话说. |
| `throwOnInvalid` | `boolean` | `false` | 何时 `true`,无效类型,不同字段,未知 `where[]` 列起a `BadRequestException` 而不是被丢弃 警告。 可超过每名 `@Filterable`。 。 。 . |
| `validation` | `'auto' | 'off'` | `'auto'` | 安装时使用类验证器验证. |

见 [根读取](https://npmcn.com/package/README.md) 用于完整文档.

## 常见问题

### @dudousxd/nestjs-filter 是什么？

NestJS过滤库——核心抽象,跑道,装饰\.

### 如何安装 @dudousxd/nestjs-filter？

在项目目录运行 npm install @dudousxd/nestjs-filter，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：rxjs（\>=7\.0\.0）、@nestjs/core（\>=10\.0\.0）、@nestjs/common（\>=10\.0\.0）、reflect-metadata（\>=0\.1\.13）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 nestjs-filter，可以用 npx nestjs-filter 直接运行。

### @dudousxd/nestjs-filter 支持 TypeScript 吗？

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

### @dudousxd/nestjs-filter 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dudousxd/nestjs-filter 需要什么版本的 Node\.js？

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

### @dudousxd/nestjs-filter 可以商用吗？

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

### @dudousxd/nestjs-filter 的下载量有多少？

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

### @dudousxd/nestjs-filter 还在维护吗？

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