我会尽量写小问题，不写大而空的架构口号。比如 Gin 中间件顺序为什么会影响日志完整性，GoFrame 的配置为什么要从启动阶段就固定，Redis 缓存空值为什么比简单删除更可靠。

技术栈会围绕 Go、Gin、GoFrame、MySQL、Redis 和 Linux 部署展开。文章不是教程合集，更像工作笔记：每一篇都回答一个实际问题，并说明我为什么这么处理。

如果一段代码只是能跑，我不会把它当成结论；只有它在可维护性、排障和团队协作上站得住，才会留下来。

cmd 适合放入口，入口只做配置加载、依赖组装和启动服务；internal 适合放业务不可被外部复用的代码；pkg 只有在确实要给别的项目 import 时才值得出现。

cmd/api/main.go
internal/order/service.go
internal/order/repository.go
internal/platform/mysql.go

如果一个函数只被当前业务调用，先放在 internal。过早放进 pkg 会暗示它是稳定 API，后面每次改签名都要考虑外部依赖。

小项目可以先保持三层以内：入口、业务、基础设施。等边界真的变清楚，再拆包，成本更低。

我通常遵守两个规则：第一，跨 API 边界且和请求生命周期绑定的值可以放；第二，业务核心参数必须显式出现在函数签名里。

ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
defer cancel()

order, err := svc.Create(ctx, userID, req.Items)

超时要在入口附近设置，因为只有入口知道 SLA。仓储层可以尊重 ctx，但不应该偷偷创建更长的超时。

这样做的好处是排障简单：请求取消、数据库超时、下游慢查询都会沿着同一个 ctx 传播，不会出现后台 goroutine 继续跑的隐患。

errgroup.WithContext 的价值在于把错误和取消绑定起来。一个任务返回错误后，派生 ctx 会取消，其他任务可以尽快退出。

g, ctx := errgroup.WithContext(ctx)
for _, id := range ids {
    id := id
    g.Go(func() error {
        return syncOne(ctx, id)
    })
}
if err := g.Wait(); err != nil {
    return err
}

如果任务数量可能很大，要加并发限制。Go 新版本的 errgroup 支持 SetLimit，比手写信号量更清楚。

我的判断标准是：只要 goroutine 的生命周期超过当前函数，就必须能说清楚谁取消它、谁等待它、错误去哪了。

但在极高频循环里，defer 可能带来额外开销，也可能把释放时机拖到函数结束。比如批量处理每一行数据时，把 defer 放在循环内部就需要小心。

for rows.Next() {
    if err := handleRow(); err != nil {
        return err
    }
}
return rows.Close()

我的默认策略是：普通业务代码优先可读性，热路径在压测或 pprof 证明有问题后再改。不要凭印象优化，也不要把所有 defer 都手动展开。

工程里真正危险的不是 defer 慢，而是资源释放路径不一致。性能问题可以量化，泄漏问题往往上线后才暴露。

我常用的顺序是：request id、访问日志、recover、CORS、限流、鉴权、业务路由。最外层先建立追踪信息，recover 要在业务之前，日志要能拿到最终状态码和耗时。

r.Use(RequestID())
r.Use(AccessLog())
r.Use(gin.Recovery())
r.Use(RateLimit())
api := r.Group("/api", Auth())

限流放鉴权前还是后，要看目标。如果要保护登录接口和匿名流量，放前面；如果按用户额度限流，放鉴权后。

不要把业务判断塞进全局中间件。中间件越靠外，影响面越大，越应该只处理横切能力。

type CreateUserReq struct {
    Name string `json:"name" binding:"required,min=2"`
    Age  int    `json:"age" binding:"gte=1,lte=120"`
}

我的做法是在入口层统一处理校验错误，把 validator.ValidationErrors 转成固定结构，例如 {field, message}。这样前端可以稳定展示，也方便测试。

校验只负责“格式正确”，不要负责“业务存在”。例如手机号格式可以在 binding 做，手机号是否已注册应该交给 service。

分清格式校验和业务校验，接口层会薄很多，错误响应也更一致。

api := r.Group("/api/v1")
admin := r.Group("/admin/api", AdminAuth())
callback := r.Group("/callbacks", VerifySignature())

版本号建议放在对外 API 上，不一定放在后台管理接口上。后台接口通常和前端一起发布，兼容压力没那么大；开放 API 则要给调用方迁移时间。

同一个 handler 不要同时服务前台和后台。看起来复用，实际上权限、字段、审计要求都不一样。

当路由能一眼看出调用方是谁，后续加限流、审计和灰度都会轻松很多。

入口层要限制 body 大小，业务层要重新生成文件名，存储层只接受已经确认过的对象 key。原始文件名可以当展示字段保存，但不应该参与真实路径。

r.MaxMultipartMemory = 8 << 20
file, err := c.FormFile("file")
key := uuid.NewString() + filepath.Ext(file.Filename)

还要校验 content type 和扩展名，但不要只信任浏览器传来的 header。重要文件最好做魔数识别，图片类文件可以解码一次确认格式。

上传接口的目标不是“能收到文件”，而是保证收到的文件不会污染路径、压垮内存或绕过业务规则。

我更倾向于 handler 显式处理业务错误，panic 只留给真正不可恢复的问题。统一响应可以通过小函数完成，不需要牺牲控制流。

if err != nil {
    response.Error(c, err)
    return
}
response.OK(c, data)

错误类型可以带 code、message 和 cause。对外返回稳定文案，对内日志保留原始错误，这样既不泄露细节，也不影响排障。

统一响应的价值是降低接口差异，不是隐藏所有错误路径。清楚地 return，通常比“抛出去让外层猜”更适合业务系统。