大家好，很高兴又见面了，我是"高级前端?进阶?"，由我带着大家一起关注前端前沿、深入前端底层技术，大家一起进步，也欢迎大家关注、点赞、收藏、转发，您的支持是我不断创作的动力。

今天给大家带来的主题是 octokit.js，即适用于浏览器、Node.js 和 Deno 的全包 GitHub SDK。话不多说，直接进入正题！

1.什么是 octokit.js

octokit.js 是适用于浏览器、Node.js 和 Deno 的全能包 GitHub SDK。

octokit 包集成了三个主要的 Octokit 库

• API client：用于REST API 请求、GraphQL API 查询、身份验证
• App client：用于GitHub 应用程序和安装、Webhooks、OAuth
• Action client： 用于客户端单个存储库的预验证 API 客户端

octokit.js 的典型特征包括：

• 功能覆盖全：涵盖了 GitHub 平台 API 的所有功能
• 最佳实践： 所有推荐的最佳实践均已实现
• 场景覆盖全： 适用于所有现代浏览器、Node.js 和 Deno
• 充分测试：所有库都有 100% 的测试覆盖率。
• TypeScript 支持：所有库都有大量的 TypeScript 声明。
• 可分解：仅使用需要的代码，比如开发者只需几行代码即可构建自己的 Octokit 或使用底层静态方法，可以在功能和打包包大小之间进行权衡。
• 高可扩展：使用插件添加功能、hook 请求或 Webhook 生命周期或实现自己的身份验证策略。

目前 octokit.js 在 Github 上通过 MIT 协议开源，有超过 6.2k 的 star、1.1k 的 fork、代码贡献者 50+，NPM 周平均下载量 282k，是一个值得长期关注的前端开源项目。

3.Octokit API 客户端使用

3.1 安装 octokit.js

在浏览器环境中，可以直接从 esm.sh 加载 octokit:

<script type="module">
  import {(Octokit, App)} from "https://esm.sh/octokit";
</script>

在 Deno 中也一样：

import { Octokit, App } from "https://esm.sh/octokit?dts";

在 Node v12+版本中，可以使用 npm/pnpm install octokit 或 yarn add octokit 安装：

import { Octokit, App } from "octokit";

在 Node 10 以下版本中可以按照下面的方法引入:

const { Octokit, App } = require("octokit");

3.2 Octokit API 客户端

@octokit/core 是独立的最小 Octokit， Octokit 客户端可用于向 GitHub 的 REST API 发送请求，并向 GitHub 的 GraphQL API 发送查询。比如获取经过身份验证的用户名。

// 在 https://github.com/settings/tokens/new?scopes=repo 创建个人访问令牌
const octokit = new Octokit({ auth: `personal-access-token123` });
// Compare: https://docs.github.com/en/rest/reference/users#get-the-authenticated-user
const {
  data: { login },
} = await octokit.rest.users.getAuthenticated();
console.log("Hello, %s", login);

3.3 验证（Authentication）

默认情况下，Octokit API 客户端支持使用静态令牌进行身份验证。

GitHub 支持多种不同的身份验证方式，在 octokit/authentication-strategies.js 中有详细描述。 开发者可以将它们中的每一个设置为 authStrategy 构造函数选项，并将策略选项作为 auth 构造函数选项传递。

例如，为了验证 GitHub 应用程序安装：

import { createAppAuth } from "@octokit/auth-app";
const octokit = new Octokit({
  authStrategy: createAppAuth,
  auth: {
    appId: 1,
    privateKey: "-----BEGIN PRIVATE KEY-----\n...",
    installationId: 123,
  },
});
// authenticates as app based on request URLs
const {
  data: { slug },
} = await octokit.rest.apps.getAuthenticated();
// creates an installation access token as needed
// assumes that installationId 123 belongs to @octocat, otherwise the request will fail
await octokit.rest.issues.create({
  owner: "octocat",
  repo: "hello-world",
  title: "Hello world from " + slug,
});

在大多数情况下，还可以使用 App 或 OAuthApp SDK，它们提供 API 和内部接线来覆盖大多数用例。 例如，使用 App 来实现上述功能：

const app = new App({ appId, privateKey });
const { data: slug } = await app.octokit.rest.apps.getAuthenticated();
const octokit = await app.getInstallationOctokit(123);
await octokit.rest.issues.create({
  owner: "octocat",
  repo: "hello-world",
  title: "Hello world from " + slug,
});

3.4 代理服务器（仅限 Node.js）

默认情况下，Octokit API 客户端不使用标准代理服务器环境变量。 要添加对代理服务器的支持，开发者需要提供支持它们的 https 客户端，例如 proxy-agent。

例如，使用代理生成的客户端，该客户端将根据标准环境变量 http_proxy、https_proxy 和 no_proxy 配置代理：

import ProxyAgent from "proxy-agent";
const octokit = new Octokit({
  request: {
    agent: new ProxyAgent(),
  },
});

如果正在编写一个使用 Octokit 并设计供其他人使用的模块，应该确保使用者可以为 Octokit 提供代理或作为特定调用的参数，例如：

octokit.rest.repos.get({
  owner,
  repo,
  request: { agent },
});

3.5 REST API

有两种使用 GitHub REST API 的方法：octokit.rest._ 端点方法和 octokit.request。两者的行为方式相同，只是为了方便而添加 octokit.rest._ 方法，它们在内部使用 octokit.request 。 例如：

await octokit.rest.issues.create({
  owner: "octocat",
  repo: "hello-world",
  title: "Hello, world!",
  body: "I created this issue using Octokit!",
});

代码的功能与下面一致：

await octokit.request("POST /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "hello-world",
  title: "Hello, world!",
  body: "I created this issue using Octokit!",
});

