Go context 怎样避免把可选参数塞进 Context

如果一个函数只接收 ctx，却要从里面找分页上限、排序方向和开关，它的调用契约并没有变简单，只是变得不可见了。我更愿意先把“输入缺失”和“默认行为”讲清楚，再决定哪些数据值得放进 Context。本文围绕查询接口做一次分层排查：不是禁止 WithValue，而是不让它替函数参数承担业务配置职责。

现象：函数签名干净，调用条件却藏起来了

典型现象是：HTTP 入口能调用成功，后台任务却得到另一种结果；同一个 Search 接口，有的调用者设置字符串键 limit，有的没有设置；读取端又把缺失值默认为某个数字。此时编译器无法提醒调用者少传了业务选项，问题只能沿 Value 的写入点追踪。

我的第一项检查是看函数是否使用类似 ctx.Value("limit") 的表达式决定结果。查询数量、排序方式、是否包含归档记录，都在改变本次操作的含义。把字符串键换成私有键只能解决键冲突，不能解决隐藏参数。也不要因为一个值“只在这次请求里有效”，就自动认定它应该进入 Context。

分层检查：这个值属于请求还是本次操作

我通常把数据分成三层：业务输入是本次要做什么，例如查询条件；操作选项是怎样做，例如查询上限和排序方向；请求范围数据是跨接口伴随请求的元数据，例如供日志关联的追踪标识。前两层直接声明在签名或 Options 中，第三层才考虑 Context。固定的仓库、客户端和全局配置属于对象依赖，不属于临时请求袋子。

context.Context 还承载取消与期限。这种控制语义应继续传给下游，不需要为了移走业务选项就删掉 ctx。图中“请求范围”包括 context.Context、取消与期限、追踪标识；“操作契约”包括函数参数、查询条件、查询选项，两组代表不同责任。

边界不取决于数据类型：一个 string 可以是查询条件，也可以是追踪标识。更有用的问题是：没有这个值，业务函数是否仍然知道调用者要求什么？如果答案是否定的，优先把它作为显式输入。身份、租户等必需的授权条件也应在可信边界解析并校验；不能用“Context 里可能有”替代权限检查，更不能缺失后默认访问全部数据。

修复动作：把查询选项放回显式参数

下面是原创接口示例。Service 使用构造函数接收仓库；Search 的第一个参数仍是 ctx，其余参数声明查询条件和 Options。零上限表示默认值，负数或过大值直接返回错误。示例只讨论契约，不提供真实数据库实现，也不声称已运行测试。

package search

import (
    "context"
    "errors"
    "strings"
)

// Options 明确声明调用者可以控制的查询选项。
type Options struct {
    Limit int
    Desc  bool
}

// Item 是示例查询结果，不包含共享可变状态。
type Item struct {
    Name string
}

// Repository 将取消信号、业务条件和选项分别声明在接口上。
type Repository interface {
    Find(ctx context.Context, query string, opts Options) ([]Item, error)
}

type Service struct {
    repo Repository
}

// NewService 在构造阶段声明固定依赖，不把仓库塞进 Context。
func NewService(repo Repository) *Service {
    return &Service{repo: repo}
}

// Search 在操作边界统一处理默认值和合法范围。
func (s *Service) Search(ctx context.Context, query string, opts Options) ([]Item, error) {
    query = strings.TrimSpace(query)
    if query == "" {
        return nil, errors.New("查询条件不能为空")
    }
    if opts.Limit == 0 {
        opts.Limit = 20
    }
    if opts.Limit  100 {
        return nil, errors.New("查询数量必须在 1 到 100 之间")
    }
    // 提前尊重取消状态，下游仓库仍须处理执行期间的取消。
    if err := ctx.Err(); err != nil {
        return nil, err
    }
    return s.repo.Find(ctx, query, opts)
}

这个设计把原来的隐式分支转成可见字段。调用者可传 Options{Limit: 50, Desc: true}，也可传零值选项使用约定默认值。归一化后的 Options 交给 Repository，仓库不再重新读取隐藏键。这里 Desc 的零值 false 有明确含义；如果要区分“未提供”和“明确选择 false”，就使用指针字段或带存在状态的专用类型，别用 Value 绕过这种建模问题。

