# @chax-at/prisma-filter 中文文档

规范地址：https://npmcn.com/package/%40chax-at/prisma-filter/

版本：5\.0\.0
npm 元数据更新时间：2026-01-28T12:35:41.926Z
中文译文更新时间：2026-11-09T11:38:17.465Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40chax-at/prisma-filter
原文对照：https://npmcn.com/package/%40chax-at/prisma-filter/?lang=original
项目主页：https://github.com/chax-at/prisma-filter#readme
源码仓库：https://github.com/chax-at/prisma-filter

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

- 包体积（解压后）：49.5 kB，16 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 18
- 运行依赖：1 个
- peer 依赖：@nestjs/common 6 - 11
- 首次发布：2022-03-02T13:43:33.907Z
- 最新版本发布：2026-01-28T12:31:22.816Z
- 近 30 天下载量：5914（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 1 个）

## 中文简介

PrismaFilter 软件包允许前端通过查询参数请求过滤,排序和分解的数据. 软件包会自动生成Prisma从这些查询参数中找到选项,然后可以在后端直接使用.

## 安装

```sh
npm install @chax-at/prisma-filter
```

也可以使用：`pnpm add @chax-at/prisma-filter`、`yarn add @chax-at/prisma-filter`、`bun add @chax-at/prisma-filter`

## README

# @chax-at/prisma-filter (英语)

