sxh / engineering-map

切换主题

Gin 从入门到精通：完整教程目录 ​

教程定位：本教程面向有 Go 语言基础、HTTP 零基础的读者，从 Web 框架概念讲起，逐步深入到路由系统、参数绑定、中间件机制、JWT 认证、企业级部署等高级主题。每章配有可运行的 Go 代码、curl 测试命令、常见错误分析、练习题，帮助你在实战中掌握 Gin v1.9+。

阅读指南 ​

本教程共 32 章 + 3 个附录，按 8 个阶段组织：

阶段章节范围核心目标建议学习时间
Phase 1第01-04章环境搭建 + 第一个Gin程序 + HTTP基础1-2天
Phase 2第05-09章路由系统与请求处理3-4天
Phase 3第10-13章参数绑定、验证与响应3-4天
Phase 4第14-18章中间件完全掌握3-5天
Phase 5第19-22章视图渲染、文件处理与会话2-3天
Phase 6第23-27章高级特性与企业级实践3-5天
Phase 7第28-31章三合一实战项目4-6天
Phase 8第32章总复习 + 面试宝典1-2天

学习建议 ​

  1. 按顺序学习：Gin 知识有很强的依赖关系，没学会路由就学中间件会一头雾水
  2. 必须手敲代码：每个 Go 代码示例都要自己跑一遍，用 curl 或 Postman 验证
  3. 每个 API 都要测试：教程里每段代码都附了 curl 命令，照敲照测
  4. 理解 HTTP 比记住 Gin API 更重要：Gin 只是 HTTP 的 Go 语言表达，理解 HTTP 原理才能举一反三
  5. 练习必须做：每章末尾的练习题是巩固知识的关键
  6. 遇到错误先看日志：Gin 的错误信息通常很直白，学会读日志

Phase 1：环境搭建与快速入门 ​

第 01 章：Gin 框架概述与安装 ​

  • 什么是 Web 框架，为什么要用框架
  • Go 生态中的 Web 框架对比（Gin / Echo / Fiber / net/http）
  • Gin 核心特点（高性能、轻量、中间件、路由树）
  • 安装 Gin
  • 第一个 Gin 程序：5 行代码跑通 HTTP 服务
  • gin.Default() vs gin.New()
  • 程序结构逐行解析

第 02 章：HTTP 基础速成（为 Gin 学习准备） ​

  • HTTP 请求-响应模型（图解）
  • HTTP 方法：GET/POST/PUT/PATCH/DELETE
  • HTTP 状态码：2xx/3xx/4xx/5xx 分类记忆
  • URL 结构：协议、主机、端口、路径、查询参数
  • Content-Type 详解（application/json、form、multipart）
  • RESTful API 设计原则速览
  • 用浏览器 DevTools 和 curl 观察 HTTP 请求

第 03 章：路由基础 —— GET/POST/PUT/DELETE ​

  • gin.Default() 返回的 *gin.Engine
  • 注册路由：GET/POST/PUT/DELETE/PATCH
  • 处理函数签名：func(c *gin.Context)
  • gin.Context 是什么
  • 返回字符串：c.String()
  • 返回 JSON：c.JSON()
  • r.Run() 启动服务
  • 用 curl/Postman 测试每个 API
  • 路由方法对应 SQL 的 CRUD

第 04 章：路由分组与路由组织 ​

  • r.Group("/api") 路由分组
  • 嵌套分组：/api/v1/users
  • 分组上应用中间件
  • 多路由文件拆分
  • 推荐的目录结构
  • 路由命名规范与 RESTful 最佳实践

Phase 2：路由系统与请求处理 ​

第 05 章：路径参数与查询参数 ​

  • 路径参数：/users/:id → c.Param("id")
  • 查询参数：?name=张三 → c.Query("name")
  • c.DefaultQuery() 默认值
  • 路径参数 vs 查询参数选择原则
  • 获取所有查询参数
  • 数组参数：?ids=1&ids=2&ids=3

