@gitbeaker/rest

中文文档
44.1.3发布于 2026/11/16MITTypeScriptES Module近 30 天下载 823.4万

跨平台执行 GitLab API

中文使用文档
文档目录10 节
  1. 目录
  2. 特征
  3. 使用量
  4. API 客户端
  5. 扩大的有效载荷
  6. 倾斜
  7. 费率限制
  8. 处理错误
  9. 实例
  10. 贡献者


gitbeaker



CircleCI REST Coverage Auto All Contributors Prettier Licence: MIT Install Size: Rest

类型 吉特拉布语Name 浏览器的SDK, Node.js, and Deno.

目录

特征

  • 完成 - GitLab所有被曝光的API的特性都覆盖到版本上 16.5 (中文(简体) )。见 这里 完整名单.
  • 通用 - 在所有现代浏览器中工作, 节点.js,以及 德诺。 。 。 .
  • 已测试 所有图书馆的测试覆盖率都大于80%.
  • 类型 - 所有库都有广泛的TypeScript声明.

使用量

浏览器 装入 @gitbeaker/rest 直接从 esm.sh (英语)
<script type="module">
  import { Gitlab } from 'https://esm.sh/@gitbeaker/rest';
</script>
德诺 装入 @gitbeaker/rest 直接从 esm.sh (英语)
import { Gitlab } from 'https://esm.sh/@gitbeaker/rest?dts';
节点18+

安装方式 npm install @gitbeaker/rest, (中文(简体) ), yarn add @gitbeaker/rest,或 pnpm add @gitbeaker/rest

import { Gitlab } from '@gitbeaker/rest';

API 客户端

使用您创建的基本符号来证明图书馆 GitLab 简介

const api = new Gitlab({
  token: 'personaltoken',
});

可用的即时选择 :

名称可选默认说明
host对https://gitlab.comGitlab 实例主机 URL
token对*不详个人托肯. 建议(建议3个标志之一)
oauthToken对*不详(原始内容存档于2018-03-27). OAuth Token. 建议(建议3个标志之一)
jobToken对*不详CI乔布·托肯. 建议(建议3个标志之一)
rejectUnauthorized对trueHttp 证书设置, 仅适用于非浏览器发布和 HTTPS 主机 urls
sudo对false须藤 查询参数
camelize对false凸起所有响应体键
requesterFn没有@gitbeaker/ rest & @gitbeaker/cli:基于抓取的,该 @gitbeaker/核心包 没有 存在默认,因此必须明确设定请求图书馆收发器
queryTimeout对300000查询超时( ms)
profileToken对不详请求配置文件
profileMode对execution请求配置文件
rateLimits没有国防 战争 战斗全球和终点特定可调整费率限额
rateLimitDuration没有60达到费率限制时的暂停时间

* 应提供其中之一,因为大多数API请求需要认证.

扩大的有效载荷

为了简单起见,只有反应体从API方法返回. 然而,看到额外的响应领域,如状态,标题等,可能是有益的. 为此,增加一个可选参数, showExpanded 可以通过大多数 API 方法.

对于返回未粘贴结果的方法,有效载荷具有这种结构:

type ResponseBodyTypes =
  | Record<string, unknown>
  | Record<string, unknown>[]
  | ReadableStream
  | Blob
  | string
  | string[]
  | number
  | void
  | null;

interface FormattedResponse<T extends ResponseBodyTypes = ResponseBodyTypes> {
  body: T;
  headers: Record<string, string>;
  status: number;
}

对于返回被粉碎后结果的方法,有效载荷还包括载于 铺设文件

倾斜

可用的页码选项 :

名称密钥集折减类型默认说明
pagination页:1页:1"抵消"或"键盘""抵消"定义应当使用的页形类型
perPage页:1页:1数目20国每个请求的结果数额
orderBy页:1字符串哪些领域的结果应该由
sort页:1“ asc” 或“ desc”亚士克结果的排序方向
maxPages页:1数目不详最多应提出请求的数量
page页:1数目不详要检索的特定页面
showExpanded页:1布尔虚假除数据外随页标信息返回

偏移倾斜

对于资源上的任何.all () 函数,它将返回 全部 gitLab提供的物品。 如果有许多项目,这可能会很麻烦,因为请求本身需要一段时间才能完成。 因此,可以通过最大Pages选项来限制所有函数的范围.