在这两种情况下，给定的请求都会由 octokit 实例透明地进行身份验证、重试和限制，该实例还根据需要管理接受和用户代理标头。

octokit.request 可用于通过传递完整 URL 将请求发送到其他域，并将请求发送到 GitHub 的 REST API 文档中尚未记录的端点。

3.6 GraphQL API 查询

Octokit 还直接支持 GitHub 的 GraphQL API，开发者可以在调用 octokit.graphql 时使用文档中显示的相同查询以及 GraphQL 资源管理器中提供的查询。

示例获取经过身份验证的用户的登录信息：

const {
  viewer: { login },
} = await octokit.graphql(`{
  viewer {
    login
  }
}`);

变量可以作为第二个参数传递:

const { lastIssues } = await octokit.graphql(
  `
    query lastIssues($owner: String!, $repo: String!, $num: Int = 3) {
      repository(owner: $owner, name: $repo) {
        issues(last: $num) {
          edges {
            node {
              title
            }
          }
        }
      }
    }
  `,
  {
    owner: "octokit",
    repo: "graphql.js",
  }
);

4.GitHub 应用（App）

独立模块：@octokit/app

对于集成商来说，GitHub Apps 是一种身份验证和授权的手段。 GitHub 应用程序可以在 GitHub 用户或组织帐户上注册。 GitHub 应用程序注册定义了一组它想要接收的权限和 Webhook 事件，并提供一组凭据作为返回，用户可以通过安装来授予对存储库的访问权限。

某些 API 端点要求 GitHub 应用程序使用 JSON Web 令牌 (JWT) 进行自身身份验证。 对于影响安装的请求，必须使用应用程序的凭据和安装 ID 创建安装访问令牌。

应用程序客户端会为开发者处理所有这些事情，比如：在安装应用程序的每个存储库中调度存储库事件。

import { App } from "octokit";
const app = new App({ appId, privateKey });
for await (const { octokit, repository } of app.eachRepository.iterator()) {
  // https://docs.github.com/en/rest/reference/repos#create-a-repository-dispatch-event
  await octokit.rest.repos.createDispatchEvent({
    owner: repository.owner.login,
    repo: repository.name,
    event_type: "my_event",
    client_payload: {
      foo: "bar",
    },
  });
  console.log("Event distpatched for %s", repository.full_name);
}

下面获取经过身份验证的 octokit 实例作为安装：

const octokit = await app.getInstallationOctokit(123);

5.Webhooks

独立模块：@octokit/webhooks

安装应用程序时，应用程序注册请求的事件将作为请求发送到应用程序注册中设置的 Webhook URL。

Webhook 事件请求使用 Webhook 密钥进行签名，这也是应用程序注册的一部分，开发者必须在处理请求负载之前验证该秘钥。

app.webhooks.* API 提供了接收、验证和处理 webhook 事件的方法。

import { createServer } from "node:http":
import { App, createNodeMiddleware } from "octokit";
const app = new App({
  appId,
  privateKey,
  webhooks: { secret },
});
app.webhooks.on("issues.opened", ({ octokit, payload }) => {
  return octokit.rest.issues.createComment({
    owner: payload.repository.owner.login,
    repo: payload.repository.name,
    body: "Hello, World!",
  });
});
// Your app can now receive webhook events at `/api/github/webhooks`
createServer(createNodeMiddleware(app)).listen(3000);

6. 开放认证（OAuth）

独立模块：@octokit/oauth-app

OAuth 应用程序和 GitHub 应用程序都支持使用 OAuth 对 GitHub 用户进行身份验证，但是两者有一些区别：

• 只有 OAuth 应用程序支持范围。 GitHub 应用程序具有权限，并且通过在存储库上安装应用程序来授予访问权限。
• 仅 GitHub 应用程序支持过期的用户令牌
• 仅 GitHub 应用程序支持创建作用域令牌以减少权限和存储库访问

App 适用于 GitHub 应用程序，如果需要 OAuth 应用程序特定的功能，请改用 OAuthApp。

示例：当用户使用 OAuth Web 流登录时监视存储库：

import { createServer } from "node:http":
import { App, createNodeMiddleware } from "octokit";

const app = new App({
  oauth: { clientId, clientSecret },
});

app.oauth.on("token.created", async ({ token, octokit }) => {
  await octokit.rest.activity.setRepoSubscription({
    owner: "octocat",
    repo: "hello-world",
    subscribed: true,
  });
});
// 应用程序可以在 /api/github/oauth/callback 接收 OAuth 重定向
// 用户可以通过打开 /api/oauth/login 来启动 OAuth Web 流程
createServer(createNodeMiddleware(app)).listen(3000);

7.Action client

独立模块：@octokit/action

一个成熟的 Action 客户端正在研发中，暂时可以继续使用@actions/github

7.本文总结

本文主要和大家介绍 octokit.js，即适用于浏览器、Node.js 和 Deno 的全能 GitHub SDK。相信通过本文的阅读，大家对 octokit.js 会有一个初步的了解。

因为篇幅有限，关于 octokit.js 的更多用法和特性文章并没有过多展开，如果有兴趣，可以在我的主页继续阅读，同时文末的参考资料提供了大量优秀文档以供学习。最后，欢迎大家点赞、评论、转发、收藏，您的支持是我不断创作的动力。

参考资料

https://github.com/octokit/octokit.js

https://www.npmjs.com/package/octokit

https://learn.microsoft.com/zh-cn/training/modules/automate-devops-github-apps/2-what-are-github-apps

https://github.com/marketplace?type=apps

https://docs.github.com/zh/apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-oauth-apps

https://github.blog/2013-10-30-introducing-octokit-net/

https://twitter.com/github/status/395675928392896513