集成者最佳实践

有兴趣与 GitHub 平台集成吗？与您志趣相投的大有人在。本指南将帮助您构建能够为用户提供最佳体验并确保与 API 进行可靠交互的应用程序。

确保安全接收从 GitHub 交付的有效负载

确保安全接收从 GitHub 发送的有效负载非常重要。虽然有效负载中不会传输个人信息，但泄露任何信息总是不好的。有些信息可能比较敏感，包括提交者电子邮件地址或私有仓库的名称。

您可以采取以下几个步骤来确保安全接收由 GitHub 交付的工作负载：

确保您的接收服务器在 HTTPS 连接上。默认情况下，GitHub 在交付有效负载时会验证 SSL 证书。
提供密钥令牌以确保有效负载肯定来自 GitHub。通过实施密钥令牌，您可以确保服务器接收的任何数据绝对来自 GitHub。理想情况下，您应该为您服务的每个用户都提供一个不同的密钥令牌。这样，即使某个令牌被泄露，也不至于影响其他用户。

支持异步工作而非同步工作

GitHub 要求在收到 web 挂钩有效负载后 30 秒内做出集成响应。如果您的服务需要更长的时间才能完成，则 GitHub 将终止连接，并且有效负载将丢失。

由于无法预测您的服务完成速度，因此您应该在后台作业中执行所有“实际工作”。 Resque（用于 Ruby）、RQ（用于 Python）或 RabbitMQ（用于 Java）是可以排队和处理后台作业的典型库。

请注意，即使在后台作业中执行工作，GitHub 仍要求您的服务器能够在三十秒内做出响应。您的服务器需要通过发送某种响应来确认它收到了有效负载。您的服务必须尽快对有效负载执行任何验证，以便您能够准确地报告您的服务器是否会继续处理请求。

响应 GitHub 时使用适当的 HTTP 状态代码

每个 web 挂钩都有自己的“最近交付”部分，其中列出了部署是否成功。

向用户提供尽可能多的信息

用户可能会深入研究您发回 GitHub 的服务器响应。请确保您的信息清晰明了。

查看有效负载响应

遵循 API 发送给您的任何重定向

GitHub 在资源发生移动时会通过提供重定向状态代码来明确告诉您。您应该遵循这些重定向。每个重定向响应都使用要转到的新 URI 来设置 Location 标头。如果您收到了重定向，最好更新代码以遵循新的 URI，以防您请求我们可能已删除的无效路径。

我们提供了 HTTP 状态代码列表，供您在设计应用程序时参考以便遵循重定向。

不要手动解析 URL

通常，API 响应包含 URL 形式的数据。例如，当请求仓库时，我们会发送一个名为 clone_url 的键，其中包含可用来克隆仓库的 URL。

为了应用程序的稳定性，您不应该尝试解析此数据，或者尝试猜测并构造未来 URL 的格式。否则，如果我们决定更改该 URL，您的应用程序可能会中断。

例如，在处理分页结果时，往往很想构造 URL - 在末尾追加 ?page=<number>。要抑制这种冲动。我们的分页指南提供了一些关于可靠跟踪分页结果的安全提示。

在处理事件之前检查事件类型和操作

有多种 web 挂钩事件类型，并且每个事件可以有多个操作。随着 GitHub 功能集的增长，我们会不时添加新的事件类型或向现有事件类型添加新的操作。请确保您的应用程序在进行任何 web 挂钩处理之前明确检查事件的类型和操作。 X-GitHub-Event 请求标头可用于了解收到了哪个事件，以便进行适当处理。同样，有效负载具有顶层 action 键，可用于了解对相关对象采取了哪些操作。

例如，如果您已将 GitHub web 挂钩配置为“向我发送所有内容”，则在添加新的事件类型和操作时，您的应用程序就会开始接收它们。因此，不建议使用任何类型的 catch-all else 子句。以下面的代码为例：

# Not recommended: a catch-all else clause
def receive
  event_type = request.headers["X-GitHub-Event"]
  payload    = request.body

  case event_type
  when "repository"
    process_repository(payload)
  when "issues"
    process_issues(payload)
  else
    process_pull_requests
  end
end

在此代码实例中，如果收到 repository 或 issues 事件，将会正确调用 process_repository 和 process_issues 方法。但是，任何其他事件类型都会导致调用 process_pull_requests。当添加新的事件类型时，这将导致不正确的行为 - 将以处理 pull_request 事件的方式来处理新的事件类型。

因此，我们建议明确检查事件类型并采取相应行动。在以下代码示例中，我们明确检查 pull_request 事件，而 else 子句仅记录我们已收到新事件类型：

# Recommended: explicitly check each event type
def receive
  event_type = request.headers["X-GitHub-Event"]
  payload    = JSON.parse(request.body)

  case event_type
  when "repository"
    process_repository(payload)
  when "issues"
    process_issue(payload)
  when "pull_request"
    process_pull_requests(payload)
  else
    puts "Oooh, something new from GitHub: #{event_type}"
  end
end

由于每个事件也可以有多个操作，因此建议对操作进行类似的检查。例如，IssuesEvent 可能有几个操作。其中包括创建议题时的 opened、关闭议题时的 closed以及将议题分配给某人时的 assigned。

与添加事件类型一样，我们可以向现有事件添加新操作。因此，再次强调，在检查事件的操作时不要使用任何类型的 catch-all else 子句。相反，我们建议像检查事件类型一样明确检查事件操作。下面的示例非常吻合我们在上文中针对事件类型的建议：

# Recommended: explicitly check each action
def process_issue(payload)
  case payload["action"]
  when "opened"
    process_issue_opened(payload)
  when "assigned"
    process_issue_assigned(payload)
  when "closed"
    process_issue_closed(payload)
  else
    puts "Oooh, something new from GitHub: #{payload["action"]}"
  end
end

在此示例中，在调用 process_closed 方法之前会先检查 closed 操作。任何未识别的操作都会被记录以供将来参考。

处理 API 错误

尽管您的代码从未引入漏洞，但您可能会发现在尝试访问 API 时遇到连续错误。

您应该确保与 API 正确交互，而不是忽略重复的 4xx 和 5xx 状态代码。例如，如果某个端点请求一个字符串，而您向其传递一个数值，则您将会收到 5xx 验证错误，并且您的调用不会成功。同样，试图访问未经授权或不存在的端点会导致 4xx 错误。

故意忽略重复的验证错误可能会导致您的应用程序因滥用而被暂停。

按产品浏览