# @clipboard-health/json-api-nestjs 中文文档

规范地址：https://npmcn.com/package/%40clipboard-health/json-api-nestjs/

版本：2\.14\.19
npm 元数据更新时间：2026-11-05T13:13:23.576Z
中文译文更新时间：2026-11-10T01:50:02.043Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40clipboard-health/json-api-nestjs
原文对照：https://npmcn.com/package/%40clipboard-health/json-api-nestjs/?lang=original
项目主页：https://github.com/ClipboardHealth/core-utils#readme
源码仓库：https://github.com/ClipboardHealth/core-utils

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

- 包体积（解压后）：53.1 kB，29 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：zod ^3，type-fest ^4 \|\| ^5\.0\.0
- 首次发布：2024-10-13T21:27:00.487Z
- 最新版本发布：2026-11-05T13:13:23.247Z
- 近 30 天下载量：76107（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：501（近 12 个月 396 个）

## 中文简介

TypeScript对坚持有NestJS的JSON:API规格的方便公用事业.

## 安装

```sh
npm install @clipboard-health/json-api-nestjs
```

也可以使用：`pnpm add @clipboard-health/json-api-nestjs`、`yarn add @clipboard-health/json-api-nestjs`、`bun add @clipboard-health/json-api-nestjs`

## README

# @clipboard-health/json-api-nestjs (英语)

