fiber中Ctx对象的用法

Ctx 结构表示保存 HTTP 请求和响应的上下文

用于请求查询字符串，参数，正文，HTTP 标头等方法

Ctx 对象的方法整体包含以下类别

整体信息或设置
用户请求处理
    --整体信息获取或操作
    --请求Header
    --请求Body
    --请求Form
    --请求查询参数
路由处理
    --整体信息获取或操作
    --路由参数
服务响应处理
    --整体信息获取或操作
    --响应Header
    --响应Body

整体信息或设置

App() *App     获取*App指针
ClientHelloInfo() *tls.ClientHelloInfo   获取ClientHello消息
Context() *fasthttp.RequestCtx     获取底层的包含截止时间的请求上下文
String() string      返回 ctx 的唯一字符串表示形式
        返回的值可能对日志记录有用
IsFromLocal() bool    请求是否来自本地

用户请求处理

整体信息获取或操作

Request() *fasthttp.Request
        获取底层的fasthttp.Request指针

Method(override ...string) string   请求方式
    override为有效HTTP方法时，会修改请求方法并返回修改后的方法
    override为无效HTTP方法时，会修改失败并返回原始的请求方法
Port() string          请求客户端端口

Protocol() string      请求协议(http/https)
Secure() bool          是否安全连接，等同于c.Protocol() == "https"
BaseURL() string       基本URL(protocol + domain:port)
Hostname() string      主机名(domain:port)
OriginalURL() string   请求URI(path+query)

Subdomains(offset ...int) []string
    返回请求的域名中子域的字符串切片
    offset 表示子域偏移量，默认为 2
    // 如主机 tobi.ferrets.example.com
      c.Subdomains()  // ["fielrets", "tobi"]
      c.Subdomains(1) // ["tobi"]

Path(override ...string) string
    返回请求URL的 path 部分，override表示修改path
    当修改了path，需要调用 RestartRouting 而不是 Next

请求header

判断相关
Accepts(offers ...string) string
    检查offers中最匹配请求Accept头要求的内容并返回该offer
    offers可以使用mime字符串或不含点的后缀字符串
    没有符合请求Accept头要求的offers会返回空白字符串
AcceptsCharsets(offers ...string) string   // Accept-Charset
AcceptsEncodings(offers ...string) string  // Accept-Encoding
AcceptsLanguages(offers ...string) string  // Accept-Language
Fresh() bool    客户端的缓存是否是最新的
    如果客户端发送Cache-Control：no-cache 请求头将恒定返回false
Stale() bool    客户端的缓存是否是需要更新的
IsProxyTrusted() bool   客户端IP是否可信
    通过代理范围和 IP 映射检查远程 IP
    如果 Config.TrustProxy 为 false，则永远返回 true
Is(ext string) bool    判定请求的Content-Type是否匹配指定后缀，ext可以包含和省略后缀中的点
XHR() bool             请求的 X-Requested-With 头字段是否为 XMLHttpRequest
    为true表示该请求是由客户端库发出的

获取信息
GetReqHeaders() map[string][]string   所有 HTTP 请求标头
Get(key string, defaultValue ...string) string
    指定请求标头的值，大小写不敏感
ReqHeaderParser(out any) error
    解析并绑定请求头到 struct中
    struct标签名reqHeader
IP() string         返回请求的客户端 IP 地址
IPs() []string      返回X-Forwarded-For请求中的IP地址数组

Cookie相关
Cookies(key string, defaultValue ...string) string
        获取键为 key 的 cookie 值
CookieParser(out any) error
    解析并绑定请求cookie到 struct中
    struct标签名cookie

请求Body

BodyRaw() []byte    POST请求的原始请求body
Body() []byte       POST请求时根据Content-Encoding尝试从正文字节执行文件解压缩
        如果没有Content-Encoding头将作为BodyRaw执行
BodyParser(out any) error
    解析并绑定请求body到 struct中
    仅支持 POST 且 content-type 值为以下之一的请求
    application/json        对应struct标签名json
    application/x-www-form-urlencoded
    multipart/form-data     对应struct标签名form
    application/xml
    text/xml                对应struct标签名xml
    解析表单时只解析表单值，上传的文件无法解析

请求Form

