99 lines
8.6 KiB
Markdown
99 lines
8.6 KiB
Markdown
---
|
||
tags: [后端, Go, Gin, 索引]
|
||
create time: 2026-04-27 00:00
|
||
---
|
||
|
||
# Gin 框架学习笔记
|
||
|
||
## 概述
|
||
|
||
本文件夹为 Go 语言 Gin 框架的系统学习笔记。`[[Go 后端基础]]` 已涵盖 Gin 的快速上手（路由分组、中间件、参数绑定、错误处理），本笔记群在此基础上**深入和拓展**，聚焦 Gin 框架特有的机制和工程实践。
|
||
|
||
本索引以 [Gin 官方文档](https://gin-gonic.com/zh-cn/docs/) 目录为骨架，结合教学逻辑重新组织——**不是逐条翻译官网，而是把相关联的知识点合并成体系化的笔记**。
|
||
|
||
## 笔记索引
|
||
|
||
### 一、核心机制（必读）
|
||
|
||
> 这些笔记帮你理解 Gin 的底层工作原理，是读懂源码和排查问题的基础。
|
||
|
||
| 序号 | 笔记 | 官网对照 | 内容概要 |
|
||
| --- | ------------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 1 | [[1-gin-architecture]] | 介绍 + 快速开始 | 整体架构：Engine、RouterGroup、Context 的关系；请求生命周期全链路（Mermaid 时序图）；Gin 如何桥接 `net/http` |
|
||
| 2 | [[2-routing]] | 路由 + 路由分组 + 重定向 | 路由匹配算法（Radix Tree 基数树）；静态/动态/通配符路由的优先级；路由分组与前缀累加原理；重定向 `c.Redirect` |
|
||
| 3 | [[3-middleware]] | 使用中间件 + 自定义中间件 + 中间件中的 Goroutine + 安全头 | 中间件链执行顺序（全局 → 分组 → 路由）；`gin.HandlerFunc` 的本质；常用中间件实现模板（CORS、限流、鉴权、RequestID、安全头）；中间件中启动 Goroutine 的陷阱与 `c.Copy()` 用法 |
|
||
| 4 | [[4-context-lifecycle]] | 上下文与取消 | `*gin.Context` 底层设计：keys/values map、Request/RW 包装；`c.Set/Get/GetString`；`c.Copy()` 的深拷贝边界；请求级 `context` 传播与取消 |
|
||
| 5 | [[5-binding-validation]] | 模型绑定和验证 + 自定义验证器 + 绑定查询字符串 + 绑定自定义反序列化器 + 绑定请求头 + 绑定 URI + 绑定 HTML 复选框 | `ShouldBind` 全家桶（JSON、form、query、header、uri）；`binding` 标签内置规则速查；自定义 Validator（`.RegisterValidation`）；自定义反序列化器（`bind.DeferredBinder`）；数组集合格式（`UserIds[]`） |
|
||
|
||
|
||
### 二、进阶功能
|
||
|
||
> 这些是日常开发中高频使用、但容易踩坑的场景。
|
||
|
||
| 序号 | 笔记 | 官网对照 | 内容概要 |
|
||
|------|------|----------|----------|
|
||
| 6 | [[6-error-handling]] | 错误处理中间件 | `c.Error` → `c.Errors` 链式错误收集；全局错误处理器 `gin.Recovery` 定制；HTTP 状态码与业务码的映射；统一错误响应中间件 |
|
||
| 7 | [[7-binding-advanced]] | Multipart/Urlencoded 表单 + Map 作为参数 + 绑定查询字符串或 POST 数据 + 表单默认值 + 使用自定义结构体标签绑定 + 将请求体绑定到不同的结构体 + 数据绑定 | 表单绑定深入：`c.ShouldBind()` 的多内容类型自动检测；Map 绑定（`binding:"-"` 跳过字段）；查询参数与 POST body 混合绑定；字段默认值策略；按条件绑定不同结构体（`ShouldBindBodyWith`） |
|
||
| 8 | [[8-file-upload]] | 文件上传（单文件/多文件/限制大小） | `c.ShouldBindFiles`；单文件/多文件上传流程；`MaxMultipartMemory` 内存限制；文件类型/大小校验；分片上传思路 |
|
||
| 9 | [[9-response-rendering]] | XML/JSON/YAML/ProtoBuf 渲染 + SecureJSON + JSONP + AsciiJSON + 渲染 + PureJSON | 渲染全家桶：`c.JSON`、`c.XML`、`c.YAML`、`c.ProtoBuf`；`SecureJSON`（防 JSON 劫持）；`PureJSON`（保留原始 Unicode）；`AsciiJSON`（中文转 Unicode）；`JSONP` |
|
||
| 10 | [[10-template-rendering]] | HTML 渲染 + 多模板 + 将模板构建到单一二进制中 | `c.HTML` / `LoadHTMLGlob` / `LoadHTMLFiles`；多模板（`Template.FuncMap`）；`embed.FS` 将模板打包进二进制 |
|
||
| 11 | [[11-static-files]] | 提供静态文件 + 从文件提供数据 + 从 Reader 提供数据 | `Static` / `StaticFS` / `StaticFile`；自定义文件服务器；`io.Reader` 直接返回文件流 |
|
||
|
||
### 三、服务器与部署
|
||
|
||
> 涉及 Gin 服务器的配置、运行方式和部署策略。
|
||
|
||
| 序号 | 笔记 | 官网对照 | 内容概要 |
|
||
|------|------|----------|----------|
|
||
| 12 | [[12-server-config]] | 自定义 HTTP 配置 + 服务器配置 + 支持 Let's Encrypt + Cookie + 可信代理 | `gin.New()` 自定义 Engine；`http.Server` 高级配置（超时、KeepAlive）；TLS/Let's Encrypt；Cookie 操作（`c.SetCookie` / `c.GetCookie`）；可信代理链（X-Forwarded-For） |
|
||
| 13 | [[13-graceful-shutdown]] | 优雅重启或停止 | `server.Shutdown()` + 信号监听（SIGINT/SIGTERM）；等待请求处理完毕再退出；优雅重启（fork + exec）思路 |
|
||
| 14 | [[14-logging]] | 如何写入日志文件 + 自定义日志格式 + 跳过日志记录 + 控制输出着色 + 避免记录查询字符串 + 定义路由日志格式 + 日志 + 结构化日志 | 日志器替换（`gin.DefaultWriter`）；自定义日志格式；结构化日志（zap/logr 接入）；跳过特定路径日志；路由日志格式定制 |
|
||
| 15 | [[15-advanced-running]] | 运行多个服务 + HTTP/2 服务器推送 | 单进程多监听端口；gRPC + HTTP 共存；HTTP/2 push 场景 |
|
||
|
||
### 四、工程实践
|
||
|
||
> 把 Gin 用到生产级别的实践。
|
||
|
||
| 序号 | 笔记 | 官网对照 | 内容概要 |
|
||
|------|------|----------|----------|
|
||
| 16 | `project-structure.md` | 依赖注入模式 | 标准项目目录结构（cmd/internal/handler/service/model/repository）；模块化路由注册；依赖注入模式（手动 vs 依赖注入容器） |
|
||
| 17 | `testing.md` | 测试 | `httptest` + `github.com/gin-gonic/gin/test`；Mock `*gin.Context`；中间件单独测试；基准测试（`Benchmark`） |
|
||
| 18 | `observability.md` | 健康检查 + 指标与监控 | `/health`、`/ready`、`/metrics` 端点；Prometheus 指标接入；链路追踪（OpenTelemetry） |
|
||
| 19 | `websocket.md` | WebSocket 支持 | Gin + gorilla/websocket 集成；Upgrade 握手；读写超时控制；广播推送 |
|
||
| 20 | `session-auth.md` | 会话管理 | Cookie Session 实现；JWT 认证中间件；RBAC 权限控制中间件 |
|
||
| 21 | `grpc-gateway.md` | — | Gin 作为 gRPC 服务的 HTTP 网关（gRPC-Gateway 原理） |
|
||
|
||
### 五、构建与优化
|
||
|
||
| 序号 | 笔记 | 官网对照 | 内容概要 |
|
||
|------|------|----------|----------|
|
||
| 22 | `build-and-perf.md` | 使用 JSON 替换构建 + 不使用 MsgPack 构建 + 构建标签 + 基准测试 | 构建标签（`// +build`）；替换 JSON 编码器（json-iterator）；禁用 MsgPack；基准测试编写与解读 |
|
||
|
||
## 已创建笔记
|
||
|
||
> 快速跳转链接：`[[1-gin-architecture]]` · `[[2-routing]]` · `[[3-middleware]]` · `[[4-context-lifecycle]]` · `[[5-binding-validation]]` · `[[6-error-handling]]` · `[[7-binding-advanced]]` · `[[8-file-upload]]` · `[[9-response-rendering]]` · `[[10-template-rendering]]` · `[[11-static-files]]` · `[[12-server-config]]` · `[[13-graceful-shutdown]]` · `[[14-logging]]` · `[[15-advanced-running]]`
|
||
|
||
---
|
||
|
||
- `[[Go 后端基础]]` — Gin 快速上手，已涵盖基础用法
|
||
- `[[HTTP 协议]]` — HTTP 协议基础
|
||
- `[[API 设计]]` — API 设计规范与错误码体系
|
||
- `[[数据库基础]]` — Go 操作数据库
|
||
- `[[部署与运维基础]]` — Go 应用部署
|
||
|
||
## 学习路线建议
|
||
|
||
```
|
||
快速上手 (Go 后端基础)
|
||
↓
|
||
核心机制 (序号1-5) ← 读懂源码、排查问题的关键
|
||
↓
|
||
工程实践 (序号16-21) ← 项目实战必备
|
||
↓
|
||
进阶功能 (序号6-15) ← 按需深入
|
||
↓
|
||
构建与优化 (序号22) ← 性能调优阶段
|
||
```
|
||
|
||
共 **22 篇笔记**，已创建 16 篇（核心机制 + 进阶功能 + 服务器与部署），6 篇待完成（工程实践 #16-21、构建与优化 #22）。
|