Hertz RequestContext API速查手册请求与响应处理的终极参考【免费下载链接】hertzGo 微服务 HTTP 框架具有高易用性、高性能、高扩展性等特点。项目地址: https://gitcode.com/CloudWeGo/hertzHertz 是一款高易用、高性能的 Go 微服务 HTTP 框架而RequestContext正是 Hertz 中处理请求与响应的核心上下文对象读取 Query/POST 参数、数据绑定、渲染 JSON 响应、控制中间件流程……所有操作都围绕它展开。本篇速查手册按使用场景把最常用的 RequestContext API 归类整理帮你一查就会、写码不卡。 一文读懂 RequestContext 是什么每收到一个 HTTP 请求Hertz 就会为其构造一个RequestContext它把一次请求的所有信息打包在一起定义见 pkg/app/context.go核心字段作用Request/Response原始请求与响应对象pkg/protocol/Params路由参数如/user/:id中的idHandlers链 index当前中间件执行链与位置支撑Next/AbortKeys请求级键值对供中间件与 Handler 间传递数据Errors累积的ErrorChain错误链Handler 的统一签名长这样完整示例见 examples/standard/main.goh.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 带默认值不存在返回defctx.GetQuery(key)Query 值 是否存在可区分空串与未传ctx.PostForm(key)取 POST 表单值自动兼容 multipartctx.GetPostForm(key)POST 值 是否存在同上ctx.Param(key)取路由参数/user/:id→ctx.Param(id)ctx.QueryArgs()/ctx.PostArgs()批量遍历参数适合日志打印、透传ctx.FormValue(key)一站式取值依次查 Query → POST → Multipart 经验法则GET 请求用QueryPOST 表单用PostFormURL 里的:name用Param懒得区分时直接上FormValue。2. 读取请求体 Body方法用途ctx.GetRawData()直接拿[]byte原始 bodyctx.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/路由参数按 tagctx.BindAndValidate(obj)绑定 按vdtag 校验参数ctx.BindQuery(obj)仅绑定 Queryquerytagctx.BindHeader(obj)仅绑定 Headerheadertagctx.BindPath(obj)仅绑定路由参数pathtagctx.BindForm(obj)仅绑定 Formformtagctx.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-Typectx.Cookie(key)读请求 Cookiectx.UserAgent()客户端 User-Agentctx.ClientIP()自动解析 X-Forwarded-For / X-Real-IPctx.RemoteAddr()连接级远端地址ctx.Host()/ctx.Path()/ctx.Method()请求的基本元信息 响应处理把结果写出去1. 状态码与快捷方法ctx.SetStatusCode(code)/ctx.Status(code)显式设置状态码ctx.NotFound()一行重置响应并返回 404ctx.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 转义的纯 JSONctx.IndentedJSON(code, obj)带缩进的 pretty JSONctx.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)整体替换 bodyctx.SetContentType(type)设置响应 Content-Typectx.Header(key, value)智能设响应头value为空则删除该头ctx.SetCookie(...)一行下发 Set-Cookie支持 Secure/HttpOnly/SameSitectx.SetConnectionClose()提示客户端断连不保持长连接4. 重定向与文件响应ctx.Redirect(statusCode, uri)跳转前记得ctx.Abort()否则后续 Handler 还会继续执行见 pkg/app/context.go#L887-L896ctx.File(path)零拷贝式返回静态文件ctx.FileAttachment(path, filename)触发浏览器下载并指定文件名。 中间件流程控制Next、Abort 与键值对这部分是写中间件鉴权、限流、日志的方向盘键值对传递ctx.Set(key, v)写入请求级数据ctx.Get(key)读取另有MustGet不存在直接 panic、GetString/GetInt/GetTime等十余个类型化读取方法以及ctx.ForEachKey(fn)遍历全部 Keypkg/app/context.go#L909-L1072。它实现了标准context.Value接口可安全传给库代码。流程控制方法作用ctx.Next(c)在中间件内手动推进后续 Handlerctx.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 全部 APIpkg/app/context.goRequest / Response 协议对象pkg/protocol/request.go、pkg/protocol/response.go数据绑定与校验pkg/app/server/binding/响应渲染JSON/HTML/XMLpkg/app/server/render/状态码等常量pkg/protocol/consts/标准版完整示例examples/standard/main.go上手建议先把「Query / PostForm / Param / BindAndValidate / JSON / Set-Get / Abort」这 7 个方法记熟它们能覆盖绝大多数接口开发其余 API 按需查本篇对应小节即可。【免费下载链接】hertzGo 微服务 HTTP 框架具有高易用性、高性能、高扩展性等特点。项目地址: https://gitcode.com/CloudWeGo/hertz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hertz RequestContext API速查手册：请求与响应处理的终极参考
Hertz RequestContext API速查手册请求与响应处理的终极参考【免费下载链接】hertzGo 微服务 HTTP 框架具有高易用性、高性能、高扩展性等特点。项目地址: https://gitcode.com/CloudWeGo/hertzHertz 是一款高易用、高性能的 Go 微服务 HTTP 框架而RequestContext正是 Hertz 中处理请求与响应的核心上下文对象读取 Query/POST 参数、数据绑定、渲染 JSON 响应、控制中间件流程……所有操作都围绕它展开。本篇速查手册按使用场景把最常用的 RequestContext API 归类整理帮你一查就会、写码不卡。 一文读懂 RequestContext 是什么每收到一个 HTTP 请求Hertz 就会为其构造一个RequestContext它把一次请求的所有信息打包在一起定义见 pkg/app/context.go核心字段作用Request/Response原始请求与响应对象pkg/protocol/Params路由参数如/user/:id中的idHandlers链 index当前中间件执行链与位置支撑Next/AbortKeys请求级键值对供中间件与 Handler 间传递数据Errors累积的ErrorChain错误链Handler 的统一签名长这样完整示例见 examples/standard/main.goh.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 带默认值不存在返回defctx.GetQuery(key)Query 值 是否存在可区分空串与未传ctx.PostForm(key)取 POST 表单值自动兼容 multipartctx.GetPostForm(key)POST 值 是否存在同上ctx.Param(key)取路由参数/user/:id→ctx.Param(id)ctx.QueryArgs()/ctx.PostArgs()批量遍历参数适合日志打印、透传ctx.FormValue(key)一站式取值依次查 Query → POST → Multipart 经验法则GET 请求用QueryPOST 表单用PostFormURL 里的:name用Param懒得区分时直接上FormValue。2. 读取请求体 Body方法用途ctx.GetRawData()直接拿[]byte原始 bodyctx.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/路由参数按 tagctx.BindAndValidate(obj)绑定 按vdtag 校验参数ctx.BindQuery(obj)仅绑定 Queryquerytagctx.BindHeader(obj)仅绑定 Headerheadertagctx.BindPath(obj)仅绑定路由参数pathtagctx.BindForm(obj)仅绑定 Formformtagctx.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-Typectx.Cookie(key)读请求 Cookiectx.UserAgent()客户端 User-Agentctx.ClientIP()自动解析 X-Forwarded-For / X-Real-IPctx.RemoteAddr()连接级远端地址ctx.Host()/ctx.Path()/ctx.Method()请求的基本元信息 响应处理把结果写出去1. 状态码与快捷方法ctx.SetStatusCode(code)/ctx.Status(code)显式设置状态码ctx.NotFound()一行重置响应并返回 404ctx.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 转义的纯 JSONctx.IndentedJSON(code, obj)带缩进的 pretty JSONctx.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)整体替换 bodyctx.SetContentType(type)设置响应 Content-Typectx.Header(key, value)智能设响应头value为空则删除该头ctx.SetCookie(...)一行下发 Set-Cookie支持 Secure/HttpOnly/SameSitectx.SetConnectionClose()提示客户端断连不保持长连接4. 重定向与文件响应ctx.Redirect(statusCode, uri)跳转前记得ctx.Abort()否则后续 Handler 还会继续执行见 pkg/app/context.go#L887-L896ctx.File(path)零拷贝式返回静态文件ctx.FileAttachment(path, filename)触发浏览器下载并指定文件名。 中间件流程控制Next、Abort 与键值对这部分是写中间件鉴权、限流、日志的方向盘键值对传递ctx.Set(key, v)写入请求级数据ctx.Get(key)读取另有MustGet不存在直接 panic、GetString/GetInt/GetTime等十余个类型化读取方法以及ctx.ForEachKey(fn)遍历全部 Keypkg/app/context.go#L909-L1072。它实现了标准context.Value接口可安全传给库代码。流程控制方法作用ctx.Next(c)在中间件内手动推进后续 Handlerctx.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 全部 APIpkg/app/context.goRequest / Response 协议对象pkg/protocol/request.go、pkg/protocol/response.go数据绑定与校验pkg/app/server/binding/响应渲染JSON/HTML/XMLpkg/app/server/render/状态码等常量pkg/protocol/consts/标准版完整示例examples/standard/main.go上手建议先把「Query / PostForm / Param / BindAndValidate / JSON / Set-Get / Abort」这 7 个方法记熟它们能覆盖绝大多数接口开发其余 API 按需查本篇对应小节即可。【免费下载链接】hertzGo 微服务 HTTP 框架具有高易用性、高性能、高扩展性等特点。项目地址: https://gitcode.com/CloudWeGo/hertz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考