第 06 章：表单参数与 Body 读取 ​

  • c.PostForm("name") 获取表单参数
  • 获取原始请求体：c.GetRawData()
  • Content-Type 与参数读取的关系
  • 三个常见 Content-Type 的区别
  • 为什么 PostForm 不能读 JSON Body

第 07 章：请求头与客户端信息 ​

  • 读取请求头：c.GetHeader() / c.Request.Header
  • 常用请求头：Content-Type、Authorization、User-Agent、Cookie
  • 获取客户端 IP：c.ClientIP()
  • 设置响应头：c.Header()

第 08 章：路由进阶 —— 匹配规则与路由树 ​

  • Gin 路由底层：Radix Tree（基数树）
  • 路由匹配优先级（静态 > 参数 > 通配）
  • r.NoRoute() 处理 404
  • r.NoMethod() 处理 405
  • r.Routes() 查看所有路由
  • Gin 为什么快

第 09 章：重定向与路由跳转 ​

  • HTTP 重定向：c.Redirect(code, url)
  • 301 vs 302 的区别与场景
  • 路由内部跳转：r.HandleContext(c)
  • 常见重定向场景

Phase 3：参数绑定、验证与响应 ​

第 10 章：参数绑定 —— ShouldBind 系列 ​

  • c.ShouldBindJSON(&obj) 绑定 JSON Body
  • c.ShouldBindQuery(&obj) 绑定查询参数
  • c.ShouldBindUri(&obj) 绑定路径参数
  • c.ShouldBind(&obj) 自动选择绑定方式
  • 结构体标签：json、form、uri、header
  • ShouldBind vs MustBind 的区别

第 11 章：参数验证 —— Validator ​

  • Gin 内置 validator 引擎
  • 基础验证标签（required/min/max/len）
  • 字符串验证（email/url/contains）
  • 数字验证（gt/gte/lt/lte）
  • 跨字段验证（eqfield）
  • 自定义验证器
  • 中文错误信息翻译

第 12 章：响应渲染 —— JSON/XML/YAML/String/HTML ​

  • c.JSON() / c.XML() / c.YAML() / c.String()
  • c.IndentedJSON() 美化 JSON
  • c.PureJSON() / c.SecureJSON()
  • c.Data() / c.Stream() 流式响应
  • 何时用哪种响应格式

第 13 章：统一响应格式与错误处理 ​

  • 设计统一响应结构 {code, message, data}
  • 封装响应工具函数
  • HTTP 状态码 vs 业务状态码
  • 错误码设计规范
  • c.Error() / c.Errors / c.Abort() 系列

Phase 4：中间件完全掌握 ​

第 14 章：中间件概念与执行流程 ​

  • 什么是中间件（洋葱模型图解）
  • Gin 请求处理完整流程
  • c.Next() 的含义（传递控制权）
  • c.Abort() 的含义（中止后续）
  • 中间件签名：func(c *gin.Context)
  • 中间件链的执行顺序

第 15 章：Gin 内置中间件 ​

  • gin.Logger() 请求日志中间件
  • gin.Recovery() Panic 恢复中间件
  • gin.BasicAuth() 基本认证
  • gin.Default() 自动包含 Logger + Recovery

第 16 章：自定义中间件 ​

  • 编写第一个自定义中间件（请求耗时）
  • c.Set() / c.Get() 传递上下文值
  • 全局/路由级/分组级中间件
  • 中间件执行顺序控制
  • 实战：TraceID 中间件

第 17 章：跨域 CORS 中间件 ​

  • 什么是跨域（同源策略）
  • 手动编写 CORS 中间件
  • gin-contrib/cors 库使用
  • 预检请求（OPTIONS）处理
  • 生产环境 CORS 最佳实践

第 18 章：限流、压缩与其他中间件 ​

  • 限流中间件（令牌桶算法）
  • Gzip 压缩中间件
  • 安全头中间件
  • 请求大小限制
  • 生产环境中间件推荐组合

Phase 5：视图渲染、文件处理与会话 ​