此软件包提供了 [网点JS](https://github.com/nestjs/nest) 变形管 REST 查询参数为 `findOption`s 用于 [普里斯马](https://github.com/prisma/prisma)。 。 。 . 查询参数使用与 [制表符](http://tabulator.info/docs/5.1/filter#ajax-filter)。 。 。 .

## QQ 为巢穴11+发出警告

使用 NestJS 11+,您必须启用扩展查询解析器,否则过滤解析器将无法工作(参见 [移徙指南](https://docs.nestjs.com/migration-guide#query-parameters-parsing):

```ts
async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule); // <-- Make sure to use <NestExpressApplication>
  app.set('query parser', 'extended'); // <-- Add this line
  await app.listen(3000);
}
```

## 用法 - 前端

首先,通过运行安装所有需要的类型

```
npm i @chax-at/prisma-filter-common
```

然后,如果您想要过滤 + pagination 某个请求的结果,您可以发送符合 页:1 `IFilter` 界面.

```
http://localhost:3000/api/admin/orders?offset=10&limit=10&filter[0][field]=id&filter[0][type]==&filter[0][value]=2&filter[1][field]=name&filter[1][type]=like&filter[1][value]=%Must%&order[0][field]=name&order[0][dir]=asc
```

检查 `FilterOperationType` 显示所有可能的过滤类型 。 请注意,默认情况下,所有过滤值都是 a. 被作为《公约》 `string`, (中文(简体) ), `number` (或 `string[]`编号 :`number[]` 页:1 `in`\- 过滤器。 如果你想通过过滤 `null` 换成 联 合 国 `'null'`,然后使用 `EqNull`编号 :`NeNull` 过滤器类型( 此处忽略给定的值) .

### 建立过滤器

此软件包提供了 `FilterBuilder<T>` 用于创建过滤器的类 :

```typescript
import { FilterBuilder, FilterOperationType } from '@chax-at/prisma-filter-common';

const filterBuilder = new FilterBuilder<User>() // create a new filter builder for User entities..
        .addFilter('name', FilterOperationType.Ilike, '%Max%') // ...filter by name ilike '%Max%'
        .addOrderBy('name', 'asc') // ...order by name, asc
        .setPageSize(40) // ...paginate with a pagesize of 40
        .requestPage(3); // ...return the third page
const filter = filterBuilder.toFilter(); // get the resulting IFilter<User>
const queryString = filterBuilder.toQueryString(); // get the resulting query string (as described below)

// Note that you can also re-use the same filter if you just want to request a different page without changing filter or ordering:
const firstPageFilter = filterBuilder.requestPage(1).toFilter();
```

#### 构建查询字符串

归根结底,需要一个查询字符串,将发送给后端服务器。 要构建此查询字符串, 您可以使用 `FilterBuilder.toQueryString()` 使用上述过滤器构建过滤器时. 然而,也可以将现有的过滤器转换为查询字符串:

```typescript
const queryString = FilterBuilder.buildFilterQueryString({
  limit: 20,
  offset: 30,
  filter: [
    { field: 'field1', type: FilterOperationType.NeNull, value: 'val1' },
    { field: 'field2', type: FilterOperationType.InStrings, value: ['str1', 'str2'] },
  ],
  order: [
    { field: 'field1', dir: 'asc' },
    { field: 'field2', dir: 'desc' },
  ],
});
// queryString is
// ?offset=30&limit=20&filter[0][field]=field1&filter[0][type]=nenull&filter[0][value]=val1&filter[1][field]=field2&filter[1][type]=instrings&filter[1][value][]=str1&filter[1][value][]=str2&order[0][field]=field1&order[0][dir]=asc&order[1][field]=field2&order[1][dir]=desc
```

### 过滤类型

-   `Eq`, (中文(简体) ), `Ne` 检查严格的(不平等)平等。 用于数字和布林斯.
-   `EqString`, (中文(简体) ), `NeString` 字符串( in) 平等检查字符串 。 不转换数字或布尔 与 `Eq` 财务报告和审定财务报表 `Ne`。 。 。 .
-   `Lt`, (中文(简体) ), `Lte`, (中文(简体) ), `Gt`, (中文(简体) ), `Gte` 用于通过检查数字是否大于/小于(或等于)值来过滤数字
-   `Contains` 转换为 Prisma `contains`,用于筛选字符串。 使用 `%` 作为通配符,例如:. `%Max%` 查找部分匹配.
-   `IContains` 就像是 `Contains` 但是对大小写不敏感
-   `StartsWith`, (中文(简体) ), `EndsWith`, (中文(简体) ), `Search` 匹配相应的 [Prisma 操作](https://www.prisma.io/docs/reference/api-reference/prisma-client-reference#filter-conditions-and-operators)。这些过滤器的前缀为 `I` 如果您想要过滤大小写不敏感( 例如) . `IStartsWith`(中文(简体) )
-   `In` 检查值是否在给定的数字数组中。 使用 `InStrings` 用于字符串阵列.
-   `InStrings` 检查值是否在给定的字符串数组中.
-   `NotIn` 检查该值是否不在给定的数字数组中。 使用 `NotInStrings` 用于字符串阵列.
-   `NotInStrings` 检查值是否不在给定的字符串数组中.
-   `EqNull`, (中文(简体) ), `NeNull` 检查该值是否无效。 必须使用代替 `Eq`, (中文(简体) ), `Ne` 因为不然 `null` 将被视为字符串
-   `ArrayContains`, (中文(简体) ), `ArrayStartsWith`, (中文(简体) ), `ArrayEndsWith` 可用于 [Prisma 阵列](https://www.prisma.io/docs/orm/reference/prisma-client-reference#array_contains)
-   `Has`, (中文(简体) ), `HasString`, (中文(简体) ), `HasSome`, (中文(简体) ), `HasSomeString`, (中文(简体) ), `HasEvery`, (中文(简体) ), `HasEveryString`

### 过滤值类型

由于过滤器是通过查询参数传输的,所以所有东西都会被转换为字符串. 这个图书馆会 根据这些规则自动转换过滤值 :

-   如果过滤器类型是 `Eq`, (中文(简体) ), `Ne` 值是“ 真” 或“ 假” , 然后转换成布尔
    -   使用 `EqString`, (中文(简体) ), `NeString` 如果您想要过滤字符串而不转换它
-   如果过滤器类型不是 `Like` 或者说 `...String` ,其值为数字(或数字数组) `In`),然后转换为数字(或数字数组)
-   否则,该值将被视为字符串

对于字符串过滤器 `Like` 或者说 `Ilike` 筛选类型被推荐,因为通常需要部分搜索. 但是,如果想要对字符串使用不同的过滤器,请确保使用 `...String` 备选案文 [瑞秋真爱](https://twitter.com/racheltrue/status/1365461618977476610) 不能通过她的名字过滤.

## 用法 - 后端

此套件输出 二 [管道](https://docs.nestjs.com/pipes),则 `DirectFilterPipe` (在大多数情况下都使用) 较普通 `FilterPipe`。也可以使用导出 `FilterParser` 要转换的类 人工查询参数.

### 先决条件

首先,通过运行安装软件包

```
npm i @chax-at/prisma-filter
```

你还需要 `@nestjs/common` 已安装,目前支持6-10版本. 此套件还输出所有来自 `prisma-filter-common` 因此,不需要安装两个软件包.

要验证用户查询输入,您可能需要提供附加注释的自己的接口执行 验证限制。 如果你使用类验证器和类转换器, 这个定义可以像这样 (为您的工程设定抵消+限制的制约和默认值):

```typescript
import { FilterOperationType, FilterOrder, GeneratedFindOptions, IFilter, IGeneratedFilter, ISingleFilter, ISingleOrder } from '@chax-at/prisma-filter';
import { Type } from 'class-transformer';
import { IsArray, IsDefined, IsEnum, IsIn, IsInt, IsOptional, IsString, Max, Min, ValidateNested } from 'class-validator';

// The fields are also validated in filter.parser.ts to make sure that only correct fields are used to filter
export class SingleFilter<T> implements ISingleFilter<T> {
  @IsString()
  field!: keyof T & string;

  @IsEnum(FilterOperationType)
  type!: FilterOperationType;

  @IsDefined()
  value: any;
}

export class SingleFilterOrder<T> implements ISingleOrder<T> {
  @IsString()
  field!: keyof T & string;

  @IsIn(['asc', 'desc'])
  dir!: FilterOrder;
}

export class Filter<T = any> implements IFilter<T> {
  @IsArray()
  @ValidateNested({ each: true })
  @Type(() => SingleFilter)
  @IsOptional()
  filter?: Array<SingleFilter<T>>;

  @IsArray()
  @ValidateNested({ each: true })
  @Type(() => SingleFilterOrder)
  @IsOptional()
  order?: Array<SingleFilterOrder<T>>;

  @Type(() => Number)
  @IsInt()
  @Min(0)
  offset = 0;

  @Type(() => Number)
  @IsInt()
  @Min(1)
  @Max(500)
  limit = 100;
}

export class FilterDto<TWhereInput> extends Filter implements IGeneratedFilter<TWhereInput> {
  // This will be set by filter pipe
  findOptions!: GeneratedFindOptions<TWhereInput>;
}
```

这个readme假设您正在使用上面的文件,但您可以根据需要调整下面示例中使用的类型.

### 直肠管

从查询参数 1:1 到数据库字段的直接过滤管映射字段. 这通常是你的管子 想要使用。 .

要启用过滤, 您可以导入并使用 `DirectFilterPipe<TDto, TWhereInput>(keys, compoundKeys?)`。完整的例子:

```typescript
// Controller
import { Prisma } from '@prisma/client';
// ...

@Controller('/some/path')
export class SomeController {
  constructor(private readonly someService: SomeService) {}

  @Get()
  public async getOrders(
    @Query(new DirectFilterPipe<any, Prisma.OrderWhereInput>(
      ['id', 'status', 'createdAt', 'refundStatus', 'refundedPrice', 'paymentDate', 'totalPrice', 'paymentMethod'],
      ['event.title', 'user.email', 'user.firstname', 'user.lastname', 'contactAddress.firstName', 'contactAddress.lastName'],
    )) filterDto: FilterDto<Prisma.OrderWhereInput>,
  ) {
    return this.someService.getOrders(filterDto.findOptions);
  }
}
```

```typescript
// Service

@Injectable()
export class SomeService {
  constructor(private readonly prismaService: PrismaService) {}

  public async getOrders(findOptions: Prisma.OrderFindManyArgs) {
    return this.prismaService.order.findMany({
      ...findOptions,
      // Is is now possible, to add custom options like include
      include: {
        user: true,
      },
      // Note that you cannot simply add `where` here, because you would override the definition from the findOptions
      // Change findOptions.where instead if you want to add additional conditions
    })
  }
}
```

#### 一般类型

-   `TDto` 是描述过滤查询参数的类型。 可以设定为 `any` 由于名字是地图1: 1
-   `TWhereInput` 是目标棱镜类型并键入可过滤键.

#### 参数

-   `keys` 是第一个参数,是所有可以直接在顺序输入中过滤的密钥的列表, 不包括任何关系。 这些类型已检查 .
-   `compoundKeys` (可选)可用于查询相关字段,例如,如果您 `Order` 模型有关系 `user`,然后可以过滤 `user.email`如果关系为1:n或n:n类似 `articles` 在一个 `Order`,然后你可以使用 [相应的棱镜语法](https://www.prisma.io/docs/concepts/components/prisma-client/relation-queries#filter-on--to-many-relations) ,比如说. `articles.some.title` 以过滤含有至少一条带有给定标题的命令. 未检查这些类型 .

#### 默认排序顺序

特别是在使用平面图时,你应该总是定义排序顺序,这样平面图就稳定了. 您可以定义默认排序顺序 创建时 `DirectFilterPipe` 除非同一密钥已经定义,否则将总是添加.

```typescript
export class SomeController {
  @Get()
  public async getOrders(
    @Query(new DirectFilterPipe<any, Prisma.OrderWhereInput>(
      ['id', 'status', 'createdAt', 'refundStatus', 'refundedPrice', 'paymentDate', 'totalPrice', 'paymentMethod'],
      ['event.title', 'user.email', 'user.firstname', 'user.lastname', 'contactAddress.firstName', 'contactAddress.lastName'],
      // Always add sort by `createdAt` ascending. Use the id as 2nd sorting criteria if the createdAt is equal. 
      [{ createdAt: 'asc' }, { id: 'asc' }],
    )) filterDto: FilterDto<Prisma.OrderWhereInput>,
  ) {
    // ...
  }
}
```

根据上述代码,可以提出下列请求:

| 请求令 | 产生顺序 |
| --- | --- |
| 无排序顺序 | 创建At(asc) - > id(asc) |
| 总价( asc) | 总价(asc) - > 创建At(asc) - > id(asc) |
| 代码( desc) | id( desc) - > 创建At( asc) |

#### 虚拟字段

如果您在组合键前加了前缀 `!`,然后被过滤管所忽略。 你可以用这个,如果你 如果设置了某个过滤器, 则想要执行一些自定义逻辑, 例如 .

```typescript
export class SomeController {
  @Get()
  public async getOrders(
    @Query(new DirectFilterPipe<any, Prisma.OrderWhereInput>(
      [],
      ['!paymentInAdvance'],
    )) filterDto: FilterDto<Prisma.OrderWhereInput>,
  ) {
    if(filterDto.filter?.some(f => f.field === '!paymentInAdvance')) {
      console.log('The paymentInAdvance filter is set, now I can do whatever I want!');
    }
  }
}
```

### 万事无虞

这个 `AllFilterPipeUnsafe` 是一种管道,如果您想要允许过滤模型的所有字段,它可以更方便地使用. 复合键仍需要如上所描述的具体说明.

> : 警告: 这允许用户读取模型的所有密钥, 即使您不返回数据 (例如,通过发送像过滤器一样的多重,直到用户知道全部值).
> 
> 确定您的模型不包含字段中的任何敏感数据( 例如, 不使用此管 ) `users` 表格为 (单位:千美元) `password` 页:1.

```typescript
export class SomeController {
  constructor(private readonly someService: SomeService) {}

  @Get()
  public async getOrders(
    @Query(new AllFilterPipeUnsafe<any, Prisma.OrderWhereInput>(
      ['event.title', 'user.email', 'user.firstname', 'user.lastname', 'contactAddress.firstName', 'contactAddress.lastName', '!paymentInAdvance'],
    )) filterDto: FilterDto<Prisma.OrderWhereInput>,
  ) {
    return this.someService.getOrders(filterDto.findOptions);
  }
}
```

### 过滤管道

这个 `FilterPipe` 工作像一个 `DirectFilterPipe`,但参数是一个可以映射某些 查询对象的不同密钥名称的参数名称,例如:.

```
{
  // the query parameter is frontendUsernameFilterName, but will filter on the name field of the object
  'frontendUsernameFilterName': 'name',
}
```

### 过滤器

你可以用这个 `FilterParser` 生成 prisma 选项而不使用管道.

## 常见问题

### @chax-at/prisma-filter 是什么？

PrismaFilter 软件包允许前端通过查询参数请求过滤,排序和分解的数据\. 软件包会自动生成Prisma从这些查询参数中找到选项,然后可以在后端直接使用\.

### 如何安装 @chax-at/prisma-filter？

在项目目录运行 npm install @chax-at/prisma-filter，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@nestjs/common（6 - 11）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @chax-at/prisma-filter 支持 TypeScript 吗？

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

### @chax-at/prisma-filter 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @chax-at/prisma-filter 需要什么版本的 Node\.js？

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

### @chax-at/prisma-filter 可以商用吗？

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

### @chax-at/prisma-filter 的下载量有多少？

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

### @chax-at/prisma-filter 还在维护吗？

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