import { Gitlab } from '@gitbeaker/rest';

const api = new Gitlab({
  host: 'http://example.com',
  token: 'personaltoken',
});

let projects = await api.Projects.all({ maxPages: 2 });

您也可以结合 perPage 参数使用此参数, 该参数将取代 Gitlab 设定的每页 30 的默认值 :

import { Gitlab } from '@gitbeaker/rest';

const api = new Gitlab({
  host: 'http://example.com',
  token: 'personaltoken',
});

let projects = await api.Projects.all({ maxPages: 2, perPage: 40 });

此外,如果您想要获取页码信息, 需要了解总页有多少页, 例如, 通过选项 showExpanded。如果有多种结果,则将包含标记属性如下:

...
const { data, paginationInfo } = await api.Projects.all({
  perPage:40,
  maxPages:2,
  showExpanded: true
});
...

这将导致以这种形式作出反应:

data: [
...
],
paginationInfo: {
  next: 4,
  current: 2,
  previous: 1,
  perPage: 3,
}

注:提供任何帕吉化限制都称为密集。 一些资源需要许多要求,这些要求可以给GitLab服务器带来大量负荷。 一般最佳做法是,在不需要所有结果的情况下,规定只返回第一页的页面请求选项.

键集缓存

同样,支持 密钥集映射 可以通过 pagination 参数作为查询选项来切换

const { data } = await api.Projects.all({
  pagination: 'keyset',
  sort: 'asc',
  orderBy: 'created_at',
});

费率限制

速率限制是完全自定义的,用于限制库内连续API请求之间的请求速率. 默认情况下,所有未指定的端点都使用3000 rps的速率限制,而一些端点的速率则要小得多,因为 GitLab 文档。关于默认值,见下文:

const DEFAULT_RATE_LIMITS = Object.freeze({
  // Default rate limit
  '**': 3000,

  // Import/Export
  'projects/import': 6,
  'projects/*/export': 6,
  'projects/*/download': 1,
  'groups/import': 6,
  'groups/*/export': 6,
  'groups/*/download': 1,

  // Note creation
  'projects/*/issues/*/notes': {
    method: 'post',
    limit: 300,
  },
  'projects/*/snippets/*/notes': {
    method: 'post',
    limit: 300,
  },
  'projects/*/merge_requests/*/notes': {
    method: 'post',
    limit: 300,
  },
  'groups/*/epics/*/notes': {
    method: 'post',
    limit: 300,
  },

  // Repositories - get file archive
  'projects/*/repository/archive*': 5,

  // Project Jobs
  'projects/*/jobs': 600,

  // Member deletion
  'projects/*/members': 60,
  'groups/*/members': 60,
});

速率限制可以在即时API包装时被推翻. 为了便于使用,这些限制是使用 glob 模式来配置的,可以有两种格式.

  1. 带有相应每秒速率的终点缩放
  2. 结束点的缩写, 指定结束点的具体方法和相应的速率限制的对象

您也可以覆盖 rateLimitDuration 默认值为 60 秒。 这是特定终点在达到速率限制时的超时时间.

const api = new Gitlab({
  token: 'token',
  rateLimits: {
    '**': 30,
    'projects/import/*': 40,
    'projects/*/issues/*/notes': {
      method: 'post',
      limit: 300,
    },
  },
  rateLimitDuration: 30,
});

处理错误

请求出错会在纯错误实例中返回, 使用原因来持有原始响应, 以及从 JSON 的响应出错或信件字段中提取的对出错的文本描述, 或其纯文本值 :

class GitbeakerError extends Error {
  constructor(
    message: string,
    options?: {
      cause: {
        description: string;
        request: Request;
        response: Response;
      };
    },
  ) {
    super(message, options);
    this.name = 'GitbeakerError';
  }
}

注意,信息被分配到反应 statusText,则 请求 财务报告和审定财务报表 回应 类型来自节点JS API.

实例

一旦您的库被即时化, 您可以使用许多 API 的功能 :

使用等待/同步方法

import { Gitlab } from '@gitbeaker/rest';

const api = new Gitlab({
  host: 'http://example.com',
  token: 'personaltoken',
});

// Listing users
let users = await api.Users.all();

