Hertz RequestContext API速查手册：请求与响应处理的终极参考-平芜编程栈

Hertz RequestContext API速查手册：请求与响应处理的终极参考

【免费下载链接】hertzGo 微服务 HTTP 框架，具有高易用性、高性能、高扩展性等特点。项目地址: https://gitcode.com/CloudWeGo/hertz

Hertz 是一款高易用、高性能的 Go 微服务 HTTP 框架，而RequestContext正是 Hertz 中处理请求与响应的核心上下文对象：读取 Query/POST 参数、数据绑定、渲染 JSON 响应、控制中间件流程……所有操作都围绕它展开。本篇速查手册按使用场景把最常用的 RequestContext API 归类整理，帮你一查就会、写码不卡。

📌 一文读懂 RequestContext 是什么

每收到一个 HTTP 请求，Hertz 就会为其构造一个RequestContext，它把一次请求的所有信息打包在一起（定义见 pkg/app/context.go）：

核心字段	作用
`Request`/`Response`	原始请求与响应对象（pkg/protocol/）
`Params`	路由参数，如`/user/:id`中的`id`
`Handlers`链 +`index`	当前中间件执行链与位置，支撑`Next`/`Abort`
`Keys`	请求级键值对，供中间件与 Handler 间传递数据
`Errors`	累积的`ErrorChain`错误链

Handler 的统一签名长这样（完整示例见 examples/standard/main.go）：

h.GET("/ping", func(c context.Context, ctx *app.RequestContext) { ctx.JSON(consts.StatusOK, utils.H{"ping": "pong"}) })

掌握ctx上的一二三十几个方法，就能覆盖 90% 的日常开发。下面按"读请求 → 写响应 → 控流程"的顺序速查。

📥 请求处理：把参数读进来

1. 读取 Query / POST 参数 / 路由参数

这是最高频的一组方法（源码位置 pkg/app/context.go#L1336-L1434）：

方法	用途	小提醒
`ctx.Query(key)`	取 URL Query 值	不存在返回`""`
`ctx.DefaultQuery(key, def)`	Query 带默认值	不存在返回`def`
`ctx.GetQuery(key)`	Query 值 + 是否存在	可区分"空串"与"未传"
`ctx.PostForm(key)`	取 POST 表单值	自动兼容 multipart
`ctx.GetPostForm(key)`	POST 值 + 是否存在	同上
`ctx.Param(key)`	取路由参数	`/user/:id`→`ctx.Param("id")`
`ctx.QueryArgs()`/`ctx.PostArgs()`	批量遍历参数	适合日志打印、透传
`ctx.FormValue(key)`	一站式取值	依次查 Query → POST → Multipart

💡 经验法则：GET 请求用Query，POST 表单用PostForm，URL 里的:name用Param，懒得区分时直接上FormValue。

2. 读取请求体 Body

方法	用途
`ctx.GetRawData()`	直接拿`[]byte`原始 body
`ctx.Body()`	拿 body，可能因流式读取报错
`ctx.RequestBodyStream()`	以`io.Reader`流式消费大文件

大多数 JSON / Protobuf 接口不需要手动读 body，交给下一节的绑定 API 更省心。

3. 数据绑定：Bind 系列一步到位 ⭐

Hertz 的 pkg/app/server/binding/ 提供了强大的绑定器，可以把 Query、Header、路由参数、Form、JSON、Protobuf 一键映射到结构体（pkg/app/context.go#L1463-L1537）：

方法	绑定来源
`ctx.Bind(obj)`	综合绑定（Query/POST/路由参数，按 tag）
`ctx.BindAndValidate(obj)`	绑定 + 按`vd`tag 校验参数
`ctx.BindQuery(obj)`	仅绑定 Query（`query`tag）
`ctx.BindHeader(obj)`	仅绑定 Header（`header`tag）
`ctx.BindPath(obj)`	仅绑定路由参数（`path`tag）
`ctx.BindForm(obj)`	仅绑定 Form（`form`tag）
`ctx.BindJSON(obj)`/`ctx.BindProtobuf(obj)`	按 Content-Type 对应格式
`ctx.BindByContentType(obj)`	自动识别 JSON/Protobuf/表单

BindAndValidate配合结构体上的vdtag 即可实现声明式参数校验，比手写 if-else 干净得多。

4. Header、Cookie 与来源信息

方法	用途
`ctx.GetHeader(key)`	读请求头
`ctx.ContentType()`	请求的 Content-Type
`ctx.Cookie(key)`	读请求 Cookie
`ctx.UserAgent()`	客户端 User-Agent
`ctx.ClientIP()`	自动解析 X-Forwarded-For / X-Real-IP
`ctx.RemoteAddr()`	连接级远端地址
`ctx.Host()`/`ctx.Path()`/`ctx.Method()`	请求的基本元信息

