Hertz HTTP 框架 30 天系统学习路线
这份路线面向已经能写基础 Go 代码的后端开发者。30 天的重点不是把文档逐页看完，而是每天围绕一个明确能力点做一个可运行的小成果，最后沉淀成一个具备认证、数据库、文档、测试、观测和部署能力的 Hertz API 服务。
阶段目标
Hertz 的学习主线可以按“能写接口、能组织项目、能稳定上线、能接入微服务”四步推进。
入门与核心 API
理解 Hertz 在 Go HTTP 生态中的定位，掌握路由、请求上下文、响应渲染和参数获取。
Web 服务能力
补齐绑定校验、中间件、认证、文件、静态资源、错误处理、优雅退出和单元测试。
工程化开发
用 hz 生成项目脚手架，形成 handler、biz、dal、router 分层，并接入数据库和 API 文档。
生产与微服务
接入日志、指标、链路追踪、服务发现、限流熔断、容器部署和性能压测。
每日路线
每天包含“学习主题、练习任务、当天产物”。如果时间紧，至少完成当天产物。
认识 Hertz 与开发环境
理解 Hertz 的定位：高性能、易扩展的 Go HTTP 框架，适合构建微服务入口和 Web API。
- 安装 Go、配置
GOPATH、准备一个新仓库。 - 阅读官方 Overview、Getting Started 和示例仓库目录。
- 记录 Hertz 与 Gin、Echo、net/http 的差异点。
notes/day01.md，包含环境版本、参考链接和框架对比表。Hello World 与服务启动
用最小代码启动 Hertz 服务，理解 server.Default、WithHostPorts、Spin 的职责。
- 手写
/ping接口，返回 JSON。 - 用
curl验证状态码、响应头和响应体。 - 尝试修改端口、Host、启动日志。
cmd/server/main.go 和一组 curl 命令。路由注册与路由分组
掌握 GET、POST、PUT、DELETE、Any、Group 的使用场景。
- 实现
/v1/users的列表、详情、创建、更新、删除接口。 - 练习静态路由、参数路由、通配路由的匹配优先级。
- 为
/api/v1和/api/admin建立不同路由组。
RequestContext 与请求数据
理解 app.RequestContext 如何承载请求、响应、路径参数、Query、Header、Cookie 和 Body。
- 读取
Param、Query、PostForm、GetHeader。 - 实现一个请求回显接口，返回请求方法、路径、参数和部分 Header。
- 对比
context.Context与RequestContext的边界。
/debug/echo 接口和一份上下文使用笔记。响应渲染与内容协商
掌握 JSON、PureJSON、IndentedJSON、HTML、Text、XML、Protobuf 等响应方式的适用场景。
- 为同一资源实现 JSON 与 HTML 两种返回形式。
- 统一封装成功响应结构，例如
{code,message,data}。 - 尝试自定义一个 YAML Render。
pkg/response 与 3 个示例接口。参数绑定与校验
系统练习 path、query、form、cookie、header、json 等 tag。
- 为创建用户、更新用户、搜索用户定义请求结构体。
- 练习 required、默认值、绑定优先级和错误返回。
- 接入
go-playground/validator做自定义校验。
周复盘：小型 REST API
把前 6 天内容整合成一个可运行、可测试、可演示的小型 REST API。
- 补齐 README：启动、接口列表、curl 示例。
- 统一包结构：
cmd、internal/handler、internal/model。 - 修复所有 TODO，提交 Week 1 tag。
week1-rest-api 版本，可从零启动并完成 CRUD 演示。中间件机制
理解 Hertz server-side middleware 的执行链，掌握前置逻辑、后置逻辑、Next、Abort。
- 实现请求耗时日志中间件。
- 实现管理员路由组鉴权中间件。
- 分别注册 server、group、route 级中间件并观察执行顺序。
internal/middleware 目录和执行顺序测试记录。Recovery、CORS、Request ID 与访问日志
接入常用中间件，形成 Web API 的基础防护和排障信息。
- 启用 Recovery，验证 panic 不会拖垮服务。
- 配置 CORS，允许本地前端访问。
- 生成 Request ID 并在响应头、日志中透传。
错误处理与业务错误模型
建立统一错误码、错误消息、日志字段和 HTTP 状态码映射。
- 设计
AppError，区分参数错误、鉴权错误、资源不存在、系统错误。 - 把绑定校验错误转换为稳定的响应格式。
- 写 5 个错误场景的 curl 验证用例。
pkg/apperr 与统一错误响应中间件。文件上传、下载与静态资源
练习 multipart 上传、文件下载、静态文件服务和目录安全。
- 实现单文件上传和文件列表接口。
- 限制文件大小、后缀和存储目录。
- 通过
Static或StaticFS暴露公开资源。
认证：BasicAuth、KeyAuth、JWT
学习不同认证方式的适用边界：开发调试、内部服务、用户登录态。
- 为管理后台路由接入 BasicAuth。
- 为开放 API 接入 KeyAuth。
- 实现登录接口，签发并校验 JWT。
优雅退出、Hooks 与服务生命周期
理解 Hertz 优雅退出流程，处理连接关闭、回调函数、注册中心下线和退出等待时间。
- 配置
WithExitWaitTime。 - 注册
OnShutdown回调，关闭数据库连接或 flush 日志。 - 用长耗时接口模拟退出期间的请求处理。
单元测试与接口测试
使用 Hertz 的测试工具在不经过真实网络的情况下执行请求，建立回归测试基础。
- 用
ut.PerformRequest测试路由。 - 测试正常、参数错误、鉴权失败、资源不存在。
- 加入
go test ./...到本地脚本。
hz 代码生成入门
学习 hz new、hz update 的使用方式，理解脚手架生成的目录职责。
- 安装
hz，用hz new -module生成新项目。 - 跑通生成项目的
/ping。 - 对比手写项目与 hz 项目的目录结构。
hz-demo 分支和目录结构说明。IDL：Thrift 或 Protobuf 生成 API
用 IDL 描述接口，生成 model、router、handler 框架，减少重复样板代码。
- 为用户和文章资源编写 thrift 或 protobuf IDL。
- 通过
hz update生成代码。 - 在生成 handler 中填充业务逻辑。
/users 与 /articles 接口。项目分层与依赖注入
把 handler、service、repository、model、config 分离，降低后续维护成本。
- 定义 service 接口和 repository 接口。
- 把内存存储替换为 repository 实现。
- 为 handler 注入 service，避免全局变量扩散。
数据库接入：GORM、Ent 或原生 SQL
选择一种数据访问方案，完成用户、文章、评论三个核心表的持久化。
- 配置数据库连接池和迁移脚本。
- 实现 CRUD、分页、唯一索引错误处理。
- 为 repository 写集成测试或替身测试。
配置管理与多环境启动
整理端口、数据库、JWT 密钥、日志等级、CORS 白名单等配置项。
- 支持 dev、test、prod 三套配置。
- 敏感配置通过环境变量覆盖。
- 启动时打印非敏感配置摘要，便于排障。
config 包、示例配置文件和启动说明。Hertz Client 与服务间 HTTP 调用
学习 Hertz Client 的 GET、POST、超时、重试、代理、TLS、上传和流式读取能力。
- 写一个外部用户画像服务 mock。
- 用 Hertz Client 调用 mock 服务，并设置超时。
- 实现 client-side middleware 注入 trace id。
internal/client/profile 客户端封装和失败降级逻辑。API 文档：Swagger 与契约维护
使用官方 Swagger 工具链并通过 Hertz HTTP adaptor 接入文档 UI。
- 为核心接口补充 swagger 注释。
- 生成 OpenAPI 文档并暴露
/swagger/*any。 - 把 curl 示例整理到 README。
日志体系：hlog 与第三方 Logger
建立结构化日志规范：请求 ID、用户 ID、路由、耗时、错误码、下游耗时。
- 封装业务日志方法。
- 接入 zap、logrus、zerolog 或 slog 中的一种。
- 确保中间件、handler、client 都能打印关联字段。
指标与链路追踪
接入 Prometheus 与 OpenTelemetry，观察请求量、延迟、错误率和外部调用链路。
- 暴露 metrics endpoint。
- 为 HTTP server 和 client 注入 trace。
- 搭建本地 Prometheus 或 OpenTelemetry Collector 验证。
Pprof、限流、熔断与降级
补齐线上稳定性工具：性能剖析、热点保护、下游故障隔离。
- 接入 Pprof，仅在内部或受保护环境开启。
- 选择 Sentinel 或自定义限流中间件保护写接口。
- 为外部画像服务增加熔断或快速失败策略。
安全加固
补齐常见 Web API 安全能力：TLS、Secure Headers、CSRF 场景判断、权限模型和敏感信息保护。
- 配置本地 TLS 或反向代理 TLS。
- 接入 Secure、CSRF 或 Casbin 中的相关组件。
- 审计日志中是否泄露 token、密码、密钥。
协议能力：HTTP2、SSE、WebSocket、Adaptor
了解不同实时或长连接方案的边界，重点掌握 Hertz 与 net/http 生态的 adaptor 互操作。
- 实现一个 SSE 通知流。
- 通过 adaptor 接入一个标准
http.Handler。 - WebSocket 采用官方建议的
gorilla/websocket+ Hertz adaptor 路线。
服务发现与微服务集成
把 Hertz 作为 HTTP 入口，理解它与 Kitex、注册中心、配置中心、网关的协作方式。
- 阅读 etcd、consul、nacos 等服务发现扩展文档。
- 用本地 etcd 或 mock resolver 完成服务发现演示。
- 设计 Hertz + Kitex 的 API Gateway 调用链。
容器化、部署与运行参数
整理 Dockerfile、健康检查、启动参数、资源限制和发布流程。
- 编写多阶段 Dockerfile。
- 增加
/healthz、/readyz。 - 用 Docker Compose 启动 API、数据库、观测组件。
性能压测与问题定位
围绕真实接口进行压测，观察路由、中间件、数据库、下游 HTTP 调用对延迟的影响。
- 用 wrk、hey 或 vegeta 对读写接口压测。
- 记录 QPS、平均延迟、P95、P99、错误率。
- 结合日志、metrics、pprof 找一个瓶颈并优化。
终局项目评审与知识体系沉淀
把 30 天项目整理成能展示、能复用、能继续迭代的后端模板。
- 补齐 README、架构图、部署说明、接口文档、测试说明。
- 整理“我会怎么用 Hertz 做新项目”的决策手册。
- 列出后续深入方向：框架扩展、网络库、微服务治理、贡献源码。
最终项目建议
不要只写零散 demo，建议用一个贴近业务的项目贯穿 30 天。
项目题目：内容管理与开放 API 平台
实现一个文章/笔记管理系统，包含用户登录、文章 CRUD、标签、评论、文件上传、开放 API Token、Swagger 文档、Prometheus 指标、OpenTelemetry 链路和 Docker Compose 部署。
检查清单
学完后，用这份清单判断自己是否真的具备 Hertz 项目落地能力。
编码能力
- 能独立创建 Hertz 服务并组织路由组。
- 能正确使用
RequestContext读写请求响应。 - 能完成绑定、校验、统一错误处理和响应封装。
- 能写 server-side 与 client-side middleware。
工程能力
- 能使用
hz和 IDL 生成并维护项目。 - 能接入数据库、配置、日志和 API 文档。
- 能写 handler、service、repository 层测试。
- 能容器化部署并通过健康检查暴露运行状态。
稳定性能力
- 能配置超时、重试、优雅退出和限流。
- 能通过 metrics、tracing、pprof 定位性能问题。
- 能为认证、CORS、TLS、敏感日志制定安全策略。
- 能用压测报告说明优化收益。
微服务能力
- 理解 Hertz Client、服务发现和注册中心扩展。
- 能把 Hertz 作为 HTTP 网关与 Kitex 服务协作。
- 能通过 adaptor 复用
net/http生态组件。 - 知道 HTTP2、SSE、WebSocket 的适用边界。
参考资料
建议按当天主题查阅对应文档，避免一开始陷入全量阅读。
资料核对时间：2026-06-21。Hertz 生态变化较快，第三方中间件和迁移建议以官方文档当前版本为准。