# @gitlab/query-language-rust 中文文档

规范地址：https://npmcn.com/package/%40gitlab/query-language-rust/

版本：0\.42\.0
npm 元数据更新时间：2026-11-04T18:05:04.893Z
中文译文更新时间：2026-11-16T10:56:19.990Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gitlab/query-language-rust
原文对照：https://npmcn.com/package/%40gitlab/query-language-rust/?lang=original
项目主页：https://gitlab.com/gitlab-org/glql#readme
源码仓库：https://gitlab.com/gitlab-org/glql

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

- 包体积（解压后）：3.1 MB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：1 个
- 首次发布：2024-11-25T17:33:13.185Z
- 最新版本发布：2026-10-20T14:39:40.828Z
- 近 30 天下载量：167469（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：89（近 12 个月 26 个）

## 中文简介

GLQL 转接器, 将 WASM 构建包成 Rust

## 安装

```sh
npm install @gitlab/query-language-rust
```

也可以使用：`pnpm add @gitlab/query-language-rust`、`yarn add @gitlab/query-language-rust`、`bun add @gitlab/query-language-rust`

## README

# GitLab 查询语言

![Latest Release](https://img.shields.io/npm/v/@gitlab/query-language-rust) ![Rust Coverage](https://gitlab.com/gitlab-org/glql/badges/main/coverage.svg?job=coverage) ![Pipeline Status](https://gitlab.com/gitlab-org/glql/badges/main/pipeline.svg)

编译器以 Rust \[^1\] 构建,并作为两个软件包分发:

-   **无** (单位:千美元)`@gitlab/query-language-rust`:由GitLab的前端用于客户端-侧查询编译.
-   **鲁比宝石** (单位:千美元)`gitlab_query_language`:由GitLab的后端用于服务器侧式查询处理.

该图书馆的目标包括:

-   将 GLQL 查询, 包括 YAML 前题块传送到 GraphQL 响应 .
-   使用变压器函数转换 GraphQL 调用的结果 .

## 无

`@gitlab/query-language-rust` 是 npm 模块,为转换提供简单的接口 `glql` 以其他格式查询.

它覆盖了Web Assembly的构建 `glql` 编译器,用Rust书写.

### 使用量

安装模块 :

```sh
npm install --save @gitlab/query-language-rust
```

导入和使用模块 :

```html
<script type="module">
  import { glql } from '@gitlab/query-language-rust';

  let query = 'label != "backend" and author = currentUser() and weight = 1 and updated > today()';

  let graphql = await glql.compile(query, {
    group: 'gitlab-org',
    username: 'johnhope',
  });

  console.log(graphql);
</script>
```

计划不在此导出 。 它由鲁比宝石代替`Glql.schema`下页 [鲁比宝石](https://npmcn.com/package/%40gitlab/query-language-rust/#readme-ruby-gem) 这是今天唯一的消费者.

### 运行浏览器播放地

克隆回波,然后安装dev依赖,建立WASM目标,并服务于 `npm/` 目录 :

```sh
npm install
cargo install wasm-pack
rustup target add wasm32-unknown-unknown
wasm-pack build --target web
npx wds -r npm/
```

## 鲁比宝石

同样的Rust编译器也作为Ruby gem提供,提供本地Ruby装订供服务器侧面使用.

### 安装

添加到您的 Gem 文件 :

```ruby
gem 'gitlab_query_language'
```

或直接安装 :

```bash
gem install gitlab_query_language
```

### 使用量

```ruby
require 'gitlab_query_language'

query = 'label != "backend" and author = currentUser() and weight = 1'
result = Glql.compile(query, { group: 'gitlab-org', username: 'johnhope', fields: 'title' })
puts result
```

`Glql.schema` 返回 GLQL 所接受的一切 - 数据源、 其字段、 运算符 字段,以及可用的函数:

```ruby
Glql.schema["sources"].map { |source| source["name"] }
# => ["WorkItems", "MergeRequests", "Pipelines", "Projects", "Jobs", ...]
```

`schema["version"]` 是宝石的版本.

### 交互式控制台( CLI / RePL)

Ruby gem为测试来自命令行的GLQL查询提供了快速的方法,而不需要浏览器:

```bash
cd glql_rb
bundle exec rake compile
bundle exec rake console
```

```ruby
irb(main):001> Glql.compile('type = Issue', {group: 'gitlab-org', username: 'johnhope', fields: 'id'})
=>
{"fields" => [{"key" => "id", "label" => "ID", "name" => "id"}],
 "output" => "query GLQL(...) { ... }",
 "success" => true,
 "variables" => { ... }}
```

关于鲁比宝石的全部细节,见 [glql rb/README.md (英语)](https://npmcn.com/package/%40gitlab/query-language-rust/glql_rb/README.md)。 。 。 .

## 发展

安装 [爱](https://mise.jdx.dev/) (或 [资产f](https://asdf-vm.com/)),然后运行:

```bash
mise install        # installs Rust, Node.js, and Ruby at the versions pinned in .tool-versions
brew install lefthook  # for managing git hooks (see below)
```

如果使用VSCode,则考虑安装 [`rust-analyzer`](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) 扩展名.

### 设置左旋

Lefthook用于在将代码推入寄存器前将某些检查自动化,例如运行测试,确保代码格式化,以及检查lint警告等.

在 MacOS 上在全球安装 Lefthook, 运行 :

```bash
brew install lefthook
```

关于安装的其他平台或方法,见 [安装文件](https://github.com/evilmartians/lefthook/blob/master/docs/install.md) 为了左撇子.

一次 `lefthook` ,通过运行您寄存器根中的以下命令在您的工程中启用 :

```bash
lefthook install
```

此命令将设置为 Lfthook 来管理 git 钩子, 用于在 `lefthook.yml` 文档.

### 预推钩

下列检查会在您按下代码前自动运行 :

-   **测试**:确保所有测试通过 `cargo test`。 。 。 .
-   **饼干**: 运行 `cargo clippy` 检查提示,并确保没有警告.
-   **格式**: 确保正确使用代码格式 `cargo fmt --check`。 。 。 .
-   **检查**: 运行 `cargo check` 以验证代码的编译没有出错.

## 运行测试

### 粗口测试

要手动运行 Rust 测试, 请使用以下命令 :

```bash
cargo test
```

这将构建和运行您 Rust 项目中定义的所有测试 .

### WASM 软件包测试

要进行WASM包测试,请使用:

```bash
npm test
```

连续集成测试:

```bash
npm run test:ci
```

### 代码覆盖

覆盖报告在CI/CD中自动生成,并发布在GitLab Pages上:

-   粗线覆盖 : `https://gitlab-org.gitlab.io/glql/coverage/`

### 重生计划

`src/schema/schema.json` 由分析器生成,而不是用手书写。 之后再生出来 更改分析器宣布的任何东西 - 字段、操作符、范围、来源:

```bash
cargo run --bin generate-schema && npm run lint:prettier:fix
```

两者都定义了文件,所以CI运行的正是这两个命令,并在任意diff上失败. 运行他们 检查一下没有改变 看看CI会说什么.

### 格式代码

为了确保您的代码使用适当的格式化 `rustfmt`,运行 :

```bash
cargo fmt -- --check
```

此命令检查您的代码是否遵守格式化规则, 但不会修改任何文件 。 要自动格式化您的代码, 运行 :

```bash
cargo fmt
```

### 以 Clippy 键入

要插入你的代码 并抓住常见的错误 或效率低下,运行:

```bash
cargo clippy -- -D warnings
```

这将把所有警告视为错误,如果发现任何警告,则防止代码构建.

### 端到端测试

在对 GLQL Rust 代码库进行修改时, 您可以遵循这些步骤测试您的修改端到端 [GitLab GDK 软件](https://gitlab.com/gitlab-org/gitlab-development-kit)。前端(npm/WASM)和后端(Ruby gem)都需要重建,并指向您的本地取出.

**在 glql repo 中:**

1.  检查您要测试的分支 :
    
    ```bash
    git checkout my-feature-branch
    ```
    
2.  构建 WASM 软件包 :
    
    ```bash
    wasm-pack build --target web --out-dir pkg
    ```
    
3.  构建 npm 包 :
    
    ```bash
    npm install && npm run build
    ```
    
4.  构建 Ruby 宝石 :
    
    ```bash
    cd glql_rb && bundle install && bundle exec rake compile
    cd ..
    ```
    
5.  打印下一步所需的路径 :
    
    ```bash
    echo "WASM path: $(pwd)/npm/dist/main.js"
    echo "Ruby gem path: $(pwd)/glql_rb"
    ```
    

**在 GitLab GDK 目录中:**

1.  更新导入到 `app/assets/javascripts/glql/core/parser.js` 财务报告和审定财务报表 `app/assets/javascripts/glql/core/transformer.js`数字 :
    
    ```js
    // change from
    import { glql } from '@gitlab/query-language-rust';
    
    // to
    import { glql } from 'file:///[WASM_PATH]';
    ```
    
2.  更新 `gitlab_query_language` 根中线条 `Gemfile` 指向您的本地宝石:
    
    ```ruby
    gem 'gitlab_query_language', path: '[GEM_PATH]'
    ```
    
3.  因此铁路后端和Vite前端都接上本地建筑:
    
    ```bash
    bundle install
    gdk stop rails-web vite && rm -rf tmp/cache/vite && gdk start rails-web vite
    ```
    

现在您可以通过嵌入 GLQL 查询来测试您在任何平分字段的更改, 例如:

````markdown
```glql
display: table
fields: title, labels, author
query: group = "gitlab-org" and label = "group::knowledge" and user = currentUser()
```
````

**说明:** 每次你改变GLQL Rust代码,你必须重建WASM,npm,和Ruby geem的文物,以使修改生效.

## 捐款

1.  如果你还没有权限,请从 [请求访问社区叉](https://gitlab.com/gitlab-community/meta#request-access-to-community-forks)。 。 。 .
2.  切开 [社区分叉存储器](https://gitlab.com/gitlab-community/gitlab-org/glql)。 。 。 .
3.  创建新功能分支( N)`git checkout -b feature/my-feature`) (中文(简体) ).
4.  提交更改( E)`git commit -am 'Add new feature'`) (中文(简体) ).
5.  推向分行(`git push origin feature/my-feature`) (中文(简体) ).
6.  打开一个MR.

### 工具链版本同步

运行时版本被固定在必须同步的三个位置:

| 文件 | 它控制着什么 |
| --- | --- |
| `.tool-versions` | 当地自然环境(海洋/灰尘) |
| `.gitlab-ci.yml` | CI 管道图像和变量(`RUST_VERSION`,图像标记) |
| `.gitlab/duo/agent-config.yml` | Duo 开发者代理环境 |

当撞出一个rust,Node.js,或Ruby版本时,更新所有三个文件.

## 释放过程

> \[重要\] 先决条件 您需要项目中的开发者权限 .

打开 `main` 分支,运行以下任何管道工作以创建 释放 :

-   `release-patch`: 弹出补丁版本并发布给国家预防机制.
-   `release-minor`: 弹出小版本并发布给国家预防机制.
-   `release-major`: 弹出主要版本并发布给国家预防机制.

发布-\*的工作将另外创建一个发布MR,同样会撞倒Ruby gem版本和依赖性. 这目前需要人工批准才能被启动宝石发行.

见宝石 [glql rb/README.md (英语)](https://npmcn.com/package/%40gitlab/query-language-rust/glql_rb/README.md) 详细了解释放过程.

## 其他阅读

### 学习玫瑰

-   [拉斯特书](https://doc.rust-lang.org/book/)
-   [以实例显示](https://doc.rust-lang.org/rust-by-example/)

## 更多地了解 GLQL

-   [建筑设计文档](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/glql/)
-   [面对文件的用户](https://docs.gitlab.com/user/glql/)

\[^1\]: 原文为: [哈斯凯尔](https://gitlab.com/gitlab-org/gitlab-query-language/glql-haskell)。 。 。 .

## 常见问题

### @gitlab/query-language-rust 是什么？

GLQL 转接器, 将 WASM 构建包成 Rust

### 如何安装 @gitlab/query-language-rust？

在项目目录运行 npm install @gitlab/query-language-rust，或使用 pnpm add / yarn add / bun add。

### @gitlab/query-language-rust 支持 TypeScript 吗？

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

### @gitlab/query-language-rust 支持 ESM 还是 CommonJS？

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

### @gitlab/query-language-rust 可以商用吗？

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

### @gitlab/query-language-rust 的下载量有多少？

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

### @gitlab/query-language-rust 还在维护吗？

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