用于遵守《公约》的方便脚本工具 [亚庇:](https://jsonapi.org/) 规格为 [网点JS](https://nestjs.com/)。 。 。 .

## 目录

-   [安装](https://npmcn.com/package/%40clipboard-health/json-api-nestjs/#readme-install)
-   [使用量](https://npmcn.com/package/%40clipboard-health/json-api-nestjs/#readme-usage)
    -   [查询助手](https://npmcn.com/package/%40clipboard-health/json-api-nestjs/#readme-query-helpers)
    -   [快速查询解析器](https://npmcn.com/package/%40clipboard-health/json-api-nestjs/#readme-express-query-parser)
    -   [oRPC程序](https://npmcn.com/package/%40clipboard-health/json-api-nestjs/#readme-orpc-procedures)
        -   [与 Qs 的差别](https://npmcn.com/package/%40clipboard-health/json-api-nestjs/#readme-differences-from-qs)
-   [地方发展指挥部](https://npmcn.com/package/%40clipboard-health/json-api-nestjs/#readme-local-development-commands)

## 安装

```bash
npm install @clipboard-health/json-api-nestjs
```

## 使用量

### 查询助手

为您的 API 查询创建 Zod 计划 :

```ts
import { booleanString } from "@clipboard-health/contract-core";
import {
  cursorPaginationQuery,
  fieldsQuery,
  type FilterMap,
  filterQuery,
  includeQuery,
  sortQuery,
} from "@clipboard-health/json-api-nestjs";
import { z } from "zod";

import type {
  ArticleAttributeFields,
  UserAttributeFields,
  UserIncludeFields,
} from "../src/contract";

const articleFields = ["title"] as const satisfies readonly ArticleAttributeFields[];
const userFields = ["age", "dateOfBirth"] as const satisfies readonly UserAttributeFields[];
const userIncludeFields = [
  "articles",
  "articles.comments",
] as const satisfies readonly UserIncludeFields[];
const userFilterMap = {
  age: {
    filters: ["eq", "gt"],
    schema: z.coerce.number().int().positive().max(125),
  },
  dateOfBirth: {
    filters: ["gte"],
    schema: z.coerce.date().min(new Date("1900-01-01")).max(new Date()),
  },
  isActive: {
    filters: ["eq"],
    schema: booleanString,
  },
} as const satisfies FilterMap<UserAttributeFields>;

/**
 * Disclaimer: Just because JSON:API supports robust querying doesn’t mean your service should
 * implement them as they may require database indexes, which have a cost. **Implement only access
 * patterns required by clients.**
 *
 * The spec says that if clients provide fields the server doesn’t support, it **MUST** return 400
 * Bad Request, hence the `.strict()`.
 */
export const query = z
  .object({
    ...cursorPaginationQuery(),
    ...fieldsQuery({ article: articleFields, user: userFields }),
    ...filterQuery(userFilterMap),
    ...sortQuery(userFields),
    ...includeQuery(userIncludeFields),
  })
  .strict();
```

### 快速查询解析器

查询助手期望 `req.query` 以锁定嵌入对象: `?filter[age][gt]=10` 必须在 `{ filter: { age: { gt: "10" } } }`。快递 5 的默认值 `simple` 查询解析叶 `filter[age][gt]` 作为一平一键,所以 `.strict()` 以 400 和 a 拒绝查询 非限制性的,静静地放下过滤器和页码.

设置 a `qs` 在 Nest app 上查询解析器 。 剪贴板服务可以使用 `createQueryParser()` 从 `@clipboard-health/api-nestjs` 17.0.0或以后:

```ts
import { createQueryParser } from "@clipboard-health/api-nestjs";
import { NestFactory } from "@nestjs/core";
import { type NestExpressApplication } from "@nestjs/platform-express";

import { AppModule } from "./app.module";

const app = await NestFactory.create<NestExpressApplication>(AppModule);
app.set("query parser", createQueryParser());
await app.listen(3000);
```

其他应用程序可以通过调用函数 [`qs`](https://github.com/ljharb/qs)是因为 `parse` 相反, 比如说 `app.set("query parser", (query: string) => qs.parse(query))`。 。 。 .

oLPC的路线不需要设置: 不读 `req.query`。见 [oRPC程序](https://npmcn.com/package/%40clipboard-health/json-api-nestjs/#readme-orpc-procedures)。 。 。 .

### oRPC程序

查询助手在 [oRPC 缩写:](https://orpc.dev/) 程序。 OLPC 解析查询字符串本身, 所以 宣布程序 `inputStructure: "detailed"` 将援助者的计谋 `query`数字 :

```ts
import { oc } from "@orpc/contract";
import { z } from "zod";

const query = z
  .object({
    ...cursorPaginationQuery(),
    ...filterQuery(userFilterMap),
    ...sortQuery(userFields),
  })
  .strict();

export const list = oc
  .route({ inputStructure: "detailed", method: "GET", path: "/users" })
  .input(z.object({ query }));
```

对于相同的查询字符串,帮助者返回的数值和验证问题与返回的相同 `qs` 和ts-rest,除了下面的差异. 以 OPPC 400 开头的路径 `query`。 。 。 . [`orpcQueryParsing.test.ts`](https://npmcn.com/package/%40clipboard-health/json-api-nestjs/src/lib/query/orpcQueryParsing.test.ts) 运行每个助手通过两个 解说者. `@orpc/*` 不是此软件包的依赖性或对等依赖性.

#### 与 Qs 的差别

oLPC的分解器按照参数出现的顺序构建了每个键的值. 当纯值 (单位:千美元)`filter[age]=10`后面是同一键上的一个括号内的密钥(`filter[age][gt]=5`, (中文(简体) ), `filter[age][eq]=20`, (中文(简体) ), `filter[age][]=20`它在计划看到它之前就抛弃了原值, 财务报告和审定财务报表 `qs` 留着吧 请求成功时没有这个值, 因此过滤器比客户端匹配更多 问取来. 帮助者无法恢复价值. 客户端每个密钥应发送一个样式: 设置操作员 首`filter[age][gt]=5&filter[age]=10` 工作),写 `filter[age][eq]=10` 明确或单独 带有逗号的值(`filter[age]=10,20`) (中文(简体) ). 这同样适用于 `sort`, (中文(简体) ), `include`,以及 `fields` (单位:千美元)`sort=age&sort[]=-age` 仅保留 `-age`) (中文(简体) ).

较小的差异 :

-   oLPC 拒绝类似原型的密钥 (`filter[__proto__][x]=1`, (中文(简体) ), `filter[hasOwnProperty]=1`有400个 从 `.strict()`。 。 。 . `qs` 与 `allowPrototypes: false` 悄悄地扔下他们.
-   oRPC 拒绝错误的括号密钥(`filter[age]]=10`)和一个空密钥(`=x`)与一出四百相会. `qs` 接受第一个并忽略第二个.
-   `filter[age][eq]=10&filter[age][]=20` 将两个值都保留在两个解析器下,但 `qs` 命令他们 `20, 10` 缩略语 `10, 20`。 。 。 .
-   oLPC没有参数限制. `qs` 与 `parameterLimit: 1000` 默默地将参数降于 头一千. 帮助者自己的数组限制仍然适用.

## 地方发展指挥部

见 [`package.json`](https://npmcn.com/package/%40clipboard-health/json-api-nestjs/package.json) `scripts` 用于命令列表.

## 常见问题

### @clipboard-health/json-api-nestjs 是什么？

TypeScript对坚持有NestJS的JSON:API规格的方便公用事业\.

### 如何安装 @clipboard-health/json-api-nestjs？

在项目目录运行 npm install @clipboard-health/json-api-nestjs，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^3）、type-fest（^4 \|\| ^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @clipboard-health/json-api-nestjs 支持 TypeScript 吗？

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

### @clipboard-health/json-api-nestjs 支持 ESM 还是 CommonJS？

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

### @clipboard-health/json-api-nestjs 可以商用吗？

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

### @clipboard-health/json-api-nestjs 的下载量有多少？

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

### @clipboard-health/json-api-nestjs 还在维护吗？

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