// Or using Promise-Then notation
api.Projects.all().then((projects) => {
  console.log(projects);
});

关于所有函数参数的通则 :

  • 如果它是一个必需的参数, 它就是函数中的一个命名的参数
  • 如果它是一个可选参数,则按照命名参数在选项对象中定义

没错.

import { Projects } from '@gitbeaker/rest';

const projectsAPI = new Projects({
  host: 'http://example.com',
  token: 'personaltoken',
});

projectsAPI.create({
  //options defined in the GitLab API documentation
});

贡献者

Justin Dalrymple Dylan DesRosier Mike Wyatt Cory Zibeill Martin Bour akira345 Pavel Birukov Joseph Petersen Louis Cherel Adam Dehnel Ev Haus Loïc Mahieu Giuseppe Angri jennparise Oscar Daniel Ruf schindld Alvaro Daniel Moore Dylan M. Taylor Corentin Mors xatavian Yevgeny Petukhov Mickaël Tricot Andrea Flavien Bridault s-kazuki Kipras Melnikovas xieyu st1gok Max Wittig Niklas Lochschmidt Ilya Dus Omar Awamry Hennadii Varava xiezht Martin Helmich Sean McGivern Clemens Lieb Vojtěch Sajdl divido Vincent Boulaye Aliyss Snow Mahmoud Saada Feng Yu Roy Jacobs Paul Lemke Ian Jenkins nilennoct Laffargue Michael Martin Howarth Christoph Lehmann Frank V Salim Benabbou Tamás Török-Vistai Martin Benninger fewieden Jeff Pelton Claude Abounegm Stefan Hall Jordan Wallet zhao0 Joshua Grosso Isaac Ouellet Therrien Rajat Sharma Cesar B. Igor Katsuba Michael Townsend bodtx Artem Munif Tanjim Quentin Dreyer Norm MacLennan jnovick Fabian Aussems Michael Matzka CraigAllardyce Bruno Guimarães Lukas Eipert Maximilian Krauß Evolution Engineering WEBER Logan Anton Zhukov Nicholas Loomans Carl Kittelberger Patrik Votoček Kyrylo Fedorov Claudio Vellage Seb0uil Rafael Mello Théis Bazin Spencer Salisbury Simone Corsi Bambii Will ArnaudTA Benjamin Beret Alessandro Diez artlist-scottambrose Martin Dreher Elan Ruusamäe artemoire Pieter Willekens David Claybourne Dom Harrington Kohei Seino JounQin Elaine Mattos DK Koen Brouwer Sefa Eyeoglu Carmi Raz Arnold Hendriks Baylee Schmeisser Andy roberta-pavel Youssef Miguel Giannis Kepas Talysson de Oliveira Cassiano Marco Endrik Einberg Bryan Lee Zack Kay W. Florian Imdahl lanthier ShaoWei Teo Daniel Rentz Matěj Smíšek

这是从一个叉子开始的 节点- gitlab- 遗留 但我最后重写了大部分代码 这是原作的 捐助者。 。 。 .

版本与发布记录

@gitbeaker/rest 共发布 158 个版本,首次发布于 2023/03/14;过去 12 个月发布了 29 个版本。

版本发布日期距今
44.1.3latest2026/11/16今天
44.1.22026/11/16今天
44.1.12026/11/16今天
44.1.02026/11/16今天
44.0.72026/11/16今天
44.0.62026/11/151 天前

其他发布通道:canary → 0.0.0-canary-20260813022219,pre → 44.0.0-pre.0。

关于 @gitbeaker/rest 的常见问题

@gitbeaker/rest 是什么?

跨平台执行 GitLab API

如何安装 @gitbeaker/rest?

在项目目录运行 npm install @gitbeaker/rest,或使用 pnpm add / yarn add / bun add。

@gitbeaker/rest 支持 TypeScript 吗?

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

@gitbeaker/rest 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gitbeaker/rest 需要什么版本的 Node.js?

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

@gitbeaker/rest 可以商用吗?

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

@gitbeaker/rest 的下载量有多少?

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

@gitbeaker/rest 还在维护吗?

最新版本 44.1.3 发布于 2026/11/16(今天);至今共发布 158 个版本,其中过去 12 个月发布了 29 个;首次发布于 2023/03/14。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。