📤 响应处理：把结果写出去

1. 状态码与快捷方法

ctx.SetStatusCode(code)/ctx.Status(code)：显式设置状态码；
ctx.NotFound()：一行重置响应并返回 404；
ctx.NotModified()：返回 304，常用于缓存场景。

2. 渲染响应体：JSON 是重头戏

渲染能力来自 pkg/app/server/render/，Render会同时写状态码与响应体（pkg/app/context.go#L1124-L1184）：

方法	说明
`ctx.JSON(code, obj)`	序列化 JSON 并自动设置 Content-Type ⭐
`ctx.PureJSON(code, obj)`	不做 HTML 转义的纯 JSON
`ctx.IndentedJSON(code, obj)`	带缩进的 pretty JSON
`ctx.XML(code, obj)`/`ctx.ProtoBuf(code, obj)`	XML / Protobuf 序列化
`ctx.HTML(code, name, obj)`	渲染 HTML 模板
`ctx.Data(code, contentType, data)`	输出任意字节流
`ctx.String(code, format, ...)`	格式化文本

⚠️ctx.JSON(204, x)这类无 body 的状态码（1xx/204/304）只写 Header，不会写 body，符合 HTTP 规范。

3. 手动写 Body、Header 与 Cookie

方法	用途
`ctx.Write(p)`/`ctx.WriteString(s)`	追加 body 内容
`ctx.SetBodyString(body)`	整体替换 body
`ctx.SetContentType(type)`	设置响应 Content-Type
`ctx.Header(key, value)`	智能设响应头（`value`为空则删除该头）
`ctx.SetCookie(...)`	一行下发 Set-Cookie，支持 Secure/HttpOnly/SameSite
`ctx.SetConnectionClose()`	提示客户端断连，不保持长连接

4. 重定向与文件响应

ctx.Redirect(statusCode, uri)：跳转前记得ctx.Abort()，否则后续 Handler 还会继续执行（见 pkg/app/context.go#L887-L896）；
ctx.File(path)：零拷贝式返回静态文件；
ctx.FileAttachment(path, filename)：触发浏览器下载并指定文件名。

🔀 中间件流程控制：Next、Abort 与键值对

这部分是写中间件（鉴权、限流、日志）的"方向盘"：

键值对传递：ctx.Set(key, v)写入请求级数据，ctx.Get(key)读取，另有MustGet（不存在直接 panic）、GetString/GetInt/GetTime等十余个类型化读取方法，以及ctx.ForEachKey(fn)遍历全部 Key（pkg/app/context.go#L909-L1072）。它实现了标准context.Value接口，可安全传给库代码。

流程控制：

方法	作用
`ctx.Next(c)`	在中间件内手动推进后续 Handler
`ctx.Abort()`	拦截剩余 Handler（鉴权失败必用）
`ctx.AbortWithStatus(code)`	Abort + 指定状态码
`ctx.AbortWithMsg(msg, code)`	Abort + 文本错误体
`ctx.AbortWithStatusJSON(code, obj)`	Abort + JSON 错误体
`ctx.IsAborted()`	判断是否已被中断
`ctx.Error(err)`	把错误压入`Errors`错误链，便于统一上报
`ctx.Finished()`	请求结束信号（chan），供异步任务感知

进阶技巧：

要把请求数据传给goroutine异步处理？先ctx.Copy()拿一份独立副本，避免主请求回收后引用失效；
需要 WebSocket 等协议升级？ctx.Hijack(handler)接管底层连接；
ctx.HandlerName()可在日志里打出当前业务 Handler 的函数名，排查问题很方便。

🚀 为什么值得速查：Hertz 的性能底气

Hertz 默认集成自研高性能网络库 Netpoll，在 QPS 与时延上相较其他框架有明显优势。下图为四框架（gin / fiber / fasthttp / hertz）在不同回显包大小下的 QPS 与 TP99 对比：

也正因RequestContext走的是零拷贝、内存池化的底层实现，你只管按上面的速查表写业务代码，性能优势是框架自带的。

📚 速查完毕：关键源码路径导航

模块	路径
RequestContext 全部 API	pkg/app/context.go
Request / Response 协议对象	pkg/protocol/request.go、pkg/protocol/response.go
数据绑定与校验	pkg/app/server/binding/
响应渲染（JSON/HTML/XML）	pkg/app/server/render/
状态码等常量	pkg/protocol/consts/
标准版完整示例	examples/standard/main.go