提前检查 ctx.Err 只能挡住已经取消的调用；Find 执行期间是否能及时结束，仍取决于仓库是否将 ctx 传给支持取消的底层操作。也不要在中途改用 Background，否则会丢失上游取消与期限。调用方必须提供非 nil 的 Context。

保留请求数据：为追踪标识提供类型化入口

追踪标识与查询上限不同：它通常供多层日志关联使用，不直接定义查询结果，可以作为请求元数据保留。为这类数据提供一个小包，集中定义私有键类型、写入函数和读取函数。我倾向于存储不可变字符串，避免把一个所有协程都会修改的 map 当成请求数据传下去。

package requestmeta

import "context"

// traceKey 是私有且可比较的键类型，避免其他包复用字符串键。
type traceKey struct{}

// WithTraceID 返回派生上下文，调用者必须使用返回值。
func WithTraceID(ctx context.Context, id string) context.Context {
    return context.WithValue(ctx, traceKey{}, id)
}

// TraceID 使用类型断言和状态返回值表达缺失或无效标识。
func TraceID(ctx context.Context) (string, bool) {
    id, ok := ctx.Value(traceKey{}).(string)
    return id, ok && id != ""
}

私有键类型与 WithTraceID 构成写入约束；TraceID、bool 状态和日志字段构成读取契约。读取失败时可以省略该日志字段或采用项目规定的替代标识，但不应静默改变查询条件。若系统强制要求标识存在，应由入口明确拒绝或创建标识，不能让每个底层函数自行猜测。

调用 ctx = requestmeta.WithTraceID(ctx, id) 时需要接住返回值；该函数不会把原上下文原地改写。普通 struct{} 私有键适合这里的单一值用途。不要导出一串字符串键让不同包随意写入，也不要用不可比较的切片或 map 作为键。Context 方法可并发使用，不意味着放进去的任意对象也自动获得并发保护。

反向确认：删除隐藏选项后还有哪些分支

改完接口后，我会沿旧键名查找剩余读取点，重点关注默认上限、排序方向和绕过校验的路径。迁移可以先在入口从旧来源解析选项，再显式传给新接口；兼容处理应集中在适配层，而不是让每个仓库同时支持“参数优先，否则读 Context”。双来源长期存在会制造优先级歧义。

这里给出的是反向确认场景，不是已经执行的测试结果：相同 query 与 Options，在有无追踪标识时应保持相同的业务选项；Limit 为零应归一化为 20，负数和超过 100 应返回错误；已取消的 ctx 应在调用仓库之前返回取消错误；入口设置的 deadline 应继续传到仓库，而不因移除 Value 选项而丢失。日志关联能有差别，查询配置不应有差别。

如果移除某个 Value 后发现函数根本无法表达调用目的，这恰好说明它原来是必需输入。反过来，如果它只是跨层日志字段，就给它一个类型化访问器即可，不必把所有元数据复制到每个参数结构体。两条通道并存，关键是各自语义稳定。

收尾清单与官方资料

• 查询条件与选项能否从签名看出来，缺省含义是否清楚？
• 固定依赖是否由构造阶段注入，而不是每次从 Context 找？
• 保留的 Value 是否真正服务于跨接口的请求元数据？
• 键是否采用私有可比较类型，读取是否有类型与存在状态？
• 身份与授权的缺失分支是否明确失败，而不是扩大访问范围？
• 是否仍传递原请求上下文，避免意外切断取消和期限？

我的取舍是让 Context 承担请求控制与伴随数据，让函数参数承担操作契约。Options 不是“参数太多”的退路，而是对可配置行为的公开声明；WithValue 也不是配置容器，而是范围明确的请求元数据通道。

官方资料（复制地址查看）：Context 包文档 https://pkg.go.dev/context，其中给出了 Value 用途、键类型与并发使用约束；Go 官方文章 https://go.dev/blog/context 展示了跨接口请求数据的封装方式。本文的查询 Options 与 Service 设计是基于这些约束的原创示例，并非官方提供的业务实现。