第 19 章：HTML 模板渲染 ​

  • r.LoadHTMLGlob() 加载模板
  • Go template 语法速成（{{.}}、{{range}}、{{if}}）
  • c.HTML() 渲染模板
  • 模板嵌套与布局
  • 自定义模板函数

第 20 章：静态文件与文件上传 ​

  • r.Static() 提供静态文件
  • 单文件上传：c.FormFile() + c.SaveUploadedFile()
  • 多文件上传：c.MultipartForm()
  • 文件大小限制
  • 文件类型验证
  • c.File() / c.FileAttachment() 文件下载
  • Cookie：c.SetCookie() / c.Cookie()
  • Cookie 属性详解（HttpOnly、Secure、SameSite）
  • Session：gin-contrib/sessions 库
  • Cookie vs Session 选择指南

第 22 章：文件服务与附件处理 ​

  • 文件下载接口
  • 断点续传思路
  • 大文件分片上传思路
  • 文件预览 vs 文件下载

Phase 6：高级特性与企业级实践 ​

第 23 章：JWT 认证 ​

  • JWT 原理（Header.Payload.Signature）
  • golang-jwt/jwt 库使用
  • 生成/解析 Token
  • JWT 中间件封装
  • Access Token + Refresh Token 双 Token 模式

第 24 章：日志系统 ​

  • Gin 内置日志与自定义格式
  • 日志写入文件
  • 集成 Zap/Logrus
  • TraceID 传递
  • 结构化日志

第 25 章：Swagger API 文档 ​

  • Swagger/OpenAPI 概念
  • swaggo/swag 安装配置
  • API 注释规范
  • swag init 生成文档
  • 在线 API 文档测试

第 26 章：高性能与优雅关闭 ​

  • Gin 为什么快（Radix Tree + httprouter）
  • http.Server 优雅关闭
  • 信号监听 signal.Notify
  • 超时控制配置
  • 性能优化建议

第 27 章：测试 ​

  • net/http/httptest 标准库
  • 测试 GET/POST/PUT/DELETE 接口
  • 测试中间件
  • 表驱动测试
  • Mock 依赖

Phase 7：实战项目 ​

第 28 章：实战项目一 —— RESTful API 用户管理系统 ​

  • 项目初始化 + 目录结构
  • User 模型（GORM 集成）
  • 路由设计（RESTful 规范）
  • 用户注册（参数验证 + 密码加密）
  • 用户登录（JWT 生成）
  • 用户列表（分页 + 搜索）
  • JWT 认证中间件
  • 统一错误处理
  • 完整可运行代码

第 29 章：实战项目二 —— 博客 API 系统 ​

  • 需求分析与路由设计
  • 文章 CRUD
  • 标签系统（多对多）
  • 评论系统
  • 搜索 + 分页 + 排序
  • 阅读量统计
  • Swagger 文档生成

第 30 章：实战项目三 —— 文件分享服务 ​

  • 用户注册/登录（JWT）
  • 文件上传（单/多文件）
  • 文件分享链接生成
  • 文件下载（过期控制）
  • 限流与权限控制
  • CORS 配置

第 31 章：部署与运维 ​

  • 配置管理（Viper）
  • 优雅关闭
  • Docker 容器化
  • Nginx 反向代理
  • 健康检查
  • 性能压测

Phase 8：总结与面试 ​

第 32 章：Gin 面试宝典与总复习 ​

  • Gin 知识体系回顾
  • 高频面试题 30 题
  • 面试场景题
  • Gin vs Echo vs Fiber 选型指南
  • 进阶学习路线

附录 ​

附录 A：Gin 常用 API 速查表 ​

附录 B：常见错误排查指南 ​

附录 C：项目环境搭建 FAQ ​

最后提醒：Web 开发技能不是"看"出来的，是"敲"出来的。请务必跟着教程敲每一行代码，用 curl 测试每一个接口，遇到错误不要慌。祝你学有所成！

把零散知识，整理成可以反复走的路。

© sxh313 · Engineering Map