# @bufbuild/protoc-gen-connect-query 中文文档

规范地址：https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/

版本：0\.4\.1
npm 元数据更新时间：2026-09-16T06:38:35.484Z
中文译文更新时间：2026-11-08T18:29:21.077Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40bufbuild/protoc-gen-connect-query
原文对照：https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/?lang=original
项目主页：https://github.com/bufbuild/connect-query#readme
源码仓库：https://github.com/bufbuild/connect-query

弃用说明：Connect has moved to its own org @connectrpc and has a stable v1\. Run \`npx @connectrpc/connect-migrate@latest\` to update\. See https://github\.com/connectrpc/connect-es/releases/tag/v0\.13\.1 for details\.

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

- 包体积（解压后）：36.1 kB，21 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=16
- 运行依赖：2 个
- peer 依赖：@bufbuild/protoc-gen-es 1\.x
- 首次发布：2022-12-13T18:00:00.522Z
- 最新版本发布：2023-08-11T21:32:56.089Z
- 近 30 天下载量：9024（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 0 个）

## 中文简介

连接- query 的代码生成器

## 安装

```sh
npm install @bufbuild/protoc-gen-connect-query
```

也可以使用：`pnpm add @bufbuild/protoc-gen-connect-query`、`yarn add @bufbuild/protoc-gen-connect-query`、`bun add @bufbuild/protoc-gen-connect-query`

## README

# @bufbuilding/protoc-gen-connect-query (英语)

-   [@bufbuilding/protoc-gen-connect-query (英语)](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-bufbuildprotoc-gen-connect-query)
    -   [安装](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-installation)
    -   [生成代码](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-generating-code)
        -   [`example.proto`](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-exampleproto)
        -   [`buf.gen.yaml`](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-bufgenyaml)
        -   [与 `buf` 国 际](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-with-the-buf-cli)
        -   [与 `protoc`](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-with-protoc)
        -   [带节点](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-with-node)
    -   [生成输出](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-generated-output)
    -   [插件选项](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-plugin-options)
        -   [`target`](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-target)
        -   [`import_extension=.js`](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-import_extensionjs)
        -   [`keep_empty_files=true`](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-keep_empty_filestrue)
    -   [生成代码示例](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-example-generated-code)

连接查询的代码生成器, 扩展包 [TanStack 查询](https://tanstack.com/query) (反应-清空),可以与会说话的服务器进行无心通信 [连接协议](https://connectrpc.com/docs/protocol)。 。 。 .

了解更多关于连接查询的信息 [github.com/bufbuilding/接通-query (英语)](https://github.com/bufbuild/connect-query)。 。 。 .

## 安装

`protoc-gen-connect-query` 用于协议缓冲编译器的代码生成器插件, 如 [库夫](https://github.com/bufbuild/buf) 财务报告和审定财务报表 [原型](https://github.com/protocolbuffers/protobuf/releases)它从您的协议缓冲计生成客户端,并与 [@ bufbuilt/ protoc- gen- s](https://www.npmjs.com/package/@bufbuild/protoc-gen-es),用于所有协议缓冲基准类型的代码生成器插件。 这两个插件生成的代码需要运行时库 [@ bufbuilding/ 连接- query](https://www.npmjs.com/package/@bufbuild/connect-query),以及 [@ bufbuilding/ protobuf](https://www.npmjs.com/package/@bufbuild/protobuf)。 。 。 .

要安装插件及其运行时库, 运行 :

```shell
npm install --save-dev @bufbuild/protoc-gen-connect-query @bufbuild/protoc-gen-es
npm install @bufbuild/connect-query @bufbuild/protobuf
```

我们使用对等依赖来保证代码生成器和运行时库相互兼容. 请注意,纱线和pnpm只发出警告 在本案中.

## 生成代码

### `example.proto`

对于这些例子,请考虑以下实例: `example.proto`数字 :

```protobuf
syntax = "proto3";

package example.v1;

message Nothing {}

message Todo {
  string id = 1;
  string name = 2;
  bool completed = 3;
}

message Todos {
  repeated Todo todos = 1;
}

service TodoService {
  rpc GetTodos(Nothing) returns (Todos);
  rpc AddTodo(Todo) returns (Nothing);
}
```

此文件创建了 RPC 服务, 内容如下 :

-   `GetTodos` 不取输入并返回一组 `Todo`编号.
-   `AddTodo` 添加一个新的 `Todo` 却一无所获.

### `buf.gen.yaml`

添加新配置文件 `buf.gen.yaml`

```yaml
version: v1
plugins:
    # This will invoke protoc-gen-es and write output to src/gen
  - name: es
    out: src/gen
    opt: target=ts
    # This will invoke protoc-gen-connect-query
  - name: connect-query
    out: src/gen
    opt: target=ts
```

### 与 `buf` 国 际

用来使用 [buf CLI (中文(简体) )](https://docs.buf.build/generate/usage#run-generate) 生成项目中所有 protobuf 文件的代码,只需运行:

```bash
npx @bufbuild/buf generate
```

> 请注意: `buf` 可以从各种 [投入](https://docs.buf.build/reference/inputs)不仅仅是本地原始文件 譬如说, `npm run generate buf.build/connectrpc/eliza` 生成模块的代码 [连接/ eliza](https://buf.build/connectrpc/eliza) 在Buf Schema登记.

### 与 `protoc`

```bash
PATH=$PATH:$(pwd)/node_modules/.bin \
  protoc -I . \
  --es_out src/gen \
  --es_opt target=ts \
  --connect-query_out src/gen \
  --connect-query_opt target=ts \
  example.proto
