Context

本文翻译自《Canceling in-progress operations》。你可以使用Go的context.Context管理正在进行中的操作。Context是一个标准的Go类型，可用来报告它所代表的整体操作是否已被取消并且不再需要。通过在你的应用程序中跨函数或服务传递context.Context，可以提前停止工作并返回一个错误。有关Context的更多信息，请参阅Go并发模式：Context。

例如，你可能希望：

结束长时间运行的操作，包括耗时过长的数据库操作。
传播来自其他地方的“取消继续工作”请求，例如当客户端关闭连接时。

Go的许多API都采用Context参数，使你更容易在整个应用程序中使用Context。

超时后取消正在进行中的数据库操作

你可以使用Context来设置超时时间或截止时间，在此之后操作将被取消。要派生具有超时时间或截止时间的Context，请调用Context.WithTimeout或Context.WithDeadline函数。

以下示例中的代码派生一个附带超时时间的Context，并将其传递到sql.DB的QueryContext方法中。

func QueryWithTimeout(ctx context.Context) {
    // 创建一个附带超时时间的Context。
    queryCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    // 传入这个附带超时时间的Context和一个查询语句。
    rows, err := db.QueryContext(queryCtx, "SELECT * FROM album")
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()

    // 处理返回的行数据。
}

当一个context从外部的context派生而来时，由于queryCtx在本例中是从函数参数ctx派生的，如果外部的context被取消，那么派生的context也会自动取消。例如，在HTTP服务器中，HTTP.Request.Context方法返回与请求相关联的context。如果HTTP客户端断开连接或取消HTTP请求（可能使用HTTP/2），则该context将被取消。如果整个HTTP请求被取消，或者查询耗时超过五秒，那么将HTTP请求的context传递给上面的QueryWithTimeout函数将导致数据库查询操作提前结束。

注意：当你在创建带有超时时间或截止时间的一个新context时，总是应该defer对这个context的cancel方法的调用。当包含这个新context的函数退出时，就能释放这个新context所持有的资源。它还将取消queryCtx，当这个新context的cancel方法返回时，就不应该再使用queryCtx。

本文翻译自《Contexts and structs》。

Jean de Klerk, Matt T. Proud

24 February 2021

介绍

在许多Go API，尤其是现代API中，函数和方法的第一个参数通常是context.Context。上下文提供了一种跨API边界和进程之间传输截止时间(deadline)、调用者取消(caller cancellation)和请求范围内的其他值的方法。当库直接或传递地与远程服务器（例如数据库、API等）交互时，通常会使用它。

Context（上下文）的文档指出：Context不应该存储在结构体类型中，而是传递给每个需要它的函数。

本文扩展了该建议的原因和示例，描述了为什么传递Context而不是将其存储在另一种类型中很重要。它还强调了在结构体类型中存储Context可能有意义的一个罕见情况，以及如何安全地这样做。

首选作为参数传递的context

为了理解不将context存储在结构体中的建议，让我们考虑首选的把context作为参数的方法：

// Worker获取work并将其添加到远程工作编排服务器。
type Worker struct { /* … */ }

type Work struct { /* … */ }

func New() *Worker {
  return &Worker{}
}

func (w *Worker) Fetch(ctx context.Context) (*Work, error) {
  _ = ctx // 每次调用ctx用于取消、截止时间和元数据。
}

func (w *Worker) Process(ctx context.Context, work *Work) error {
  _ = ctx // 每次调用ctx用于取消、截止时间和元数据。
}

在这里，(*Worker).Fetch和(*Worker).Process方法都直接接受context。通过这种作为参数传递的设计，用户可以设置每次调用的截止时间、取消和元数据。而且，很清楚如何使用传递给每个方法的context.Context：没有悬念传递给一个方法的context.Context将被任何其他方法使用。这是因为context被限定为尽可能小的操作，这极大地增加了这个包中context的实用性和清晰度。

在结构体中存储context会导致混乱

让我们用不受欢迎的在结构体中使用context(context-in-struct)方法再次检查上面的Worker示例。它的问题在于，当你将context存储在结构体中时，你会模糊调用者的生命周期，或者更糟的是以不可预知的方式将两个作用域混合在一起：

type Worker struct {
  ctx context.Context
}

func New(ctx context.Context) *Worker {
  return &Worker{ctx: ctx}
}

func (w *Worker) Fetch() (*Work, error) {
  _ = w.ctx // 共享的w.ctx用于取消、截止时间和元数据。
}