MultipartForm() (*multipart.Form, error)
    解析表单所有字段及上传文件内容
    type mime/multipart.Form struct {
        Value map[string][]string
        File  map[string][]*FileHeader
    }
    type mime/multipart.FileHeader struct {
        Filename string
        Header   net/textproto.MIMEHeader
        Size     int64
    }
    type MIMEHeader map[string][]string


FormValue(key string, defaultValue ...string) string
    获取指定表单字段的第一个值，key不存在返回空字符串
FormFile(key string) (*multipart.FileHeader, error)
    获取指定表单字段上传的第一个文件

SaveFile(fileheader *multipart.FileHeader, path string) error
    将通过POST上传的文件保存到磁盘

SaveFileToStorage(fileheader *multipart.FileHeader, path string, storage Storage) error
    将通过POST上传的文件保存到磁盘的同时保存到自定义存储后端（如云存储、数据库、内存存储）
    type Storage interface {
        Get(key string) ([]byte, error)
        Set(key string, val []byte, exp time.Duration) error
        Delete(key string) error
        Reset() error
        Close() error
    }
    要使用该方法，需要实现 Storage 接口

请求查询参数

Queries() map[string]string   解析查询字符串

Query(key string, defaultValue ...string) string
QueryBool(key string, defaultValue ...bool) bool
QueryFloat(key string, defaultValue ...float64) float64
QueryInt(key string, defaultValue ...int) int

QueryParser(out any) error
    解析并绑定查询参数到 struct中
    struct标签名query

路由处理

路由信息获取或操作

Route() *Route  返回当前匹配的Route实例
    type Route struct {
        Method string
        Name   string
        Path     string
        Params   []string
        Handlers []Handler
    }

Next() error    执行堆栈中与当前路由匹配的下一个方法

Bind(vars Map) error
    将默认数据绑定到所有模版渲染中，可以被Render()方法中传递数据来覆盖

Locals(key any, value ...any) any
    用于存储限定于请求范围的变量，仅对与请求匹配的所有后续路由可用
    不传入 value 表示获取值，传入 value 表示设定值
    存储的数据在请求处理完成后会被删除
    如果存储的数据实现了 io.Closer 接口，在删除之前还会调用它的 Close 方法

RestartRouting() error         重启路由
    一般在路由中更改请求路径后会用，如Path(path)
    但是注意不要导致无限循环

GetRouteURL(routeName string, params Map) (string, error)
    根据Map数据来生成指定路由的URI
    app.Get("/user/:id", ... ).Name("userroute")
    app.Get("/test", func(c *fiber.Ctx) error {
        location, _ := c.GetRouteURL("userroute", fiber.Map{"id": 1})
        return c.SendString(location)
    })
    // 访问/test 输出 "/user/1"

RedirectToRoute(routeName string, params fiber.Map, status ...int) error
    重定向到指定名称的路由
    params表示目标路由的路由参数
    状态码status默认为302

SetContext(ctx context.Context)    设置一个自定义的上下文
Context() context.Context     获取用户自定义的上下文
        如果之前未设置自定义上下文，返回非 nil 的空上下文

Range(size int) (Range, error)
    用于大文件的分片传输
    客户端使用Range请求头指定想要获取的资源分片
        Range: bytes=0-99
        表示客户端想要以二进制形式获取资源的0-99字节共计100个字节大小的分片数据
        支持多个分片：bytes=0-99, 200-299, 300-399
    服务端根据Range请求头和表示资源总大小的size创建一个Range
    type Range struct {
        Type   string     // 默认"bytes"
        Ranges []RangeSet
    }
    type RangeSet struct {
        Start int
        End   int
    }
    服务端在接收到含Range请求头的请求需要在响应头中设置
    c.Set("Content-Range", fmt.Sprintf("bytes %d-%d/%d", Start, End, fileSize))
    c.Set("Content-Length", strconv.Itoa(r.End-r.Start+1))
    c.Status(fiber.StatusPartialContent) // 206 状态码
    客户端在接收后通过Content-Range中的文件总大小数值来判断资源是否已经接受完成
    当客户端的Range指定的片段超出了资源总大小，服务端需要设置状态码416
    c.Status(fiber.StatusRequestedRangeNotSatisfiable).SendString("无效范围")

路由参数

AllParams() map[string]string   // 获取所有路由参数

Params(key string, defaultValue ...string) string
    获取指定路由参数
    key不存在返回defaultValue，默认为空字符串

ParamsInt(key string) (int, error)
    从路由参数中获取整数
    key不存在返回0，参数不是数字返回0和err
    此方法等效于将 atoi 与 Params 一起使用