```

请注意,我们正在增加 `node_modules/.bin` 页:1 `$PATH`,这样协议缓冲编译器就可以找到它们。 Npm 脚本会自动发生这种情况.

> 注:由于线条v2及以上不使用a `node_modules` 目录中,您需要稍微修改变量 :
> 
> ```bash
> PATH=$(dirname $(yarn bin protoc-gen-es)):$(dirname $(yarn bin protoc-gen-connect-es)):$PATH
> ```

### 带节点

添加行到 `scripts` 区域 `package.json` 要运行 `buf generate`。 。 。 .

```json
"scripts": {
    ...
    "buf:generate": "npx @bufbuild/buf generate example.proto"
},
```

最后,告诉Buf通过运行命令生成代码:

```bash
npm run buf:generate
```

现在你应该看看你生成的代码:

```tree
.
└── gen/
    ├── example_pb.ts
    └── example-TodoService_connectquery.ts
```

## 生成输出

Connect-Query将为每个protofile中的每个服务创建一个输出文件. 说您有以下文件结构 :

```tree
.
└── proto/
    ├── pizza.proto
    └── curry.proto
```

何处 `pizza.proto` 包含 `DetroitStyleService` 财务报告和审定财务报表 `ChicagoStyleService`,并在哪里 `curry.proto` 包含 `VindalooService`。您生成的输出会像这样 :

```tree
.
└── gen/
    ├── pizza_pb.ts
    ├── pizza-DetroitStyleService_connectquery.ts
    ├── pizza-ChicagoStyleService_connectquery.ts
    ├── curry_pb.ts
    └── curry-VindalooService_connectquery.ts
```

每个服务得到一个单独文件的原因 是为了方便了解和了解 [语言服务器协议导入](https://github.com/typescript-language-server/typescript-language-server#organize-imports)。通知每个输入原型生成一个文件 `protoc-gen-es` (单位:千美元)`pizza_pb.ts` 财务报告和审定财务报表 `curry_pb.ts`),每个服务创建一个文件 `protoc-gen-connect-query` (组成其余部分)。 Protobuf-ES生成文件(`*_pb.ts`)很重要,因为这些文件来自 `*_connectquery.ts` 文档.

## 插件选项

### `target`

此选项控制插件是否生成 JavaScript, TypeScript, 或 TypeScript 声明文件 .

比如说,你用过 [`example.proto`](https://npmcn.com/package/%40bufbuild/protoc-gen-connect-query/#readme-exampleproto)数字 :

| 目标 | 生成输出 |
| --- | --- |
| `target=js` | `example-TodoService_connectquery.js` |
| `target=ts` | `example-TodoService_connectquery.ts` |
| `target=dts` | `example-TodoService_connectquery.d.ts` |

可以通过将它们与 `+`,例如 `target=js+dts`。 。 。 .

默认情况下,我们生成了JavaScript和TypeScript声明文件,它们产生最小的代码大小并是最能与各种捆绑器配置兼容的. 如果您喜欢生成类型脚本, 请使用 `target=ts`。 。 。 .

### `import_extension=.js`

默认, [原型- 基因- 连接- query](https://www.npmjs.com/package/@bufbuild/protoc-gen-connect-query) (和基于 [@ bufbuilding/ protoplugin (英语)](https://www.npmjs.com/package/@bufbuild/protoplugin)使用 a `.js` 导入路径中的文件扩展名,甚至在TypeScript文件中.

这是不直观的,但必需的 [节点.js中的ECMAScript模块](https://www.typescriptlang.org/docs/handbook/esm-node.html)。 。 。 .

不幸的是,并非所有的捆绑者和工具都赶上了,而德诺要求 `.ts`。使用此插件选项,可以替换 `.js` 在带有给定值的导入路径中扩展 。 例如,设定

-   `import_extension=none` 删除 `.js` 扩展
-   `import_extension=.ts` 替换 `.js` 扩展名 `.ts`

### `keep_empty_files=true`

此选项适用于其他插件, 但不适用于 `protoc-gen-connect-query` 因为与其他大多数插件不同,它不会为每个输入原生文件产生最多一个输出文件. 相反,它每个服务生成一个输出文件. 如果您提供了无效的原型文件, 其中没有服务, `protoc-gen-connect-query` 将没有输出.

## 生成代码示例

见 [`example.proto`](https://github.com/bufbuild/connect-query/blob/main/packages/generated-react/example.proto) 财务报告和审定财务报表 [`eliza.proto`](https://github.com/bufbuild/connect-query/blob/main/packages/generated-react/eliza.proto) 例如输入和查看 [这里](https://github.com/bufbuild/connect-query/blob/main/packages/generated-react/dist) 以查看这些文件生成的输出.

## 常见问题

### @bufbuild/protoc-gen-connect-query 是什么？

连接- query 的代码生成器注意：该包已被作者标记为弃用——Connect has moved to its own org @connectrpc and has a stable v1\. Run \`npx @connectrpc/connect-migrate@latest\` to update\. See https://github\.com/connectrpc/connect-es/releases/tag/v0\.13\.1 for details\.

### 如何安装 @bufbuild/protoc-gen-connect-query？

在项目目录运行 npm install @bufbuild/protoc-gen-connect-query，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 protoc-gen-connect-query，可以用 npx protoc-gen-connect-query 直接运行。

### @bufbuild/protoc-gen-connect-query 支持 TypeScript 吗？

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

### @bufbuild/protoc-gen-connect-query 需要什么版本的 Node\.js？

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

### @bufbuild/protoc-gen-connect-query 可以商用吗？

@bufbuild/protoc-gen-connect-query 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @bufbuild/protoc-gen-connect-query 的下载量有多少？

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

### @bufbuild/protoc-gen-connect-query 还在维护吗？

最新版本 0\.4\.1 发布于 2023/08/12（3 年前）；至今共发布 21 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/12/14。作者已将其标记为弃用，新项目建议寻找替代方案。