Flutter GitHub集成插件github_kit的使用

GitHubKit 是一个全面的 Dart 包，用于与 GitHub API 交互。它提供了易于使用的接口来执行常见的 GitHub 操作，并支持高级功能，如 GitHub Actions、代码扫描和秘密扫描。

目录

• 特性
• 安装
• 使用
  • 初始化
  • 仓库管理
  • 问题处理
  • 拉取请求
  • GitHub Actions
  • 代码扫描
  • 秘密扫描
  • GraphQL API
• 错误处理
• 分页
• 速率限制
• 日志记录
• 测试
• 示例
• 贡献
• 许可证

特性

• 完整覆盖 GitHub REST API v3
• 支持 GitHub GraphQL API v4
• 仓库管理
• 问题和拉取请求处理
• GitHub Actions 工作流管理
• 代码扫描和秘密扫描 API
• 自动分页处理
• 内置速率限制处理和自动重试
• 全面的日志系统
• 带有自定义异常的简单错误处理
• 完整的认证支持（个人访问令牌）
• 丰富的文档和示例

安装

在你的包的 pubspec.yaml 文件中添加以下依赖项：

dependencies:
  github_kit: ^1.0.0

然后运行：

$ dart pub get

使用

初始化

首先，导入包并创建 GitHubKit 的实例：

import 'package:github_kit/github_kit.dart';

final gitHubKit = GitHubKit(token: 'your_personal_access_token');

仓库管理

获取仓库：

// 获取仓库
final repo = await gitHubKit.repositories.getRepository('octocat', 'Hello-World');
print('Repository: ${repo.fullName}');

创建仓库：

// 创建仓库
final newRepo = await gitHubKit.repositories.createRepository('New-Repo', private: true);
print('Created new repository: ${newRepo.fullName}');

列出仓库：

// 列出仓库
final repos = await gitHubKit.repositories.listRepositories('octocat');
for (var repo in repos) {
  print('Repo: ${repo.name}');
}

问题处理

创建问题：

// 创建问题
final issue = await gitHubKit.issues.createIssue('octocat', 'Hello-World', 'Bug report', body: 'This is a bug report');
print('Created issue #${issue.number}');

获取问题：

// 获取问题
final fetchedIssue = await gitHubKit.issues.getIssue('octocat', 'Hello-World', 1);
print('Issue title: ${fetchedIssue.title}');

列出问题：

// 列出问题
final issues = await gitHubKit.issues.listIssues('octocat', 'Hello-World', state: 'open');
for (var issue in issues) {
  print('Issue #${issue.number}: ${issue.title}');
}

拉取请求

创建拉取请求：

// 创建拉取请求
final pr = await gitHubKit.pullRequests.createPullRequest('octocat', 'Hello-World', 'New feature', 'feature-branch', 'main');
print('Created PR #${pr.number}');

获取拉取请求：

// 获取拉取请求
final fetchedPR = await gitHubKit.pullRequests.getPullRequest('octocat', 'Hello-World', 1);
print('PR title: ${fetchedPR.title}');

列出拉取请求：

// 列出拉取请求
final prs = await gitHubKit.pullRequests.listPullRequests('octocat', 'Hello-World', state: 'open');
for (var pr in prs) {
  print('PR #${pr.number}: ${pr.title}');
}

GitHub Actions

列出工作流：

// 列出工作流
final workflows = await gitHubKit.actions.listWorkflows('octocat', 'Hello-World');
for (var workflow in workflows) {
  print('Workflow: ${workflow.name}');
}

创建工作流调度事件：

// 创建工作流调度事件
await gitHubKit.actions.createWorkflowDispatch('octocat', 'Hello-World', 'main.yml', 'main');
print('Workflow dispatch created');

代码扫描

列出代码扫描警报：

// 列出代码扫描警报
final alerts = await gitHubKit.codeScanning.listCodeScanningAlerts('octocat', 'Hello-World');
for (var alert in alerts) {
  print('Alert #${alert.number}: ${alert.state}');
}

秘密扫描

列出秘密扫描警报：

// 列出秘密扫描警报
final secretAlerts = await gitHubKit.secretScanning.listSecretScanningAlerts('octocat', 'Hello-World');
for (var alert in secretAlerts) {
  print('Secret Alert #${alert.number}: ${alert.state}');
}

GraphQL API

使用 GraphQL 查询：

// 使用 GraphQL 查询
final result = await gitHubKit.graphql('''
  query {
    viewer {
      login
      repositories(first: 10) {
        nodes {
          name
          stargazerCount
        }
      }
    }
  }
''');
print('Logged in as: ${result['viewer']['login']}');

错误处理

GitHubKit 使用自定义异常进行错误处理。始终用 try-catch 块包裹 API 调用：

try {
  final repo = await gitHubKit.repositories.getRepository('octocat', 'Hello-World');
  print('Repository: ${repo.fullName}');
} catch (e) {
  if (e is GitHubException) {
    print('GitHub API Error: ${e.message} (Status: ${e.statusCode})');
  } else {
    print('Error: $e');
  }
}

分页

大多数列表方法在 GitHubKit 中自动处理分页。可以使用 perPage 和 page 参数控制分页：

// 控制分页
final repos = await gitHubKit.repositories.listRepositories('octocat', perPage: 100, page: 2);

速率限制

GitHubKit 通过在达到限制时重试请求来自动处理速率限制。可以在创建 GitHubKit 实例时配置重试行为：

// 配置重试行为
final gitHubKit = GitHubKit(
  token: 'your_token',
  maxRetries: 5,
  retryDelay: Duration(seconds: 10),
);

日志记录

GitHubKit 包含内置的日志系统。可以在创建 GitHubKit 实例时配置日志级别：

// 配置日志级别
final gitHubKit = GitHubKit(token: 'your_token');
gitHubKit.setLogLevel(LogLevel.debug);

测试

要运行 GitHubKit 的测试：

$ dart test