ParamsParser(out any) error
    解析并绑定请求参数到 struct中
    struct标签名params

服务响应处理

整体信息获取或操作

Response() *fasthttp.Response  获取 *fasthttp.Response

SendStatus(status int) error
    设置 HTTP 状态码，会自动根据状态码设置匹配的状态码描述文本
Status(status int) Ctx
    同SendStatus，但返回上下文，可以实现链式调用

响应Header

获取响应头
GetRespHeaders() map[string][]string   获取所有响应头
GetRespHeader(key string, defaultValue ...string) string
    获取指定响应头，key大小写不敏感

设置通用响应头
Set(key, val string)    设置响应头
Append(key string, values ...string)  追加值到指定字段
    会将key首字母以及段横线(如果存在)后的第一个字母转为大写
        demo-test会转为Demo-Test
    key中存在不支持的字符(如中文)时调用该方法不生效

设置特定响应头
Attachment(filename ...string)
    设置 Content-Disposition 头为 attachment，会弹出下载对话框
    不设置filename会将当前页面显示内容作为附件下载
    设置了filename会自动根据文件后缀设置Content-Type
Links(link ...string)    设置 Link 头
    参数一般两两出现，第一个表示link的url，第二个表示rel值
    c.Links("http://domain.com/?page=2", "next")
    // Link: <http://domain.com/?page=2>; rel="next"
Type(ext string, charset ...string) *Ctx
    将 Content-Type 头设置为指定的拓展名对应的 MIME
    ext 表示拓展名，可以包含点也可以不包含点
    可以使用"path/filepath"包中的filepath.Ext(file)来获取带点的后缀名
    可以使用官方库"mime"中的mime.TypeByExtension(ext)来获取 MIME值后通过Set()方法设置Content-Type头
Vary(fields ...string)
    将给定的若干个值追加到 Vary 响应头中

设置重定向
Location(path string)   设置表示跳转路径的 Location 头
Redirect(location string, status ...int) error
    重定向到指定目录或文件，状态码status默认302
RedirectBack(fallback string, status ...int) error
    后退到Referer请求头的网址
    如果Referer请求头不存在重定向到fallback
    状态码status默认为302

Cookie相关
ClearCookie(key ...string)    清除客户端 Cookie
    传入一个或多个 key 会清除指定的 key
    不传入任何 key 值会清除所有 Cookie
Cookie(cookie *Cookie)   设置Cookie，发送Set-Cookie标头
    type Cookie struct {
        Name     string
        Value    string
        Path     string
        Domain   string
        MaxAge   int
        Expires  time.Time
        Secure   bool
        HTTPOnly bool
        SameSite string
        SessionOnly bool
    }

响应Body

Render(name string, bind Map, layouts ...string) error
    使用指定数据按指定的模板渲染并发送响应
    name ：模板名称
    bind ：绑定到模板的数据
    layouts：模板布局，不提供将使用全局布局

Write(p []byte) (int, error)
Writef(f string, a ...any) (int, error)
WriteString(s string) (int, error)
    向响应Body中追加内容

Send(body []byte) error
    设置响应Body为指定的内容
    该方法会有内部的类型断言开销
    推荐使用SendString或SendStream减少类型断言开销提升性能
SendString(body string) error
SendStream(stream io.Reader, size ...int) error
SendStreamWriter(streamWriter func(*bufio.Writer)) error

SendFile(file string, compress ...bool) error
    将指定文件的内容作为响应Body
    会自动根据文件扩展名设置 Content-Type
    compress表示是否启用文件压缩，默认false
    如果启用压缩，会自动设置 Content-Encoding 标头，可用的压缩方法 gzip、br 和 zstd

Download(file string, filename ...string) error
    将文件作为attachment从路径传输，浏览器会弹出下载对话框
    filename指定下载后保存的文件名

Format(body any) error
    根据 Accept 标头转换内容格式
    如果未指定或没有适当的格式，则使用 text/plain

JSON(data any, ctype ...string) error
    将data解析为json并作为响应Body
    并将Content-Type设置ctype，默认application/json
JSONP(data any, callback ...string) error
    将data解析为json，作为参数传递给回调函数，回调函数执行结果作为响应Body
    回调函数名默认为callback

XML(data any) error
    将响应内容转换为XML，并设置Content-Type为application/xml