先明确接口粒度再选框架：gin绑定稳定、生态成熟，echo泛型早但插件少；路由应按意图分组（如/posts读取、/admin/posts管理），避免职责混杂；中间件顺序、结构体校验、GORM关联查询优化、文件上传流式处理及环境变量排查是关键实践。
用 gin 还是 echo 搭 API 路由？别纠结框架，先想清接口粒度
选框架不是为了炫技，而是让路由定义、中间件注入、错误统一处理不反人类。实际写博客后端时，gin 更常见，因为它的 c.ShouldBindJSON() 对结构体绑定更稳，echo 在泛型支持上稍早但生态插件少些。
真实踩坑点：很多人一上来就套「RESTful」模板，把文章列表写成 GET /api/v1/posts，结果分页、标签筛选、草稿过滤全塞 query 参数里，后期加权限或缓存策略时路由逻辑开始发散。
- 建议按操作意图分组：内容读取走
/posts，管理动作走/admin/posts，避免一个路由承担查询 + 修改 + 权限校验三重职责 -
gin的Use()中间件顺序很关键：鉴权中间件必须在绑定参数之后、业务 handler 之前；否则c.ShouldBindJSON()可能 panic - 别在路由层做字段校验（比如判断 title 长度），放到 binding struct 的 tag 里，用
binding:"required,min=1,max=100"
gorm 关联查询怎么不 N+1？别依赖 Preload 就完事
博客系统里最典型的是查文章列表时顺带加载作者名、分类名、标签列表。用 Preload("Author") 看似解决，但一旦加上 Preload("Tags")，GORM 默认会发 3 条 SQL（主表 + author 表 + tags 表 JOIN），而 tags 是多对多，实际生成的 SQL 可能因数据量大拖慢整个接口。
真正可控的方式是手动 JOIN + Scan 到自定义 struct，尤其当只需要作者昵称、标签名这类字段时：
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
db.Table("posts").
Select("posts.*, users.nickname as author_name, GROUP_CONCAT(tags.name) as tag_names").
Joins("left join users on users.id = posts.author_id").
Joins("left join post_tags on post_tags.post_id = posts.id").
Joins("left join tags on tags.id = post_tags.tag_id").
Group("posts.id").Scan(&results)
-
Preload适合深度嵌套且字段全要的场景；简单展平字段，JOIN + Scan 性能更稳、SQL 可控 - 注意
GROUP_CONCAT在 MySQL 里默认长度 1024，长标签列表会被截断，需提前设SET SESSION group_concat_max_len = 10000 - SQLite 不支持
GROUP_CONCAT的分隔符语法，如果要兼容，得换用json_group_array或改用应用层聚合
上传封面图用 multipart/form-data，但别在内存里解包大文件
用户上传一张 5MB 的封面图，如果直接用 c.FormFile("cover") 拿到 *multipart.FileHeader 后立刻 Open()，再 io.Copy 到磁盘——这过程整个文件都进 Go 的堆内存，GC 压力陡增，QPS 上不去。
正确做法是流式处理：拿到 FileHeader 后立即 Open()，然后边读边写，不缓存全文本。
- 务必检查
header.Size是否超限（比如 >10MB），在Open()前就返回 413，避免打开恶意大文件 - 别用
ioutil.ReadAll()或bytes.Buffer接收上传流，这是最常被抄错的示例代码 - 保存路径别拼接用户传的原始文件名：
filepath.Join(uploadDir, header.Filename)有路径遍历风险；应生成 UUID 文件名，后缀从header.Header.Get("Content-Type")提取
部署时 os.Getenv("DB_URL") 为空？环境变量没生效的三个硬核排查点
本地跑得好好的，扔到 Docker 或 systemd 里就报 failed to connect: dial tcp: lookup db on 127.0.0.11:53: no such host——这不是 DNS 问题，是环境变量压根没透进去。
- Docker run 时漏了
-e DB_URL=...，或者 compose 文件里写成了environment:下的 key-value，但没加引号导致 YAML 解析失败（如DB_URL: postgres://user:pass@db:5432/blog中的:会让 YAML 当成 map 键） - systemd service 文件里用了
EnvironmentFile，但文件路径写错，或文件内用了#注释却没换行，导致后续变量全失效 - Go 二进制本身没加
CGO_ENABLED=0编译，运行时动态链接 libc 失败，连os.Getenv都可能静默返回空（尤其 Alpine 镜像）
复杂点在于：这些配置问题不会报错，只会让 gorm.Open() 返回 generic “connection refused”，你得从日志第一行开始确认 fmt.Println("DB_URL:", os.Getenv("DB_URL")) 是否真输出了值——别信文档，自己打一行。
