# @bitovi/querystring-parser 中文文档

规范地址：https://npmcn.com/package/%40bitovi/querystring-parser/

版本：0\.8\.1
npm 元数据更新时间：2026-05-21T14:19:15.496Z
中文译文更新时间：2026-11-08T04:39:47.866Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bitovi/querystring-parser
原文对照：https://npmcn.com/package/%40bitovi/querystring-parser/?lang=original
项目主页：https://www.bitovi.com/nodejs
源码仓库：https://github.com/bitovi/querystring-parser

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

- 包体积（解压后）：144 kB，42 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2022-05-13T22:21:25.858Z
- 最新版本发布：2023-12-14T15:46:22.688Z
- 近 30 天下载量：4821（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 0 个）

## 中文简介

![Tests Workflow Status](https://github.com/bitovi/querystring-parser/actions/workflows/tests.yml/badge.svg?branch=main) \[![Join our Slack](https://img.shields.io/badge/slack-join%20chat-611f69.svg)\[(\][https://www.bitovi.com/community/slack?utm source=badge 页面存档备份,存于互联网档案馆](https://www.bitovi.com/community/slack?utm_source=badge)

## 安装

```sh
npm install @bitovi/querystring-parser
```

也可以使用：`pnpm add @bitovi/querystring-parser`、`yarn add @bitovi/querystring-parser`、`bun add @bitovi/querystring-parser`

## README

# 查询字符串- parser

![Tests Workflow Status](https://github.com/bitovi/querystring-parser/actions/workflows/tests.yml/badge.svg?branch=main) [![Join our Slack](https://img.shields.io/badge/slack-join%20chat-611f69.svg)](https://www.bitovi.com/community/slack?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

-   [为什么是查询- parser?](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-why-querystring-parser)
-   [安装](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-installation)
-   [使用量](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-usage)
    -   [排序参数](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-sort-parameters)
    -   [倾角参数](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-pagination-parameters)
    -   [包含参数](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-include-parameters)
    -   [字段参数](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-fields-parameters)
    -   [过滤参数](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-filter-parameters)
    -   [MongoDB- Style 过滤参数](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-mongodb-style-filter-parameters)
        -   [快速示例](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-quick-examples)
        -   [MongoDB - 样式运算符](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-mongodb-style-operators)
        -   [关闭运算符](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-omitted-operators)
        -   [阵列](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-arrays)
        -   [化合物过滤器](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-compound-filters)
    -   [IBM- Style 过滤参数](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-ibm-style-filter-parameters)
        -   [快速示例](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-quick-examples-1)
        -   [IBM- Style 操作器](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-ibm-style-operators)
        -   [属性参考](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-attribute-references)
        -   [化合物过滤器](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-compound-filters-1)
-   [发展/贡献](https://npmcn.com/package/%40bitovi/querystring-parser/#readme-development--contributing)
-   [内容](https://github.com/bitovi/querystring-parser#readme)

## 为什么是查询- parser?

审议下列情况:

-   你正在制作一个标准的 CRUD 应用程序, 更多或更少跟随 [JSON:API规格](https://jsonapi.org/format/)
-   此应用程序将接收 HTTP 以查询字符串获取请求, 如以下示例中 :
    -   `?filter[start_date][$gt]=2020-01-01`
    -   `?sort=-date,name&page[number]=1&page[size]=5`
    -   `?fields[articles]=title,body&fields[people]=name`
-   您需要解析这些查询参数以获取请求的数据 。 此库为您进行查询字符串分析 .

## 安装

```sh
npm install @bitovi/querystring-parser
```

如果你打算用这个图书馆 [反对](https://vincit.github.io/objection.js/) 或者说 [排序](https://sequelize.org/),不安装 `@bitovi/querystring-parser`。反之,安装:

-   [`@bitovi/objection-querystring-parser`](https://github.com/bitovi/querystring-parser/tree/main/packages/objection#readme)
-   [`@bitovi/sequelize-querystring-parser`](https://github.com/bitovi/querystring-parser/tree/main/packages/sequelize#readme)

## 使用量

```js
const querystringParser = require("@bitovi/querystring-parser");

const { page } = querystringParser.parse("page[number]=1&page[size]=10");
console.log(page.number); // --> 1
console.log(page.size); // --> 10
```

### 排序参数

分析结果 `sort` 查询参数存储于 `sort` 属性. 其价值 `sort` 属性是一组“类型字段”对象。 每个"类型字段"对象都包含一个字段名称和排序方向.

参考: [JSON:API - 排序](https://jsonapi.org/format/#fetching-sorting)

```js
const { sort } = querystringParser.parse("sort=-date,name");
console.log(sort[0]); // --> { field: 'date', direction: 'DESC' }
console.log(sort[1]); // --> { field: 'name', direction: 'ASC' }
```

### 倾角参数

分析结果 `page` 查询参数存储于 `page` 属性。 其价值 `page` 属性是一个有 2 个密钥的对象 : `number` 财务报告和审定财务报表 `size`。 。 。 .

参考: [JSON:API - 铺设](https://jsonapi.org/format/#fetching-pagination)

```js
const { page } = querystringParser.parse("page[number]=1&page[size]=10");
console.log(page.number); // --> 1
console.log(page.size); // --> 10
```

### 包含参数

分析结果 `include` 查询参数存储于 `include` 属性。 其价值 `include` 属性是一组“关系路径”.

参考: [JSON:API - 包含相关资源](https://jsonapi.org/format/#fetching-includes)

```js
const { include } = querystringParser.parse("include=children.movies.actors.children,children.movies.actors.pets,children.pets,pets");
console.log(include[0]); // --> 'children.movies.actors.children'
console.log(include[1]); // --> 'children.movies.actors.pets'
console.log(include[2]); // --> 'children.pets'
console.log(include[3]); // --> 'pets'
```

### 字段参数

分析结果 `fields[TYPE]` 查询参数存储于 `fields` 属性。 其价值 `fields` 属性是一个对象。 对于该对象中的每个密钥值对,密钥是类型的名称,而该值是该类型的一个字段数组.

参考: [JSON:API - Sparse 场集](https://jsonapi.org/format/#fetching-sparse-fieldsets)

```js
const { fields } = querystringParser.parse("fields[articles]=title,body&fields[people]=name");
console.log(fields.articles); // --> [ 'title', 'body' ]
console.log(fields.people); // --> [ 'name' ]
```

### 过滤参数

分析结果 `filter` 查询参数存储于 `filter` 属性。 有2个"风格"的查询字符串过滤器被支持. "MongoDB-Style"和"IBM-Style". 虽然它们有自己的惯例,但它们都产生同样的产出。 如果需要,可以使用这两种样式,但不能在同一个查询字符串中.

* * *

### MongoDB- Style 过滤参数

蒙戈DB-Style的基地来自 [MongoDB 比较查询操作员](https://www.mongodb.com/docs/manual/reference/operator/query-comparison/)。 。 。 .

#### 快速示例

| 查询过滤器 | 解析输出 |
| --- | :-: |
| 过滤器\[名\]=brad | `{ LIKE: [ '#name', '%brad%' ] }` |
| 过滤器\[名称\]\[$eq\]=mike | `{ '=': [ '#name', 'mike' ] }` |
| 过滤器\[年龄\]\[$gt\]=21 | `{ '>': [ '#age', 21 ] }` |
| 过滤器 \[生 \[$lte\] = 2020-01-01 | `{ '<=': [ '#born', '2020-01-01' ] }` |
| 过滤器\[分 \[$eq\] | `{ 'IS NULL': '#score' }` |
| 过滤器 \[名称\]\[美元\] = michael, brad | `{ IN: [ '#name', 'michael', 'brad' ] }` |

#### MongoDB - 样式运算符

以下是MongoDB-Style运算符及其相容值类型的完整列表.

| 运算符 | 字符串 | 数字 | 日期 | 无效 | 数组 |
| --- | :-: | :-: | :-: | :-: | :-: |
| (单位:美元) | ✅ | ✅ | ✅ | ✅ | ❌ |
| (单位:美元) | ✅ | ✅ | ✅ | ✅ | ❌ |
| 单位 $gt | ✅ | ✅ | ✅ | ❌ | ❌ |
| $gte (单位:千美元) | ✅ | ✅ | ✅ | ❌ | ❌ |
| (单位:美元) | ✅ | ✅ | ✅ | ❌ | ❌ |
| (单位) | ✅ | ✅ | ✅ | ❌ | ❌ |
| 喜欢 | ✅ | ❌ | ❌ | ❌ | ❌ |
| (单位:美元) | ✅ | ✅ | ✅ | ✅ | ✅ |
| (单位:百万美元) | ✅ | ✅ | ✅ | ✅ | ✅ |

#### 关闭运算符

MongoDB-Style过滤器不需要明确的运算符. 在许多情况下,数值类型足以让解析器推断出哪一个操作员可以使用. 下面的例子显示了每个值类型的操作员推论.

| 数值类型 | 示例 | 产出 |
| --- | :-: | :-: |
| 字符串 | 过滤器\[名\]=lisa | `{ LIKE: [ '#name', '%lisa%' ] }` |
| 编号 | 过滤器\[年龄\]=25 | `{ '=': [ '#age', 25 ] }` |
| 日期 | 过滤器\[生\]=2020-01-01 | `{ '=': [ '#born', '2020-01-01' ] }` |
| 无效 | 过滤器\[分数\]%%%%% | `{ 'IS NULL': '#score' }` |
| 数组 | 过滤器\[名\]=mike, brad | `{ IN: [ '#name', 'mike', 'brad' ] }` |

#### 阵列

以下示例说明可如何指定数组值.

-   使用重复查询参数 :
    -   `filter[age][$in]=24&filter[age][$in]=25&filter[age][$in]=26`
-   使用逗号( U)`,`:
    -   `filter[age][$in]=24,25,26`

两种样式将产生相同的输出: `{ IN: [ '#age', 24, 25, 26 ] }`

#### 化合物过滤器

MongoDB-Style过滤器不直接支持高阶操作员(`AND` 编号 : `OR` 编号 : `NOT`) (中文(简体) ). 然而,如果在查询字符串中存在多个过滤器,则它们将被合并在一起 `AND` 时尚.

```js
// example of 2 filters getting "AND"-ed together into a compound filter
const { filter } = querystringParser.parse("filter[name]=mike&filter[age]=25");
expect(filter).toEqual({
  AND: [
    { LIKE: ["#name", "%mike%"] },
    { "=": ["#age", 25] }
  ]
});
```

* * *

### IBM- Style 过滤参数

IBM-Style基于 [jsonapi.net 过滤规格](https://www.jsonapi.net/usage/reading/filtering.html)。 。 。 .

#### 快速示例

| 查询过滤器 | 解析输出 |
| --- | :-: |
| 过滤器=容器( 名称, “ brad ”) | `{ LIKE: [ '#name', '%brad%' ] }` |
| filter=等分 (名称, “mike ”) | `{ '=': [ '#name', 'mike' ] }` |
| 过滤器=大Than(年龄,'25') | `{ '>': [ '#age', 25 ] }` |
| filter= less OrEqual(生,'2020-01-01') (中文(简体) ) | `{ '<=': [ '#born', '2020-01-01' ] }` |
| filter= any (名称, “ brad” , “mike” ) | `{ IN: [ '#name', 'brad', 'mike' ] }` |
| 过滤器=等分( 分数, null) | `{ 'IS NULL': '#score' }` |
| filter=not(等值(年龄,'25')) | `{ NOT: { "=": ["#age", 25] } }` |
| filter=和(任何(年龄,'10','20'),等值(名称,'mike')) | `{ AND: [{ IN: ["#age", 10, 20] }, { "=": ["#name", "mike"] }] }` |
| filter=或(任何(年龄,'10','20'),等分(名称,'mike')) | `{ OR: [{ IN: ["#age", 10, 20] }, { "=": ["#name", "mike"] }] }` |

#### IBM- Style 操作器

以下是IBM-Style操作器及其相容值类型的完整列表.

| 运算符 | 字符串 | 数字 | 日期 | 属性参考文件 | 无效 | 嵌入式运算符 |
| --- | :-: | :-: | :-: | :-: | :-: | :-: |
| 等于 | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| 大调 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| 大正数 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| 小谭 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| 小于正数 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| 包含 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 启动时间 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 结束 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 任意 | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ |
| 没有 | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| 财务报告和审定财务报表 | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| 或者说 | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |

#### 属性参考

一些IBM-Style操作器可以直接比较出两个不同的属性(或"列"). 以下文为例, `wins` 财务报告和审定财务报表 `losses` 是属性引用(相对于常数,例如 `'emily'` 或者说 `'22'`) (中文(简体) ).

通过常规,属性引用在解析输出中被前缀为"#",以区别于常数.

```js
// example attribute references
const { filter } = querystringParser.parse("filter=greaterThan(wins,losses)");
expect(filter).toEqual({ ">": ["#wins", "#losses"] });
```

#### 化合物过滤器

IBM-Style过滤器直接支持更高级的操作员(`AND` 编号 : `OR` 编号 : `NOT`) (中文(简体) ). 此外,如果查询字符串中存在多个过滤器,它们将合并在一起 `OR` 时尚.

```js
// example of 2 filters getting "OR"-ed together into a compound filter
const { filter } = querystringParser.parse("filter=contains(name,'mike')&filter=equals(age,'25')");
expect(filter).toEqual({
  OR: [
    { LIKE: ["#name", "%mike%"] },
    { "=": ["#age", 25] }
  ]
});
```

## 发展/贡献

见 [捐款额](https://npmcn.com/package/%40bitovi/querystring-parser/CONTRIBUTING.md)

## 常见问题

### @bitovi/querystring-parser 是什么？

\[\[\(\]https://www\.bitovi\.com/community/slack?utm source=badge 页面存档备份,存于互联网档案馆

### 如何安装 @bitovi/querystring-parser？

在项目目录运行 npm install @bitovi/querystring-parser，或使用 pnpm add / yarn add / bun add。

### @bitovi/querystring-parser 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bitovi\_\_querystring-parser 是否存在。

### @bitovi/querystring-parser 支持 ESM 还是 CommonJS？

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

### @bitovi/querystring-parser 可以商用吗？

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

### @bitovi/querystring-parser 的下载量有多少？

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

### @bitovi/querystring-parser 还在维护吗？

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