mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-28 05:46:36 +08:00
ryan
228 lines
5.7 KiB
Markdown
228 lines
5.7 KiB
Markdown
# Context 模式
|
||
|
||
派生、检查和传播 `context.Context` 的常见模式。
|
||
|
||
---
|
||
|
||
## Context 不可变性
|
||
|
||
Context 是不可变的。将同一个 `ctx` 传递给共享相同截止时间、取消信号、凭据和父级追踪的多个调用是安全的：
|
||
|
||
```go
|
||
// 安全：同一个 context 传递给顺序调用
|
||
func ProcessBatch(ctx context.Context, items []Item) error {
|
||
for _, item := range items {
|
||
if err := process(ctx, item); err != nil {
|
||
return err
|
||
}
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// 安全：同一个 context 传递给并发调用
|
||
func ProcessConcurrently(ctx context.Context, a, b *Data) error {
|
||
g, ctx := errgroup.WithContext(ctx)
|
||
g.Go(func() error { return processA(ctx, a) })
|
||
g.Go(func() error { return processB(ctx, b) })
|
||
return g.Wait()
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 何时使用 context.Background()
|
||
|
||
仅在**从不特定于请求**的函数中使用 `context.Background()`：
|
||
|
||
```go
|
||
func main() {
|
||
ctx := context.Background()
|
||
if err := run(ctx); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
}
|
||
|
||
func startBackgroundWorker() {
|
||
ctx := context.Background()
|
||
go worker(ctx)
|
||
}
|
||
```
|
||
|
||
**默认传递 Context**，即使你认为不需要。只有在有充分理由说明传递 context 是错误做法时，才直接使用 `context.Background()`：
|
||
|
||
```go
|
||
func LoadConfig(ctx context.Context) (*Config, error) {
|
||
// 即使现在不使用 ctx，接受它可以在未来添加功能时
|
||
// 不需要修改 API
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 派生 Context
|
||
|
||
```go
|
||
// 添加超时 — 持续时间结束后触发取消
|
||
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
|
||
defer cancel()
|
||
|
||
// 添加取消 — 调用者控制何时取消
|
||
ctx, cancel := context.WithCancel(ctx)
|
||
defer cancel()
|
||
|
||
// 添加截止时间 — 在指定的墙钟时间触发取消
|
||
ctx, cancel := context.WithDeadline(ctx, time.Now().Add(time.Hour))
|
||
defer cancel()
|
||
|
||
// 添加值（谨慎使用 — 仅用于请求作用域数据）
|
||
ctx = context.WithValue(ctx, requestIDKey, reqID)
|
||
```
|
||
|
||
创建派生 context 后，**始终立即 `defer cancel()`**。这确保即使函数提前返回，资源也会被释放。
|
||
|
||
### 嵌套派生
|
||
|
||
派生的 context 形成树状结构。取消父级会取消所有子级：
|
||
|
||
```go
|
||
func handleRequest(ctx context.Context) error {
|
||
// 整个请求的父级超时
|
||
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
|
||
defer cancel()
|
||
|
||
// 数据库调用的更短超时
|
||
dbCtx, dbCancel := context.WithTimeout(ctx, 5*time.Second)
|
||
defer dbCancel()
|
||
|
||
data, err := queryDB(dbCtx)
|
||
if err != nil {
|
||
return err
|
||
}
|
||
|
||
// 父级 context 的剩余时间适用于此处
|
||
return sendResponse(ctx, data)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 检查取消
|
||
|
||
### 在长时间运行的循环中
|
||
|
||
```go
|
||
func LongRunningOperation(ctx context.Context) error {
|
||
for {
|
||
select {
|
||
case <-ctx.Done():
|
||
return ctx.Err()
|
||
default:
|
||
// 执行工作
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 在高开销操作之前
|
||
|
||
在开始无法中断的工作之前检查取消：
|
||
|
||
```go
|
||
func ProcessItems(ctx context.Context, items []Item) error {
|
||
for _, item := range items {
|
||
if ctx.Err() != nil {
|
||
return ctx.Err()
|
||
}
|
||
if err := expensiveProcess(item); err != nil {
|
||
return err
|
||
}
|
||
}
|
||
return nil
|
||
}
|
||
```
|
||
|
||
### 区分取消原因
|
||
|
||
```go
|
||
if err := ctx.Err(); err != nil {
|
||
switch {
|
||
case errors.Is(err, context.Canceled):
|
||
// 调用者显式取消（例如客户端断开连接）
|
||
case errors.Is(err, context.DeadlineExceeded):
|
||
// 超时或截止时间已过
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 在 HTTP 处理器中遵守取消
|
||
|
||
```go
|
||
func handler(w http.ResponseWriter, r *http.Request) {
|
||
ctx := r.Context()
|
||
|
||
result, err := slowOperation(ctx)
|
||
if err != nil {
|
||
if errors.Is(err, context.Canceled) {
|
||
// 客户端已断开连接 — 无需写入
|
||
return
|
||
}
|
||
http.Error(w, err.Error(), http.StatusInternalServerError)
|
||
return
|
||
}
|
||
|
||
json.NewEncoder(w).Encode(result)
|
||
}
|
||
```
|
||
|
||
`r.Context()` 在以下情况被取消：
|
||
- 客户端关闭连接
|
||
- `http.Server` 的 `ReadTimeout` 或 `WriteTimeout` 触发
|
||
- `ServeHTTP` 方法返回
|
||
|
||
---
|
||
|
||
## Context 值的最佳实践
|
||
|
||
### 使用未导出的键类型
|
||
|
||
```go
|
||
type contextKey struct{}
|
||
|
||
var userIDKey contextKey
|
||
|
||
func WithUserID(ctx context.Context, id string) context.Context {
|
||
return context.WithValue(ctx, userIDKey, id)
|
||
}
|
||
|
||
func UserIDFromContext(ctx context.Context) (string, bool) {
|
||
id, ok := ctx.Value(userIDKey).(string)
|
||
return id, ok
|
||
}
|
||
```
|
||
|
||
使用未导出的结构体类型作为键可以防止与其他包的键发生冲突 — 即使它们使用相同的 string 或 int 值。
|
||
|
||
### 提供访问器函数
|
||
|
||
始终将 `context.WithValue` 和 `ctx.Value` 包装在类型化的辅助函数中（如上所示），而不是暴露键。这提供了类型安全性和一个可以修改实现的单一位置。
|
||
|
||
---
|
||
|
||
## 快速参考
|
||
|
||
| 模式 | 指导 |
|
||
|------|------|
|
||
| 参数位置 | 始终第一个：`func F(ctx context.Context, ...)` |
|
||
| 结构体存储 | 不要存储在结构体中；传递给方法 |
|
||
| 自定义类型 | 不要创建；使用 `context.Context` 接口 |
|
||
| 应用数据 | 优先选择 参数 > 接收者 > 全局变量 > context 值 |
|
||
| 请求作用域数据 | 适用于 context 值 |
|
||
| 共享 context | 安全 — context 是不可变的 |
|
||
| `context.Background()` | 仅用于非请求特定的代码 |
|
||
| 默认行为 | 即使认为不需要也要传递 context |
|
||
| `defer cancel()` | 在 `WithTimeout`/`WithCancel`/`WithDeadline` 之后始终立即 defer |
|
||
| 值键 | 使用未导出的结构体类型，提供访问器函数 |
|
||
| 取消检查 | 在高开销操作前使用 `ctx.Err()`；在循环中使用 `select` 监听 `ctx.Done()` |
|