func (w *Worker) Process(work *Work) error {
  _ = w.ctx // 共享的w.ctx用于取消、截止时间和元数据。
}

(*Worker).Fetch和(*Worker).Process方法都使用存储在Worker中的context。这可以防止Fetch和Process的调用者（它们本身可能有不同的context）指定截止时间、请求取消以及在每个调用的基础上附加元数据。例如：用户无法为(*Worker).Fetch提供截止时间，或仅取消(*Worker).Process调用。调用者的生命周期与共享的context混合在一起，并且context的作用域局限于创建的Worker的生命周期。

与通过参数传递(pass-as-argument)的方法相比，API也更容易让用户感到困惑。用户可能会问自己：

由于New需要一个context.Context，构造函数做的工作是否需要取消或截止时间？
传递给New的context.Context是否适用于(*Worker).Fetch和(*Worker).Process？两者都不？这一个但不是另一个？

API需要大量文档来明确告诉用户context.Context的用途。用户可能还必须阅读源代码，而不是能够依赖API传达的信息。

最后，这么设计一个生产级服务可能非常危险，它的每个请求都没有context，因此不能充分执行取消。如果无法设置每次调用的最后时间，你的进程可能会积压并耗尽其资源（例如内存）！

规则的例外：保持向后兼容性

当引入context.Context的Go 1.7发布时，大量API必须以向后兼容的方式添加context支持。例如，net/http的Client方法，像Get和Do，是context的绝佳候选者。使用这些方法发送的每个外部请求都将受益于context.Context附带的截止时间、取消和元数据支持。

有两种方法可以向后兼容的方式添加对context.Context的支持：在结构体中包含context，我们稍后会看到，以及复制函数，复制的函数接受context.Context并将Context作为其函数名后缀。复制方法应优先于在结构体中使用context，并在《保持模块兼容》中进一步讨论。但是，在某些情况下它是不切实际的：例如，如果你的API公开了大量函数，那么复制它们可能是不可行的。

net/http包选择了在结构体中使用context的方法，它提供了一个有用的案例研究。让我们看看net/http的Do。在引入context.Context之前，Do定义如下：

// Do发送一个HTTP请求并返回一个HTTP响应 [...]
func (c *Client) Do(req *Request) (*Response, error)

在Go 1.7之后，如果不是因为它会破坏向后兼容性，Do可能看起来像下面这样：

// Do发送一个HTTP请求并返回一个HTTP响应 [...]
func (c *Client) Do(ctx context.Context, req *Request) (*Response, error)

但是，保持向后兼容性并遵守Go 1的兼容性承诺对于标准库至关重要。因此，维护者选择在http.Request结构里添加context.Context以允许支持context.Context而不会破坏向后兼容性：

// Request代表服务器接收到的HTTP请求或将由客户端发送的HTTP请求。
// ...
type Request struct {
  ctx context.Context

  // ...
}

// NewRequestWithContext在给定method、URL和可选body的情况下返回一个新请求。
// [...]
// 给定的ctx用于Request的生命周期。
func NewRequestWithContext(ctx context.Context, method, url string, body io.Reader) (*Request, error) {
  // 为简洁起见，本文进行了简化。
  return &Request{
    ctx: ctx,
    // ...
  }
}

// Do发送一个HTTP请求并返回一个HTTP响应 [...]
func (c *Client) Do(req *Request) (*Response, error)

当改造你的API以支持context时，将context.Context添加到结构体中可能是有意义的，如上所述。但是，请记住首先考虑复制你的函数，这允许在不牺牲实用性和理解性的情况下以向后兼容的方式改进context.Context。例如：

// Call在内部使用context.Background；要指定context，请使用CallContext。
func (c *Client) Call() error {
  return c.CallContext(context.Background())
}

func (c *Client) CallContext(ctx context.Context) error {
  // ...
}

总结

context可以轻松地将重要的跨库和跨API信息传播到调用堆栈。但是，它必须一致且清晰地使用，以保持可理解、易于调试和有效。

当作为方法中的第一个参数而不是存储在结构类型中传递时，用户可以充分利用其可扩展性，以便通过调用堆栈构建强大的取消、截止时间和元数据信息树。而且，最重要的是，当它作为参数传入时，可以清楚地理解它的作用域，从而在堆栈上下都有清晰的理解和可调试性。

在设计带有context的API时，请记住以下建议：将context.Context作为参数传入；不要将它存储在结构体中。

标签： Context

取消正在进行中的数据库操作

Context和结构体