Octocrab: 现代且可扩展的GitHub API客户端。

Octocrab是一个第三方GitHub API客户端，允许您轻松使用Rust构建自己的GitHub集成或机器人。Octocrab提供了两套主要的API来与GitHub通信，一个用于GitHub的高层强类型语义API，以及一个用于扩展行为的低层HTTP API。

添加Octocrab

在您的终端中运行此命令以添加Octocrab的最新版本。

cargo add octocrab

语义API

语义API提供围绕GitHub API的强类型支持，一组映射到GitHub类型的models，以及用于GitHub应用的auth函数。截至版本0.17，以下模块可用。

• actions GitHub Actions。
• apps GitHub Apps。
• current 当前用户信息。
• gitignore Gitignore模板。
• graphql GraphQL。
• issues 问题及相关项目，例如评论、标签等。
• licenses 许可证元数据。
• markdown 使用GitHub渲染Markdown。
• orgs GitHub组织。
• pulls 提交请求。
• releases 发布版本。
• repos 代码库。
• search GitHub 的搜索 API。
• teams 团队。
• gists GitHub 的 Gist API
• users 用户。
• code_scannings 代码扫描

获取拉取请求

// Get pull request #5 from `XAMPPRocky/octocrab`.
let issue = octocrab::instance().pulls("XAMPPRocky", "octocrab").get(5).await?;

所有具有多个可选参数的方法都构建为 Builder 结构体，允许您轻松指定参数。

列出问题

let octocrab = octocrab::instance();
// Returns the first page of all issues.
let mut page = octocrab
    .issues("XAMPPRocky", "octocrab")
    .list()
    // Optional Parameters
    .creator("XAMPPRocky")
    .state(params::State::All)
    .per_page(50)
    .send()
    .await?;

// Go through every page of issues. Warning: There's no rate limiting so
// be careful.
loop {
    for issue in &page {
        println!("{}", issue.title);
    }
    page = match octocrab
        .get_page::<models::issues::Issue>(&page.next)
        .await?
    {
        Some(next_page) => next_page,
        None => break,
    }
}

HTTP API

当前类型化 API 未能涵盖 GitHub API 的全部内容，尽管如此，由于 GitHub 正在积极开发，此库在某些时间点可能始终落后于 GitHub。但这并不意味着为了使用这些功能，您必须分叉或用您自己的解决方案替换 octocrab。

相反，octocrab 提供了一套 HTTP 方法，允许您轻松扩展 Octocrab 的现有行为。使用这些 HTTP 方法允许您继续使用相同的身份验证和配置，同时控制请求和响应。每个 HTTP 方法都有一个方法，如 get、post、patch、put、delete，它们都接受一个相对路由和一个可选的正文。

let user: octocrab::models::User = octocrab::instance()
    .get("/user", None::<&()>)
    .await?;

每个 HTTP 方法都期望一个正文，使用基本 URL 格式化 URL，如果 GitHub 返回不成功的状态，则发生错误。但是，当与 GitHub API 一起工作时，这并不总是希望的，有时您需要检查响应状态或头。因此，存在配套的方法 _get、_post 等，这些方法对请求不进行任何额外的预处理或后处理。

let octocrab = octocrab::instance();
let response = octocrab
    ._get("https://api.github.com/organizations")
    .await?;

// You can also use `Uri::builder().authority("<my custom base>").path_and_query("<my custom path>")` if you want to customize the base uri and path.
let response =  octocrab
    ._get(Uri::builder().path_and_query("/organizations").build().expect("valid uri"))
    .await?;

您可以使用这些 HTTP 方法轻松地为 Octocrab 的类型化 API 创建自己的扩展。（需要 async_trait）。

use octocrab::{Octocrab, Page, Result, models};

#[async_trait::async_trait]
trait OrganisationExt {
  async fn list_every_organisation(&self) -> Result<Page<models::Organization>>;
}

#[async_trait::async_trait]
impl OrganisationExt for Octocrab {
  async fn list_every_organisation(&self) -> Result<Page<models::Organization>> {
    self.get("/organizations", None::<&()>).await
  }
}

您还可以使用 serde 轻松访问当前模型中不可用的新属性。

#[derive(Deserialize)]
struct RepositoryWithVisibility {
    #[serde(flatten)]
    inner: octocrab::models::Repository,
    visibility: String,
}

let my_repo = octocrab::instance()
    .get::<RepositoryWithVisibility>("https://api.github.com/repos/XAMPPRocky/octocrab", None::<&()>)
    .await?;

静态 API

Octocrab 还提供其 API 的静态引用计数版本，允许您轻松将其插入现有系统，而无需担心必须集成和传递客户端。

// Initialises the static instance with your configuration and returns an
// instance of the client.
octocrab::initialise(octocrab::Octocrab::builder());
// Gets a instance of `Octocrab` from the static API. If you call this
// without first calling `octocrab::initialise` a default client will be
// initialised and returned instead.
let octocrab = octocrab::instance();