获取请求参数有三种方式:1. c.params("id")提取路径变量;2. c.params("*")捕获通配符路径;3. c.query("page")读取查询参数并支持默认值;所有返回字符串需手动类型转换。

获取请求参数与路径变量
当路由定义为 /users/:id/orders/:order_id 时,需从上下文提取动态段值。
方法一:使用 c.Params("id") 获取命名路径参数,返回字符串类型值,若参数不存在则返回空字符串。
方法二:调用 c.Params("*") 捕获通配符匹配的整个路径片段,适用于 RESTful 资源嵌套场景,比如 /api/v1/* 匹配到 users/123/profile 时返回该完整子串。
方法三:用 c.Query("page") 提取 URL 查询参数,支持默认值回退——c.Query("limit", "20") 在未传 limit 时自动补上 "20"。
【c.Params() 和 c.Query() 返回的都是原始字符串,不会自动类型转换,需要手动解析为 int 或 bool】
读取请求体数据
区分表单、JSON 和原始字节三种常见格式。
第一步:处理 JSON 请求体,直接调用 c.Body() 获取原始字节,再用 json.Unmarshal 解析;更推荐用 c.Struct(&v) 一步完成反序列化并校验结构体字段标签。
第二步:读取表单数据,c.FormValue("username") 可取普通字段,c.FormFile("avatar") 专门用于文件上传——注意它必须配合 enctype="multipart/form-data" 使用,否则返回 nil 错误。
第三步:获取原始请求体(如 Webhook 签名验证),调用 c.Body() 即可,但【该方法只能调用一次,多次调用会返回空字节切片】,因为底层 reader 已被消耗。
设置响应内容与状态码
发送文本最简方式是 c.SendString("OK"),它自动设为 200 状态码且 Content-Type 为 text/plain。
返回 JSON 推荐用 c.JSON(201, data),第一个参数是显式状态码,避免依赖默认值;若只传结构体不传状态码,c.JSON(data) 默认发 200。
重定向用 c.Redirect(302, "/login"),支持临时跳转和永久跳转(301);注意路径必须带协议和域名才能跨域跳转,否则视为相对路径。
设置自定义 Header 必须在写入响应体前完成:c.Set("X-Request-ID", uuid.New().String()),否则会被忽略。
上下文生命周期与数据绑定
所有通过 c.Locals(key, value) 设置的数据仅在当前请求生命周期内有效,可用于中间件向后续处理器透传信息,比如鉴权中间件存入用户 ID。
c.Context() 返回标准 context.Context 实例,可用于传递取消信号或超时控制,但【不可保存该 context 到 goroutine 外部变量中,否则引发数据竞争】。
使用 c.Next() 手动触发下一个中间件,常用于条件分支逻辑,例如权限检查通过后才执行 c.Next(),否则直接返回 403。











