# @haddowg/json-api-query 中文文档

规范地址：https://npmcn.com/package/%40haddowg/json-api-query/

版本：1\.7\.2
npm 元数据更新时间：2026-11-16T22:58:48.709Z
中文译文更新时间：2026-11-17T18:23:18.822Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40haddowg/json-api-query
原文对照：https://npmcn.com/package/%40haddowg/json-api-query/?lang=original
项目主页：https://haddowg.github.io/json-api-ts/
源码仓库：https://github.com/haddowg/json-api-ts

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

- 包体积（解压后）：316 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- peer 依赖：@tanstack/query-core ^5\.0\.0
- 首次发布：2026-07-13T10:50:39.580Z
- 最新版本发布：2026-11-16T22:58:48.378Z
- 近 30 天下载量：4604（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 29 个）

## 中文简介

TanStack 查询 JSON:API客户端的绑定:选项/关键工厂+类型:id缓存正常化.

## 安装

```sh
npm install @haddowg/json-api-query
```

也可以使用：`pnpm add @haddowg/json-api-query`、`yarn add @haddowg/json-api-query`、`bun add @haddowg/json-api-query`

## README

# @ haddowg/ json- api- query

> **部分 [jsonapi.rest (英语)](https://jsonapi.rest/) 套间** - 完整、符合规格 JSON: API 1. 1 堆栈: 框架不可知 PHP [核心项目](https://github.com/haddowg/json-api)页:1 [符号捆绑](https://github.com/haddowg/json-api-symfony)页:1 [Laravel 软件包](https://github.com/haddowg/json-api-laravel)这个 **键入类型脚本 客户端**,由经过检测的OpenAPI 3.1合同捆绑在一起. 完整文档: **[(原始内容存档于2018-10-21) (韩语). haddog.github.io/json-api-ts](https://haddowg.github.io/json-api-ts/)**。 。 。 .

TanStack 查询绑定 [`@haddowg/json-api-client`](https://npmcn.com/package/%40haddowg/client) 运行时间: 查询/更改 **选项工厂** (不是先入为主的钩子),一个决定式的查询键厂,然后说 `type:id` 写入缓存正常化.

因为表面是选择工厂 `@tanstack/query-core`,一个装订盖 反应 / Vue / Svelte / Solid —— 您通过返回 `{ queryKey, queryFn }` 编号 : `MutationOptions` 到你的框架 `useQuery` 编号 : `useMutation`。 。 。 .

## 安装

```bash
pnpm add @haddowg/json-api-query @tanstack/query-core
```

`@tanstack/query-core` 是同级依赖.

## 绑定客户端

读取工厂接受 `Client<D, A>` 和写作厂 `Client<D, A, W>` - 也没有 包含客户端的自定义动作类型(动作不是可缓存的资源). 生成的 `createClient` 返回客户端 _(单位:千美元)_ 带有动作类型,因此通过 动作不可知性 `Client` 查询边界上的类型——每平面投出一个:

```ts
import type { Client } from '@haddowg/json-api-client'
import { createClient } from './api/music.gen'
import type { Attributes, ResourceMap, WriteAttributes } from './api/music.gen'

const client = createClient({ baseUrl: 'https://music.example' })

type ReadClient = Client<ResourceMap, Attributes>
type WriteClient = Client<ResourceMap, Attributes, WriteAttributes>
```

## 读取 - 查询选项工厂

每个工厂都返回平原 `{ queryKey, queryFn }`,在结构上与查询核心兼容 `QueryOptions`,保留客户端的全静态收缩(`include` 宽度, `fields` (原始内容存档于2018-09-25). Grains. 两种同等形式:

```ts
import { createQueryApi, listQueryOptions } from '@haddowg/json-api-query'

// Bound API — the cleanest per-type call shape.
const reads = createQueryApi(client as unknown as ReadClient)
const listOpts = reads.albums.list({ include: ['artist'] })
const getOpts = reads.albums.get('1')
const relOpts = reads.albums.relationship('1', 'tracks') // linkage
const relatedOpts = reads.albums.related('1', 'tracks') // related collection

// Standalone factories — equivalent, with `client`/`type` passed explicitly.
const listOpts2 = listQueryOptions(client as unknown as ReadClient, 'albums', {
  include: ['artist'],
})

// Pass to your framework's useQuery, or fetch directly:
const albums = await queryClient.fetchQuery(listOpts)
```

独立的工厂是 `listQueryOptions`, (中文(简体) ), `getQueryOptions`, (中文(简体) ), `relationshipQueryOptions`, (中文(简体) ), `relatedQueryOptions`。 。 。 .

## 查询键厂

键是稳定的,等级化的只读的tuple—— `[type, operation, id?, rel?, params?]`编辑 分级是合同目标无效 : `[type]` 无效整个类型, `[type, operation]` 一个操作的子树, `[type, 'fetchOne', id]` (单位:千美元) 单资源。 params 将最后一个部分作为正态对象来骑行,所以两个相模相等 查询(按键重排,等值)共享一键.

```ts
import { keyFor, operationKey, resourceKey, typeKey } from '@haddowg/json-api-query'

keyFor({ type: 'albums', operation: 'fetchOne', id: '1' }) // ['albums', 'fetchOne', '1']
typeKey('albums') // ['albums']
operationKey('albums', 'fetchMany') // ['albums', 'fetchMany']
resourceKey('albums', '1') // ['albums', 'fetchOne', '1']

queryClient.invalidateQueries({ queryKey: typeKey('albums') }) // every albums read
```

也导出 : `relationKey`, (中文(简体) ), `normalizeParams`。 。 。 .

单通键类型键不包含 id (`['inboxes', 'fetchOne']`) (中文(简体) ). 它的工厂 `undefined` iD,类型只允许单通,绑定的 API 将 参数 : `reads.inboxes.get()`, (中文(简体) ), `writes.inboxes.update()`,其变量包含资源 `id` 请求机构.

## 正常化`type:id` 写入补丁)

TanStack 保持非正常化的结果; 此软件包索引了每个资源(`data` + 键 `included`作者: `type:id` 和,在一个变化, **补丁每个缓存查询 `type:id` 到位** - "编辑 一次,随时更新。" 补丁替换节点 _属性_ (描述器知道属性) vs关系),同时保留边缘-局部关系 `$pivot` 编号 : `$edge`。每个被触摸的查询然后获得一个新的 根引用于同值上,因此组件观察它重递. 读取工厂的设定 `structuralSharing: false`,因为结构共享会重建一个被重置为平面阵列的值 和对象 `$page`, (中文(简体) ), `$next()` 或者说 `$self`; 设置在您创建的任意查询上 .

`installNormalization` 自动运行每个成功查询/调试的补丁 :

```ts
import { installNormalization } from '@haddowg/json-api-query'
import { resourceMap } from './api/music.gen'
import { QueryClient } from '@tanstack/query-core'

const queryClient = new QueryClient()
const teardown = installNormalization(queryClient, resourceMap)
// … later: teardown() removes the subscriptions.
```

> **每个查询站一个描述符 .** 补丁匹配由 `type:id` 独自一人,所以两个描述 共享查询客户端会交叉污染属性 。 正在安装 a _不同_ 显示 相同的查询 client 抛出。 给每个输入的客户端/服务器自己的查询站.

更倾向于明确的控制? 跳过安装和调用 `normalize(queryClient, result, resourceMap)` 从选择工厂 `onSuccess` - 相同的书写补丁.

## 写作——可变选择工厂

每个返回 a `MutationOptions` (单位:千美元)`mutationFn` + 生命周期召回绑定线条 正常化/失效/乐观),结构上与查询-核心兼容. 这个 **补丁- vs- 无效拆分**数字 :

-   a 一个 **更新** (或关系) `set` 编号 : `replace`)只更改一个节点的属性/链接 ~ 它通过成功补丁 `normalize` (无回放);
-   (单位:千美元) **创建** 编号 : **删除** 更改收集成员 —— 在结算时取消相关 列表 / 关系子树, 因此它们会重新绘制 .

```ts
import { createMutationApi } from '@haddowg/json-api-query'

const writes = createMutationApi(queryClient, client as unknown as WriteClient, resourceMap)

// Create — invalidates the type's lists on settle; normalizes the new resource on success.
const createOpts = writes.albums.create()

// Update — patches across the cache on success. `{ optimistic: true }` pre-applies the patch's
// attributes through the normalized patch and rolls back on error.
const updateOpts = writes.albums.id('1').update({ optimistic: true })

// Delete — invalidates the type's lists + the resource's own reads.
const deleteOpts = writes.albums.id('1').delete()

// Relationship mutations — invalidate the parent's relation reads (never the type's lists).
const addOpts = writes.albums.id('1').rel('tracks').add()
const setOpts = writes.albums.id('1').rel('artist').set()
```

变异的变量会镜像客户端: `create()` 使用平面创建输入, `update()` 补丁, `add/remove/replace()` 联系参考:, `set()` 参考或 `null`。 。 。 .

独立的工厂是 `createMutationOptions`, (中文(简体) ), `updateMutationOptions`, (中文(简体) ), `deleteMutationOptions`, (中文(简体) ), `addRelationshipMutationOptions`, (中文(简体) ), `removeRelationshipMutationOptions`, (中文(简体) ), `replaceRelationshipMutationOptions`, (中文(简体) ), `setRelationshipMutationOptions`和细 `atomicMutationOptions` 传球.

### 工作实例(直接用克瑞-核心)

```ts
const reads = createQueryApi(client as unknown as ReadClient)
const writes = createMutationApi(queryClient, client as unknown as WriteClient, resourceMap)

const listOpts = reads.albums.list()
const getOpts = reads.albums.get('1')
await queryClient.fetchQuery(listOpts)
await queryClient.fetchQuery(getOpts)

const updateOpts = writes.albums.id('1').update()
await queryClient
  .getMutationCache()
  .build(queryClient, updateOpts as never)
  .execute({ title: 'Fresh title' })

// Both the cached list AND the cached get now reflect the fresh title — patched by `type:id`,
// not refetched.
queryClient.getQueryData(listOpts.queryKey)
queryClient.getQueryData(getOpts.queryKey)
```

## 许可证

麻省理工学院

## 常见问题

### @haddowg/json-api-query 是什么？

TanStack 查询 JSON:API客户端的绑定:选项/关键工厂\+类型:id缓存正常化\.

### 如何安装 @haddowg/json-api-query？

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

### @haddowg/json-api-query 支持 TypeScript 吗？

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

### @haddowg/json-api-query 支持 ESM 还是 CommonJS？

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

### @haddowg/json-api-query 需要什么版本的 Node\.js？

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

### @haddowg/json-api-query 可以商用吗？

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

### @haddowg/json-api-query 的下载量有多少？

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

### @haddowg/json-api-query 还在维护吗？

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

