[译] fasthttp 文档手册

# fasthttp 文档手册 貌似文章有最大长度限制,完整全文地址:https://github.com/DavidCai1993/my-blog/issues/35 ## 常量 ```go const ( CompressNoCompression = flate.NoCompression CompressBestSpeed = flate.BestSpeed CompressBestCompression = flate.BestCompression CompressDefaultCompression = flate.DefaultCompression ) ``` 所支持的压缩级别。 ```go const ( StatusContinue = 100 // RFC 7231, 6.2.1 StatusSwitchingProtocols = 101 // RFC 7231, 6.2.2 StatusProcessing = 102 // RFC 2518, 10.1 StatusOK = 200 // RFC 7231, 6.3.1 StatusCreated = 201 // RFC 7231, 6.3.2 StatusAccepted = 202 // RFC 7231, 6.3.3 StatusNonAuthoritativeInfo = 203 // RFC 7231, 6.3.4 StatusNoContent = 204 // RFC 7231, 6.3.5 StatusResetContent = 205 // RFC 7231, 6.3.6 StatusPartialContent = 206 // RFC 7233, 4.1 StatusMultiStatus = 207 // RFC 4918, 11.1 StatusAlreadyReported = 208 // RFC 5842, 7.1 StatusIMUsed = 226 // RFC 3229, 10.4.1 StatusMultipleChoices = 300 // RFC 7231, 6.4.1 StatusMovedPermanently = 301 // RFC 7231, 6.4.2 StatusFound = 302 // RFC 7231, 6.4.3 StatusSeeOther = 303 // RFC 7231, 6.4.4 StatusNotModified = 304 // RFC 7232, 4.1 StatusUseProxy = 305 // RFC 7231, 6.4.5 StatusTemporaryRedirect = 307 // RFC 7231, 6.4.7 StatusPermanentRedirect = 308 // RFC 7538, 3 StatusBadRequest = 400 // RFC 7231, 6.5.1 StatusUnauthorized = 401 // RFC 7235, 3.1 StatusPaymentRequired = 402 // RFC 7231, 6.5.2 StatusForbidden = 403 // RFC 7231, 6.5.3 StatusNotFound = 404 // RFC 7231, 6.5.4 StatusMethodNotAllowed = 405 // RFC 7231, 6.5.5 StatusNotAcceptable = 406 // RFC 7231, 6.5.6 StatusProxyAuthRequired = 407 // RFC 7235, 3.2 StatusRequestTimeout = 408 // RFC 7231, 6.5.7 StatusConflict = 409 // RFC 7231, 6.5.8 StatusGone = 410 // RFC 7231, 6.5.9 StatusLengthRequired = 411 // RFC 7231, 6.5.10 StatusPreconditionFailed = 412 // RFC 7232, 4.2 StatusRequestEntityTooLarge = 413 // RFC 7231, 6.5.11 StatusRequestURITooLong = 414 // RFC 7231, 6.5.12 StatusUnsupportedMediaType = 415 // RFC 7231, 6.5.13 StatusRequestedRangeNotSatisfiable = 416 // RFC 7233, 4.4 StatusExpectationFailed = 417 // RFC 7231, 6.5.14 StatusTeapot = 418 // RFC 7168, 2.3.3 StatusUnprocessableEntity = 422 // RFC 4918, 11.2 StatusLocked = 423 // RFC 4918, 11.3 StatusFailedDependency = 424 // RFC 4918, 11.4 StatusUpgradeRequired = 426 // RFC 7231, 6.5.15 StatusPreconditionRequired = 428 // RFC 6585, 3 StatusTooManyRequests = 429 // RFC 6585, 4 StatusRequestHeaderFieldsTooLarge = 431 // RFC 6585, 5 StatusUnavailableForLegalReasons = 451 // RFC 7725, 3 StatusInternalServerError = 500 // RFC 7231, 6.6.1 StatusNotImplemented = 501 // RFC 7231, 6.6.2 StatusBadGateway = 502 // RFC 7231, 6.6.3 StatusServiceUnavailable = 503 // RFC 7231, 6.6.4 StatusGatewayTimeout = 504 // RFC 7231, 6.6.5 StatusHTTPVersionNotSupported = 505 // RFC 7231, 6.6.6 StatusVariantAlsoNegotiates = 506 // RFC 2295, 8.1 StatusInsufficientStorage = 507 // RFC 4918, 11.5 StatusLoopDetected = 508 // RFC 5842, 7.2 StatusNotExtended = 510 // RFC 2774, 7 StatusNetworkAuthenticationRequired = 511 // RFC 6585, 6 ) ``` 与 net/http 相同的 HTTP 状态吗。 ```go const DefaultConcurrency = 256 * 1024 ``` `DefaultConcurrency` 为默认情况下(没有设置 `Server.Concurrency` 时)服务器可以接受的最大并发请求数。 ```go const DefaultDNSCacheDuration = time.Minute ``` `DefaultDNSCacheDuration` 是由 `Dial*` 函数族缓存处理过的 TCP 地址的持续时间。 ```go const DefaultDialTimeout = 3 * time.Second ``` `DefaultDialTimeout` 是由 `Dial` 和 `DialDualStack` 使用的用于建立 TCP 连接的超时时间。 ```go const DefaultMaxConnsPerHost = 512 ``` `DefaultMaxConnsPerHost` 是 http 客户端在默认情况下(如果没有设置 `Client.MaxConnsPerHost`)单个 host 可以建立的最大并发连接数。 ```go const DefaultMaxIdleConnDuration = 10 * time.Second ``` `DefaultMaxIdleConnDuration` 是在空闲的 keep-alive 连接被关闭前默认的持续时间。 ```go const DefaultMaxPendingRequests = 1024 ``` `DefaultMaxPendingRequests` 是 `PipelineClient.MaxPendingRequests` 的默认值。 ```go const DefaultMaxRequestBodySize = 4 * 1024 * 1024 ``` `DefaultMaxRequestBodySize` 是服务器默认可读的最大请求体大小。 更多详情请参阅 `Server.MaxRequestBodySize` 。 ```go const FSCompressedFileSuffix = ".fasthttp.gz" ``` `FSCompressedFileSuffix` 是当需要使用新文件名存储被压缩后的文件时, `FS` 在原始文件名上添加的前缀。更多详情请参阅 `FS.Compress` 。 ```go const FSHandlerCacheDuration = 10 * time.Second ``` `FSHandlerCacheDuration` 是由 `FS` 所打开的非活跃文件句柄的默认失效时间。 ## 变量 ```go var ( // ErrNoFreeConns 在当特定的 host 没有可用的连接时返回。 // // 如果你看到了这个错误,你可以选择调高每个 host 可用的连接数。 ErrNoFreeConns = errors.New("no free connections available to host") // ErrTimeout 在调用超时时返回。 ErrTimeout = errors.New("timeout") // ErrConnectionClosed 会在当服务端在返回第一个相应字节前被关闭时, // 于客户端方法中返回。 // // 如果你看到了这个错误,你可以在服务端关闭连接前通过 `'Connection: close'` 相应头 // 来修复这个错误,或者在客户端发送请求前添加 `'Connection: close'` 请求头。 ErrConnectionClosed = errors.New("the server closed connection before returning the first response byte. " + "Make sure the server returns 'Connection: close' response header before closing the connection") ) ``` ```go var ( // CookieExpireDelete 可以会被支持于 `Cookie.Expire` 中,用于为指定 // cookie 添加过期。 CookieExpireDelete = time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC) // CookieExpireUnlimited 用于表明该 cookie 不会过期。 CookieExpireUnlimited = zeroTime ) ``` ```go var ( // ErrPerIPConnLimit 会在任一 ip 连接数超过 Server.MaxConnsPerIP 时 // 由 ServeConn 返回。 ErrPerIPConnLimit = errors.New("too many connections per ip") // ErrConcurrencyLimit 会在并发连接数超过 Server.Concurrency 时由 // ServeConn 返回。 ErrConcurrencyLimit = errors.New("canot serve the connection because Server.Concurrency concurrent connections are served") // ErrKeepaliveTimeout 会在连接的时长超过 MaxKeepaliveDuration 时 // 由 ServeConn 返回。 ErrKeepaliveTimeout = errors.New("exceeded MaxKeepaliveDuration") ) ``` ```go var ErrBodyTooLarge = errors.New("body size exceeds the given limit") ``` `ErrBodyTooLarge` 会在请求体或者响应体超过指定限制时返回。 ```go var ErrDialTimeout = errors.New("dialing to the given TCP address timed out") ``` `ErrDialTimeout` 会在 TCP 握手超时时触发。 ```go var ErrMissingFile = errors.New("there is no uploaded file associated with the given key") ``` `ErrMissingFile` 会在没有与指定的 `multipart` 表单键相关联的被上传文件时由 `FormFile` 返回。 ```go var ErrNoArgValue = errors.New("no Args value for the given key") ``` `ErrNoArgValue` 会在指定 `Args` 键缺少值时返回。 ```go var ErrNoMultipartForm = errors.New("request has no multipart/form-data Content-Type") ``` `ErrNoMultipartForm` 意味着请求的 `Content-Type` 不是 `'multipart/form-data'` 。 ```go var ErrPipelineOverflow = errors.New("pipelined requests' queue has been overflown. Increase MaxConns and/or MaxPendingRequests") ``` `ErrPipelineOverflow` 会在请求的队列溢出时,由 `PipelineClient.Do*` 函数族返回。 ### func AppendBytesStr ```go func AppendBytesStr(dst []byte, src string) []byte ``` `AppendBytesStr` 向 `dst` 追加 `src` ,并且返回追加后的 `dst` 。 这个函数与 `append(dst, src...)` 的性能没有差别。目前它仅用于向后兼容。 这个函数已经弃用并且可能很快被移除。 ### func AppendGunzipBytes ```go func AppendGunzipBytes(dst, src []byte) ([]byte, error) ``` `AppendGunzipBytes` 向 `dst` 追加 gunzip 压缩后的 `src` ,并且返回追加后的 `dst` 。 ### func AppendGzipBytes ```go func AppendGzipBytes(dst, src []byte) []byte ``` `AppendGzipBytes` 向 `dst` 追加 gzip 压缩后的 `src` ,并且返回追加后的 `dst` 。 ### func AppendGzipBytesLevel ```go func AppendGzipBytesLevel(dst, src []byte, level int) []byte ``` `AppendGzipBytesLevel` 向 `dst` 追加指定级别的 gzip 压缩后的 `src` ,并且返回追加后的 `dst` 。 支持的压缩级别有: - `CompressNoCompression` - `CompressBestSpeed` - `CompressBestCompression` - `CompressDefaultCompression` ### func AppendHTMLEscape ```go func AppendHTMLEscape(dst []byte, s string) []byte ``` `AppendHTMLEscape` 向 `dst` 追加 HTML 转义后的 `src` ,并且返回追加后的 `dst` 。 ### func AppendHTMLEscapeBytes ```go func AppendHTMLEscapeBytes(dst, s []byte) []byte ``` `AppendHTMLEscapeBytes` 向 `dst` 追加 HTML 转义后的 `src` ,并且返回追加后的 `dst` 。 ### func AppendHTTPDate ```go func AppendHTTPDate(dst []byte, date time.Time) []byte ``` `AppendHTTPDate` 向 `dst` 追加符合 HTTP-compliant (RFC1123) 表示的时间 ,并且返回追加后的 `dst` 。 ### func AppendIPv4 ```go func AppendIPv4(dst []byte, ip net.IP) []byte ``` `AppendIPv4` 向 `dst` 追加表示 ip v4 的字符串 ,并且返回追加后的 `dst` 。 ### func AppendNormalizedHeaderKey ```go func AppendNormalizedHeaderKey(dst []byte, key string) []byte ``` `AppendNormalizedHeaderKey` 向 `dst` 追加标准化后的 HTTP 头键(名),并且返回追加后的 `dst` 。 标准化后的头键由一个大写字母开头。在 `-` 后的第一个字母也为大写。其他的所有字母则都为小写。例子: - coNTENT-TYPe -> Content-Type - HOST -> Host - foo-bar-baz -> Foo-Bar-Baz ### func AppendNormalizedHeaderKeyBytes ```go func AppendNormalizedHeaderKeyBytes(dst, key []byte) []byte ``` `AppendNormalizedHeaderKeyBytes` 向 `dst` 追加标准化后的 HTTP 头键(名),并且返回追加后的 `dst` 。 标准化后的头键由一个大写字母开头。在 `-` 后的第一个字母也为大写。其他的所有字母则都为小写。例子: - coNTENT-TYPe -> Content-Type - HOST -> Host - foo-bar-baz -> Foo-Bar-Baz ### func AppendQuotedArg ```go func AppendQuotedArg(dst, src []byte) []byte ``` `AppendQuotedArg` 向 `dst` 追加经过 url 加密的 `src` ,并且返回追加后的 `dst` 。 ### func AppendUint ```go func AppendUint(dst []byte, n int) []byte ``` `AppendUint` 向 `dst` 追加 `n`,并且返回追加后的 `dst` 。 ### func Dial ```go func Dial(addr string) (net.Conn, error) ``` `Dial` 使用 tcp4 连接指定的 TCP 地址 `addr` 。 与 `net.Dial` 相比,该函数有以下这些额外的特性: - 它通过以 `DefaultDNSCacheDuration` 持续时间缓存解析后的 TCP 地址来减少 DNS 解析器的负载。 - 它通过轮询来连接所有被解析后的 TCP 连接,直至第一个连接被建立。这在当其中的某一个 TCP 地址临时性不可用时相当有用。 - 在 `DefaultDialTimeout` 秒之后若连接还没有被建立,它会返回 `ErrDialTimeout` ,可以使用 `DialTimeout` 来自定义这个超时。 `addr` 参数必须包含端口,例如: - `foobar.baz:443` - `foo.bar:80` - `aaa.com:8080` ### func DialDualStack ```go func DialDualStack(addr string) (net.Conn, error) ``` `DialDualStack` 使用 tcp4 和 tcp6 连接指定的 TCP 地址 `addr` 。 与 `net.Dial` 相比,该函数有以下这些额外的特性: - 它通过以 `DefaultDNSCacheDuration` 持续时间缓存解析后的 TCP 地址来减少 DNS 解析器的负载。 - 它通过轮询来连接所有被解析后的 TCP 连接,直至第一个连接被建立。这在当其中的某一个 TCP 地址临时性不可用时相当有用。 - 在 `DefaultDialTimeout` 秒之后若连接还没有被建立,它会返回 `ErrDialTimeout` ,可以使用 `DialTimeout` 来自定义这个超时。 `addr` 参数必须包含端口,例如: - `foobar.baz:443` - `foo.bar:80` - `aaa.com:8080` ### func DialDualStackTimeout ```go func DialDualStackTimeout(addr string, timeout time.Duration) (net.Conn, error) ``` `DialDualStackTimeout` 使用 tcp4 和 tcp6 连接指定的 TCP 地址 `addr` ,并且会在指定时间后超时。 与 `net.Dial` 相比,该函数有以下这些额外的特性: - 它通过以 `DefaultDNSCacheDuration` 持续时间缓存解析后的 TCP 地址来减少 DNS 解析器的负载。 - 它通过轮询来连接所有被解析后的 TCP 连接,直至第一个连接被建立。这在当其中的某一个 TCP 地址临时性不可用时相当有用。 - 在 `DefaultDialTimeout` 秒之后若连接还没有被建立,它会返回 `ErrDialTimeout` ,可以使用 `DialTimeout` 来自定义这个超时。 `addr` 参数必须包含端口,例如: - `foobar.baz:443` - `foo.bar:80` - `aaa.com:8080` ### func DialTimeout ```go func DialTimeout(addr string, timeout time.Duration) (net.Conn, error) ``` `DialTimeout` 使用 tcp4 和 tcp6 连接指定的 TCP 地址 `addr` ,并且会在指定时间后超时。 与 `net.Dial` 相比,该函数有以下这些额外的特性: - 它通过以 `DefaultDNSCacheDuration` 持续时间缓存解析后的 TCP 地址来减少 DNS 解析器的负载。 - 它通过轮询来连接所有被解析后的 TCP 连接,直至第一个连接被建立。这在当其中的某一个 TCP 地址临时性不可用时相当有用。 - 在 `DefaultDialTimeout` 秒之后若连接还没有被建立,它会返回 `ErrDialTimeout` ,可以使用 `DialTimeout` 来自定义这个超时。 `addr` 参数必须包含端口,例如: - `foobar.baz:443` - `foo.bar:80` - `aaa.com:8080` ### func Do ```go func Do(req *Request, resp *Response) error ``` `Do` 发出指定的 http 请求,在得到响应后并且填充指定的 http 响应对象。 请求必须至少包含一个非空的 RequestURI (包含协议和 host)或非空的 Host 头 + RequestURI。 客户端以以下顺序确定待请求的服务端: - 如果 RequestURI 包含完整的带有协议和 host 的 url ,则从 RequestURI 中取得。 - 否则就从 Host 头中取得。 这个函数不会跟随重定向。若要跟随重定向,请使用 `Get*` 。 如果 `resp` 是 `nil` ,那么响应会被忽略。 如果向指定请求 host 的所有 `DefaultMaxConnsPerHost` 数量的连接都被占用,那么会返回 `ErrNoFreeConns`。 在有性能要求的代码中,推荐通过 `AcquireRequest` 和 `AcquireResponse` 来获取 `req` 和 `resp` 。 ### func DoDeadline ```go func DoDeadline(req *Request, resp *Response, deadline time.Time) error ``` `DoDeadline` 发出指定的 http 请求,并且在指定的 deadline 之前得到响应后填充指定的 http 响应对象。 请求必须至少包含一个非空的 RequestURI (包含协议和 host)或非空的 Host 头 + RequestURI。 客户端以以下顺序确定待请求的服务端: - 如果 RequestURI 包含完整的带有协议和 host 的 url ,则从 RequestURI 中取得。 - 否则就从 Host 头中取得。 这个函数不会跟随重定向。若要跟随重定向,请使用 `Get*` 。 如果 `resp` 是 `nil` ,那么响应会被忽略。 如果向指定请求 host 的所有 `DefaultMaxConnsPerHost` 数量的连接都被占用,那么会返回 `ErrNoFreeConns`。 在有性能要求的代码中,推荐通过 `AcquireRequest` 和 `AcquireResponse` 来获取 `req` 和 `resp` 。 ### func DoTimeout ```go func DoTimeout(req *Request, resp *Response, timeout time.Duration) error ``` `DoTimeout` 发出指定的 http 请求,并且在指定的超时之前得到响应后填充指定的 http 响应对象。 请求必须至少包含一个非空的 RequestURI (包含协议和 host)或非空的 Host 头 + RequestURI。 客户端以以下顺序确定待请求的服务端: - 如果 RequestURI 包含完整的带有协议和 host 的 url ,则从 RequestURI 中取得。 - 否则就从 Host 头中取得。 这个函数不会跟随重定向。若要跟随重定向,请使用 `Get*` 。 如果 `resp` 是 `nil` ,那么响应会被忽略。 如果向指定请求 host 的所有 `DefaultMaxConnsPerHost` 数量的连接都被占用,那么会返回 `ErrNoFreeConns`。 在有性能要求的代码中,推荐通过 `AcquireRequest` 和 `AcquireResponse` 来获取 `req` 和 `resp` 。 ### func EqualBytesStr ```go func EqualBytesStr(b []byte, s string) bool ``` `EqualBytesStr`,在 `string(b) == s` 时返回 `true`。 这个函数与 `string(b) == s` 的性能没有差别。目前它仅用于向后兼容。 这个函数已经弃用并且可能很快被移除。 ### func FileLastModified ```go func FileLastModified(path string) (time.Time, error) ``` `FileLastModified` 返回文件的最后修改时间。 ### func Get ```go func Get(dst []byte, url string) (statusCode int, body []byte, err error) ``` `Get` 向 `dst` 追加 url 信息,并且通过 `body` 返回它。 这个函数会跟随重定向。若要手动操作重定向,请使用 `Do*` 。 如果 `dst` 为 `nil` ,那么则会分配一个新的 `body` 缓冲。 ### func GetDeadline ```go func GetDeadline(dst []byte, url string, deadline time.Time) (statusCode int, body []byte, err error) ``` `GetDeadline` 向 `dst` 追加 url 信息,并且通过 `body` 返回它。 这个函数会跟随重定向。若要手动操作重定向,请使用 `Do*` 。 如果 `dst` 为 `nil` ,那么则会分配一个新的 `body` 缓冲。 若在指定的 deadline 之前没能获取到响应,那么会返回 `ErrTimeout` 。 ### func GetTimeout ```go func GetTimeout(dst []byte, url string, timeout time.Duration) (statusCode int, body []byte, err error) ``` `GetTimeout` 向 `dst` 追加 url 信息,并且通过 `body` 返回它。 这个函数会跟随重定向。若要手动操作重定向,请使用 `Do*` 。 如果 `dst` 为 `nil` ,那么则会分配一个新的 `body` 缓冲。 若在指定的超时之前没能获取到响应,那么会返回 `ErrTimeout` 。 ### func ListenAndServe ```go func ListenAndServe(addr string, handler RequestHandler) error ``` `ListenAndServe` 使用指定的 `handler` 处理来自指定 TCP 地址 `addr` 的 HTTP 请求。 例子: ```go // 这个服务器会监听所有来自该地址的请求 listenAddr := "127.0.0.1:80" // 当每个请求到来时,这个函数都将被调用。 // RequestCtx 提供了很多有用的处理 http 请求的方法。更多详情请参阅 RequestCtx 说明。 requestHandler := func(ctx *fasthttp.RequestCtx) { fmt.Fprintf(ctx, "Hello, world! Requested path is %q", ctx.Path()) } // 使用默认设置启动服务器。 // 创建服务器实例。 // // ListenAndServe 只返回一个错误,所以它通常是永久阻塞的。 if err := fasthttp.ListenAndServe(listenAddr, requestHandler); err != nil { log.Fatalf("error in ListenAndServe: %s", err) } ``` ### func ListenAndServeTLS ```go func ListenAndServeTLS(addr, certFile, keyFile string, handler RequestHandler) error ``` `ListenAndServeTLS` 使用指定的 `handler` 处理来自指定 TCP 地址 `addr` 的 HTTPS 请求。 `certFile` 和 `keyFile` 是 TLS 证书和密钥文件的路径。 ### func ListenAndServeTLSEmbed ```go func ListenAndServeTLSEmbed(addr string, certData, keyData []byte, handler RequestHandler) error ``` `ListenAndServeTLSEmbed` 使用指定的 `handler` 处理来自指定 TCP 地址 `addr` 的 HTTPS 请求。 `certData` 和 `keyData` 必须包含合法的 TLS 证书和密钥数据。 ### func ListenAndServeUNIX ```go func ListenAndServeUNIX(addr string, mode os.FileMode, handler RequestHandler) error ``` `ListenAndServeUNIX` 使用指定的 `handler` 处理来自指定 UNIX 地址 `addr` 的 HTTP 请求。 这个函数会在开始接受请求前删除所有 `addr` 下的文件。 该函数会为制定 UNIX 地址 `addr` 设置参数中指定的 `mode` 。 ### func NewStreamReader ```go func NewStreamReader(sw StreamWriter) io.ReadCloser ``` `NewStreamReader` 返回一个 `reader` ,用于获取所有由 `sw` 生成的数据。 返回的 `reader` 可以被传递至 `Response.SetBodyStream` 。 在返回的 `reader` 中所有的数据都被读取完毕之后,必须调用 `Close` 。否则可能会造成 goroutine 泄露。 更多详情可参阅 `Response.SetBodyStreamWriter` 。 ### func ParseByteRange ```go func ParseByteRange(byteRange []byte, contentLength int) (startPos, endPos int, err error) ``` `ParseByteRange` 用于解释 `'Range: bytes=...'` 头的值。 依据的规范是 https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35 。 ### func ParseHTTPDate ```go func ParseHTTPDate(date []byte) (time.Time, error) ``` `ParseHTTPDate` 用于解释符合 HTTP-compliant (RFC1123) 规范的时间。 ### func ParseIPv4 ```go func ParseIPv4(dst net.IP, ipStr []byte) (net.IP, error) ``` `ParseIPv4` 解释 `ipStr` 提供的 ip 地址,并填充 `dst` ,然后返回填充后的 `dst` 。 ### func ParseUfloat ```go func ParseUfloat(buf []byte) (float64, error) ``` `ParseUfloat` 解释 `buf` 提供的无符号浮点数。 ### func ParseUint ```go func ParseUint(buf []byte) (int, error) ``` `ParseUint` 解释 `buf` 提供的无符号整型数。 ### func Post ```go func Post(dst []byte, url string, postArgs *Args) (statusCode int, body []byte, err error) ``` `Post` 使用指定 POST 参数向指定 `url` 发出 POST 请求。 请求体会追加值 `dst` ,并且通过 `body` 返回。 这个函数会跟随重定向。若要手动操作重定向,请使用 `Do*` 。 若 `dst` 是 `nil` ,那么新的 `body` 缓冲会被分配。 如果 `postArgs` 是 `nil` ,则发送空 POST 请求体。 ### func ReleaseArgs ```go func ReleaseArgs(a *Args) ``` `ReleaseArgs` 向池中释放通过 `AquireArgs` 取得的对象。 不要试图访问释放的 `Args` 对象,可能会产生数据竞争。 ### func ReleaseByteBuffer ```go func ReleaseByteBuffer(b *ByteBuffer) ``` `ReleaseByteBuffer` 返回池中释放指定字节缓冲。 在释放回池之后, `ByteBuffer.B` 不能再被访问,可能会产生数据竞争。 ### func ReleaseCookie ```go func ReleaseCookie(c *Cookie) ``` `ReleaseCookie` 向池中释放由 `AcquireCookie` 返回的对象。 不要试图访问释放的 `Cookie` 对象,可能会产生数据竞争。 ### func ReleaseRequest ```go func ReleaseRequest(req *Request) ``` `ReleaseRequest` 向池中释放由 `AcquireRequest` 返回的对象。 在释放回池之后,禁止再访问 `req` 对象以及它的任何成员。 ### func ReleaseResponse ```go func ReleaseResponse(resp *Response) ``` `ReleaseResponse` 向池中释放由 `AcquireResponse` 返回的对象。 在释放回池之后,禁止再访问 `resp` 对象以及它的任何成员。 ### func ReleaseURI ```go func ReleaseURI(u *URI) ``` `ReleaseURI` 向池中释放由 `AcquireURI` 返回的对象。 不要试图访问释放的 `URI` 对象,可能会产生数据竞争。 ### func SaveMultipartFile ```go func SaveMultipartFile(fh *multipart.FileHeader, path string) error ``` `SaveMultipartFile` 在指定的 `path` 下保存文件 `fh` 。 ### func Serve ```go func Serve(ln net.Listener, handler RequestHandler) error ``` `Serve` 使用指定的 `handler` 来处理来自 `listener` 的连接。 在 `listener` 返回永久性的错误之前, `Serve` 都会一直保持阻塞。 例子: ```go // 创建一个接受请求的 listener // // 你不仅可以创建 TCP listener - 任意的 net.Listener 都可以。 // 例如 UNIX Socket 或 TLS listener 。 ln, err := net.Listen("tcp4", "127.0.0.1:8080") if err != nil { log.Fatalf("error in net.Listen: %s", err) } // 当每个请求到来时,这个函数都将被调用。 // RequestCtx 提供了很多有用的处理 http 请求的方法。更多详情请参阅 RequestCtx 说明。 requestHandler := func(ctx *fasthttp.RequestCtx) { fmt.Fprintf(ctx, "Hello, world! Requested path is %q", ctx.Path()) } // 使用默认设置启动服务器。 // 创建服务器实例。 // // Serve 在 ln.Close() 或发生错误时返回,所以它通常是永久阻塞的。 if err := fasthttp.Serve(ln, requestHandler); err != nil { log.Fatalf("error in Serve: %s", err) } ``` ### func ServeConn ```go func ServeConn(c net.Conn, handler RequestHandler) error ``` `ServeConn` 使用指定的 `handler` 处理来自指定连接的 HTTP 请求。 如果所有来自 `c` 的请求都被成功处理,`ServeConn` 会返回 `nil` 。否则返回一个非空错误。 连接 `c` 必须立刻将所有数据通过 `Write()` 发送至客户端,否则请求的处理可能会被挂起。 `ServeConn` 在返回之前会关闭 `c` 。 ### func ServeFile ```go func ServeFile(ctx *RequestCtx, path string) ``` `ServeFile` 返回来自指定 `path` 的压缩后文件内容的 HTTP 响应。 在以下情况下,HTTP 响应可能会包含未压缩文件内容: - 缺少 `'Accept-Encoding: gzip'` 请求头。 - 没有对文件目录的写权限。 如果 `path` 指向一个目录,那么目录的内容会被返回。 如果你不需要响应压缩后的文件内容,请使用 `ServeFileUncompressed` 。 更多详情可参阅 `RequestCtx.SendFile` 。 ### func ServeFileBytes ```go func ServeFileBytes(ctx *RequestCtx, path []byte) ``` `ServeFileBytes` 返回来自指定 `path` 的压缩后文件内容的 HTTP 响应。 在以下情况下,HTTP 响应可能会包含未压缩文件内容: - 缺少 `'Accept-Encoding: gzip'` 请求头。 - 没有对文件目录的写权限。 如果 `path` 指向一个目录,那么目录的内容会被返回。 如果你不需要响应压缩后的文件内容,请使用 `ServeFileUncompressed` 。 更多详情可参阅 `RequestCtx.SendFile` 。 ### func ServeFileBytesUncompressed ```go func ServeFileBytesUncompressed(ctx *RequestCtx, path []byte) ``` `ServeFileBytesUncompressed` 返回来自指定 `path` 文件内容的 HTTP 响应。 如果 `path` 指向一个目录,那么目录的内容会被返回。 若需要处理压缩后的文件,请使用 `ServeFileBytes` 。 更多详情可参阅 `RequestCtx.SendFileBytes` 。 ### func ServeFileUncompressed ```go func ServeFileUncompressed(ctx *RequestCtx, path string) ``` `ServeFileUncompressed` 返回来自指定 `path` 文件内容的 HTTP 响应。 如果 `path` 指向一个目录,那么目录的内容会被返回。 若需要处理压缩后的文件,请使用 `ServeFile` 。 更多详情可参阅 `RequestCtx.SendFile` 。 ### func ServeTLS ```go func ServeTLS(ln net.Listener, certFile, keyFile string, handler RequestHandler) error ``` `ServeTLS` 使用指定的 `handler` 来处理来自指定 `net.Listener` 的 HTTPS 请求。 `certFile` 和 `keyFile` 是 TLS 证书和密钥文件的路径。 ### func ServeTLSEmbed ```go func ServeTLSEmbed(ln net.Listener, certData, keyData []byte, handler RequestHandler) error ``` `ServeTLSEmbed` 使用指定的 `handler` 来处理来自指定 `net.Listener` 的 HTTPS 请求。 `certData` 和 `keyData` 必须包含合法的 TLS 证书和密钥数据。 ### func StatusMessage ```go func StatusMessage(statusCode int) string ``` `StatusMessage` 根据指定的状态码返回 HTTP 状态信息。 ### func WriteGunzip ```go func WriteGunzip(w io.Writer, p []byte) (int, error) ``` `WriteGunzip` 向 `w` 写入经 gunzip 压缩的 `p` ,并且返回未压缩的字节数。 ### func WriteGzip ```go func WriteGzip(w io.Writer, p []byte) (int, error) ``` `WriteGunzip` 向 `w` 写入经 gzip 压缩的 `p` ,并且返回未压缩的字节数。 ### func WriteGzipLevel ```go func WriteGzipLevel(w io.Writer, p []byte, level int) (int, error) ``` `WriteGunzip` 向 `w` 写入经指定级别 gzip 压缩的 `p` ,并且返回未压缩的字节数。 支持的压缩级别有: - `CompressNoCompression` - `CompressBestSpeed` - `CompressBestCompression` - `CompressDefaultCompression` ### func WriteInflate ```go func WriteInflate(w io.Writer, p []byte) (int, error) ``` `WriteGunzip` 向 `w` 写入压缩后的 `p` ,并且返回未压缩的字节数。 ### func WriteMultipartForm ```go func WriteMultipartForm(w io.Writer, f *multipart.Form, boundary string) error ``` `WriteMultipartForm` 使用指定的 `w` 写入指定的表单 `f` 。 ### type Args ```go type Args struct { // 包含被过滤或未导出的属性 } ``` `Args` 代表查询字符串参数。 拷贝 `Args` 实例是禁止的。你需要使用 `CopyTo()` 函数或创建一个新实例。 `Args` 实例必须不能在并发执行的 goroutine 间使用。 #### func AcquireArgs ```go func AcquireArgs() *Args ``` `AcquireArgs` 从池中返回一个空的 `Args` 对象。 返回的 `Args` 实例在不再需要时可以通过 `ReleaseArgs` 释放回池。这可以降低垃圾回收负载。 #### func (*Args) Add ```go func (a *Args) Add(key, value string) ``` `Add` 添加 `'key=value'` 参数。 同一个 `key` 可以添加多个值。 #### func (*Args) AddBytesK ```go func (a *Args) AddBytesK(key []byte, value string) ``` `AddBytesK` 添加 `'key=value'` 参数。 同一个 `key` 可以添加多个值。 #### func (*Args) AddBytesKV ```go func (a *Args) AddBytesKV(key, value []byte) ``` `AddBytesKV` 添加 `'key=value'` 参数。 同一个 `key` 可以添加多个值。 #### func (*Args) AddBytesV ```go func (a *Args) AddBytesV(key string, value []byte) ``` `AddBytesV` 添加 `'key=value'` 参数。 同一个 `key` 可以添加多个值。 #### func (*Args) AppendBytes ```go func (a *Args) AppendBytes(dst []byte) []byte ``` `AppendBytes` 像 `dst` 追加查询字符串,并返回 `dst` 。 #### func (*Args) CopyTo ```go func (a *Args) CopyTo(dst *Args) ``` `CopyTo` 将所有的参数复制至 `dst` 。 #### func (*Args) Del ```go func (a *Args) Del(key string) ``` `Del` 删除键为指定 `key` 的参数。 #### func (*Args) DelBytes ```go func (a *Args) DelBytes(key []byte) ``` `Del` 删除键为指定 `key` 的参数。 #### func (*Args) GetUfloat ```go func (a *Args) GetUfloat(key string) (float64, error) ``` `GetUfloat` 返回指定 `key` 的无符号浮点数值。 #### func (*Args) GetUfloatOrZero ```go func (a *Args) GetUfloatOrZero(key string) float64 ``` `GetUfloatOrZero` 返回指定 `key` 的无符号浮点数值。 当出错时返回 `0` 。 #### func (*Args) GetUint ```go func (a *Args) GetUint(key string) (int, error) ``` `GetUint` 返回指定 `key` 的无符号整型数值。 #### func (*Args) GetUintOrZero ```go func (a *Args) GetUintOrZero(key string) int ``` `GetUintOrZero` 返回指定 `key` 的无符号整型数值。 当出错时返回 `0` 。 #### func (*Args) Has ```go func (a *Args) Has(key string) bool ``` `Has` 在当 `Args` 中存在指定 `key` 时返回 `true` 。 #### func (*Args) HasBytes ```go func (a *Args) HasBytes(key []byte) bool ``` `HasBytes` 在当 `Args` 中存在指定 `key` 时返回 `true` 。 #### func (*Args) Len ```go func (a *Args) Len() int ``` `Len` 查询参数的数量。 #### func (*Args) Parse ```go func (a *Args) Parse(s string) ``` `Parse` 解析包含查询参数的字符串。 #### func (*Args) ParseBytes ```go func (a *Args) ParseBytes(b []byte) ``` `ParseBytes` 解析包含查询参数的 `b`。 #### func (*Args) Peek ```go func (a *Args) Peek(key string) []byte ``` `Peek` 返回查询参数中指定 `key` 的值。 #### func (*Args) PeekBytes ```go func (a *Args) PeekBytes(key []byte) []byte ``` `PeekBytes` 返回查询参数中指定 `key` 的值。 #### func (*Args) PeekMulti ```go func (a *Args) PeekMulti(key string) [][]byte ``` `PeekMulti` 返回查询参数中指定 `key` 的所有值。 #### func (*Args) PeekMultiBytes ```go func (a *Args) PeekMultiBytes(key []byte) [][]byte ``` `PeekMultiBytes` 返回查询参数中指定 `key` 的所有值。 #### func (*Args) QueryString ```go func (a *Args) QueryString() []byte ``` `QueryString` 返回查询参数的字符串表示。 在下个 `Args` 方法调用之前,返回值都是合法的。 #### func (*Args) Reset ```go func (a *Args) Reset() ``` `Reset` 清除所有查询参数。 #### func (*Args) Set ```go func (a *Args) Set(key, value string) ``` `Set` 设置 `'key=value'` 参数。 #### func (*Args) SetBytesK ```go func (a *Args) SetBytesK(key []byte, value string) ``` `SetBytesK` 设置 `'key=value'` 参数。 #### func (*Args) SetBytesKV ```go func (a *Args) SetBytesKV(key, value []byte) ``` `SetBytesKV` 设置 `'key=value'` 参数。 #### func (*Args) SetBytesV ```go func (a *Args) SetBytesV(key string, value []byte) ``` `SetBytesV` 设置 `'key=value'` 参数。 #### func (*Args) SetUint ```go func (a *Args) SetUint(key string, value int) ``` `SetUint` 为指定 `key` 设置无符号整数值。 #### func (*Args) SetUintBytes ```go func (a *Args) SetUintBytes(key []byte, value int) ``` `SetUintBytes` 为指定 `key` 设置无符号整数值。 #### func (*Args) String ```go func (a *Args) String() string ``` `String` 返回查询参数的字符串表示。 #### func (*Args) VisitAll ```go func (a *Args) VisitAll(f func(key, value []byte)) ``` `VisitAll` 对每一个存在的参数调用 `f` 。 `f` 在返回后必须不能保留对键和值的引用。若要在返回后扔需要存储它们,请存储它们的副本。 #### func (*Args) WriteTo ```go func (a *Args) WriteTo(w io.Writer) (int64, error) ``` `WriteTo` 向 `w` 写入查询字符串。 `WriteTo` 实现了 `io.WriterTo` 接口。 ### type Client ```go type Client struct { // 客户端名字。在 User-Agent 请求头中会被使用到。 // // 如果未被设置,则会使用默认客户端名。 Name string // 建立到指定 host 的新连接后的回调函数。 // // 如果未被设置,则会使用默认 Dial 函数。 Dial DialFunc // 若被设为 true ,则会试图连接 ipv4 和 ipv6 的地址。 // // 这个选项仅在使用默认 TCP dialer 时有效, // 例如:Dial 为空。 // // 默认情况下客户端仅会连接 ipv4 地址, // 因为 ipv6 在世界上的大多数网络中都仍然不可用 :) DialDualStack bool // HTTPS 连接的 TLS 配置。 // 如果未被设置,则使用默认的 TLS 配置。 TLSConfig *tls.Config // 每个 host 可以被建立的最大连接数。 // // 如果未被设置,则使用默认的 DefaultMaxConnsPerHost 。 MaxConnsPerHost int // 在这个时间间隔后,空闲的 keep-alive 连接会被关闭。 // 默认值为 DefaultMaxIdleConnDuration 。 MaxIdleConnDuration time.Duration // 每个连接响应读取时的缓冲大小。 // 这个值也限制了最大头大小。 // // 默认值为 0 。 ReadBufferSize int // 每个连接请求写入时的缓冲大小。 // // 默认值为 0 。 WriteBufferSize int // 完整的响应读取(包含响应体)可用的最大时间。 // // 默认为无限制。 ReadTimeout time.Duration // 完整的请求写入(包含请求体)可用的最大时间。 // // 默认为无限制。 WriteTimeout time.Duration // 相应体的最大大小。 // // 当该值大于 0 ,且相应体超过它时,客户端返回 ErrBodyTooLarge 。 // 默认为无限制。 MaxResponseBodySize int DisableHeaderNamesNormalizing bool // 包含被过滤或未导出的属性 } ``` `Client` 实现了 HTTP 客户端。 不允许按值拷贝 `Client` ,应该创建一个新的实例。 在多个运行的 goroutine 间调用 `Client` 方法是安全的。 #### func (*Client) Do ```go func (c *Client) Do(req *Request, resp *Response) error ``` `Do` 发出指定的 http 请求,在得到响应后并且填充指定的 http 响应对象。 请求必须至少包含一个非空的 RequestURI (包含协议和 host)或非空的 Host 头 + RequestURI。 客户端以以下顺序确定待请求的服务端: - 如果 RequestURI 包含完整的带有协议和 host 的 url ,则从 RequestURI 中取得。 - 否则就从 Host 头中取得。 如果 `resp` 是 `nil` ,那么响应会被忽略。 这个函数不会跟随重定向。若要跟随重定向,请使用 `Get*` 。 如果向指定请求 host 的所有 `DefaultMaxConnsPerHost` 数量的连接都被占用,那么会返回 `ErrNoFreeConns`。 在有性能要求的代码中,推荐通过 `AcquireRequest` 和 `AcquireResponse` 来获取 `req` 和 `resp` 。 #### func (*Client) DoDeadline ```go func (c *Client) DoDeadline(req *Request, resp *Response, deadline time.Time) error ``` `DoDeadline` 发出指定的 http 请求,并且在指定的 deadline 之前得到响应后填充指定的 http 响应对象。 请求必须至少包含一个非空的 RequestURI (包含协议和 host)或非空的 Host 头 + RequestURI。 客户端以以下顺序确定待请求的服务端: - 如果 RequestURI 包含完整的带有协议和 host 的 url ,则从 RequestURI 中取得。 - 否则就从 Host 头中取得。 这个函数不会跟随重定向。若要跟随重定向,请使用 `Get*` 。 如果 `resp` 是 `nil` ,那么响应会被忽略。 如果向指定请求 host 的所有 `DefaultMaxConnsPerHost` 数量的连接都被占用,那么会返回 `ErrNoFreeConns`。 在有性能要求的代码中,推荐通过 `AcquireRequest` 和 `AcquireResponse` 来获取 `req` 和 `resp` 。 #### func (*Client) DoTimeout ```go func (c *Client) DoTimeout(req *Request, resp *Response, timeout time.Duration) error ``` `DoTimeout` 发出指定的 http 请求,并且在指定的超时之前得到响应后填充指定的 http 响应对象。 请求必须至少包含一个非空的 RequestURI (包含协议和 host)或非空的 Host 头 + RequestURI。 客户端以以下顺序确定待请求的服务端: - 如果 RequestURI 包含完整的带有协议和 host 的 url ,则从 RequestURI 中取得。 - 否则就从 Host 头中取得。 这个函数不会跟随重定向。若要跟随重定向,请使用 `Get*` 。 如果 `resp` 是 `nil` ,那么响应会被忽略。 如果向指定请求 host 的所有 `DefaultMaxConnsPerHost` 数量的连接都被占用,那么会返回 `ErrNoFreeConns`。 在有性能要求的代码中,推荐通过 `AcquireRequest` 和 `AcquireResponse` 来获取 `req` 和 `resp` 。 #### func (*Client) Get ```go func (c *Client) Get(dst []byte, url string) (statusCode int, body []byte, err error) ``` `Get` 向 `dst` 追加 url 信息,并且通过 `body` 返回它。 这个函数会跟随重定向。若要手动操作重定向,请使用 `Do*` 。 如果 `dst` 为 `nil` ,那么则会分配一个新的 `body` 缓冲。 #### func (*Client) GetDeadline ```go func (c *Client) GetDeadline(dst []byte, url string, deadline time.Time) (statusCode int, body []byte, err error) ``` `GetDeadline` 向 `dst` 追加 url 信息,并且通过 `body` 返回它。 这个函数会跟随重定向。若要手动操作重定向,请使用 `Do*` 。 如果 `dst` 为 `nil` ,那么则会分配一个新的 `body` 缓冲。 若在指定的 deadline 之前没能获取到响应,那么会返回 `ErrTimeout` 。 #### func (*Client) GetTimeout ```go func (c *Client) GetTimeout(dst []byte, url string, timeout time.Duration) (statusCode int, body []byte, err error) ``` `GetTimeout` 向 `dst` 追加 url 信息,并且通过 `body` 返回它。 这个函数会跟随重定向。若要手动操作重定向,请使用 `Do*` 。 如果 `dst` 为 `nil` ,那么则会分配一个新的 `body` 缓冲。 若在指定的超时之前没能获取到响应,那么会返回 `ErrTimeout` 。 #### func (*Client) Post ```go func (c *Client) Post(dst []byte, url string, postArgs *Args) (statusCode int, body []byte, err error) ``` `Post` 使用指定 POST 参数向指定 `url` 发出 POST 请求。 请求体会追加值 `dst` ,并且通过 `body` 返回。 这个函数会跟随重定向。若要手动操作重定向,请使用 `Do*` 。 若 `dst` 是 `nil` ,那么新的 `body` 缓冲会被分配。 如果 `postArgs` 是 `nil` ,则发送空 POST 请求体。 ### type Cookie ```go type Cookie struct { // 包含被过滤或未导出的属性 } ``` `Cookie` 代表 HTTP 相应的 cookie 。 不允许按值拷贝 `Cookie` ,应该创建一个新的实例。 在多个运行的 goroutine 间使用 `Cookie` 实例是禁止的。 #### func AcquireCookie ```go func AcquireCookie() *Cookie ``` `AcquireCookie` 从池中返回一个空的 `Cookie` 对象。 返回的 `Cookie` 实例在不再需要时可以通过 `ReleaseCookie` 释放回池。这可以降低垃圾回收负载。 #### func (*Cookie) AppendBytes ```go func (c *Cookie) AppendBytes(dst []byte) []byte ``` `AppendBytes` 向 `dst` 追加 cookie ,并且返回追加后的 `dst` 。 #### func (*Cookie) Cookie ```go func (c *Cookie) Cookie() []byte ``` `Cookie` 返回 cookie 的表示。 直到下次调用 `Cookie` 方法前,返回值都是合法的。 #### func (*Cookie) CopyTo ```go func (c *Cookie) CopyTo(src *Cookie) ``` `CopyTo` 拷贝 `src` cookie 至 `c` 。 #### func (*Cookie) Domain ```go func (c *Cookie) Domain() []byte ``` `Domain` 返回 cookie 的 domain 值。 直到下次调用会改变 `Cookie` 的方法前,返回值都是合法的。 #### func (*Cookie) Expire ```go func (c *Cookie) Expire() time.Time ``` `Expire` 返回 cookie 的过期时间。 若没设置过期,则返回 `CookieExpireUnlimited` 。 #### func (*Cookie) HTTPOnly ```go func (c *Cookie) HTTPOnly() bool ``` `HTTPOnly` 在 cookie 为 http only 时返回 `true` 。 #### func (*Cookie) Key ```go func (c *Cookie) Key() []byte ``` `Key` 返回 cookie 名字。 直到下次调用会改变 `Cookie` 的方法前,返回值都是合法的。 #### func (*Cookie) Parse ```go func (c *Cookie) Parse(src string) error ``` `Parse` 解析 Set-Cookie 头。 #### func (*Cookie) ParseBytes ```go func (c *Cookie) ParseBytes(src []byte) error ``` `ParseBytes` 解析 Set-Cookie 头。 #### func (*Cookie) Path ```go func (c *Cookie) Path() []byte ``` `Path` 返回 cookie path 。 #### func (*Cookie) Reset ```go func (c *Cookie) Reset() ``` `Reset` 清空该 cookie 。 #### func (*Cookie) Secure ```go func (c *Cookie) Secure() bool ``` `Secure` 在当 cookie 为 secure 时返回 `true` 。 #### func (*Cookie) SetDomain ```go func (c *Cookie) SetDomain(domain string) ``` `SetDomain` 设置 cookie 的 domain 。 #### func (*Cookie) SetDomainBytes ```go func (c *Cookie) SetDomainBytes(domain []byte) ``` `SetDomainBytes` 设置 cookie 的 domain 。 #### func (*Cookie) SetExpire ```go func (c *Cookie) SetExpire(expire time.Time) ``` `SetExpire` 设置 cookie 的过期时间。 若要使该 cookie 在客户端过期,则将值设置为 `CookieExpireDelete` 。 默认情况下 cookie 的寿命由浏览器会话限制。 #### func (*Cookie) SetHTTPOnly ```go func (c *Cookie) SetHTTPOnly(httpOnly bool) ``` `SetHTTPOnly` 将 cookie 的 httpOnly 标识设置为指定值。 #### func (*Cookie) SetKey ```go func (c *Cookie) SetKey(key string) ``` `SetKey` 设置 cookie 名。 #### func (*Cookie) SetKeyBytes ```go func (c *Cookie) SetKeyBytes(key []byte) ``` `SetKeyBytes` 设置 cookie 名。 #### func (*Cookie) SetPath ```go func (c *Cookie) SetPath(path string) ``` `SetPath` 设置 cookie 路径。 #### func (*Cookie) SetPathBytes ```go func (c *Cookie) SetPathBytes(path []byte) ``` `SetPathBytes` 设置 cookie 路径。 #### func (*Cookie) SetSecure ```go func (c *Cookie) SetSecure(secure bool) ``` `SetSecure` 将 cookie 的 secure 标识设置为指定值。 #### func (*Cookie) SetValue ```go func (c *Cookie) SetValue(value string) ``` `SetValue` 设置 cookie 的值。 #### func (*Cookie) SetValueBytes ```go func (c *Cookie) SetValueBytes(value []byte) ``` `SetValueBytes` 设置 cookie 的值。 #### func (*Cookie) String ```go func (c *Cookie) String() string ``` `String` 返回 cookie 的字符串表示。 #### func (*Cookie) Value ```go func (c *Cookie) Value() []byte ``` `Value` 返回 cookie 的值。 直到下次调用会改变 `Cookie` 的方法前,返回值都是合法的。 #### func (*Cookie) WriteTo ```go func (c *Cookie) WriteTo(w io.Writer) (int64, error) ``` `WriteTo` 将 cookie 的字符串表示写入 `w` 。 `WriteTo` 实现了 `io.WriterTo` 接口。 ### type DialFunc ```go type DialFunc func(addr string) (net.Conn, error) ``` `DialFunc` 必须建立到 `addr` 的连接。 没有必要为 HTTPS 建立到 TLS(SSL)的连接。若 `HostClient.IsTLS` 被设置,则客户端会自动转换连接至 TLS 。 TCP address passed to DialFunc always contains host and port. Example TCP addr values: 传递至 `DialFunc` 的 TCP 地址总是包含 host 和端口。例子: - `foobar.com:80` - `foobar.com:443` - `foobar.com:8080` ### type FS ```go type FS struct { // 用于响应文件的根目录 Root string // 目录中的索引文件名。 // // 例子: // // * index.html // * index.htm // * my-super-index.xml // // 默认为空。 IndexNames []string GenerateIndexPages bool // 若设为 true ,则压缩响应。 // // 服务器会通过缓存来最小化 CPU 的使用。 // 新的缓存文件名字会添加 `CompressedFileSuffix` 前缀。 // 所以建议使服务器对 Root 目录以及子目录有写权限。 Compress bool // 若被设为 true ,则启用字节范围请求 // // 默认为 false 。 AcceptByteRange bool // 重写路径函数。 // // 默认为不改变请求路径。 PathRewrite PathRewriteFunc // 非活跃的文件句柄的过期时间间隔。 // // 默认为 `FSHandlerCacheDuration` 。 CacheDuration time.Duration // 为缓存的压缩文件添加的前缀。 // // 这个值仅在 Compress 被设置时才有效。 // // 默认为 FSCompressedFileSuffix 。 CompressedFileSuffix string // 包含被过滤或未导出的属性 } ``` `FS` 代表了通过本地文件系统来响应静态文件 HTTP 请求的设置。 不允许复制 `FS` 值,应该创建新的 `FS` 值。 例子: ```go fs := &fasthttp.FS{ // 响应静态文件请求的目录 Root: "/var/www/static-site", // 生成索引 GenerateIndexPages: true, // 开启压缩,用于节省带宽 Compress: true, } // 创建响应静态文件的 handler h := fs.NewRequestHandler() // 启动服务器 if err := fasthttp.ListenAndServe(":8080", h); err != nil { log.Fatalf("error in ListenAndServe: %s", err) } ``` #### func (*FS) NewRequestHandler ```go func (fs *FS) NewRequestHandler() RequestHandler ``` `NewRequestHandler` 通过指定的 `FS` 设置返回新的请求 handler 。 返回的 handler 根据 `FS.CacheDuration` 来缓存请求的文件句柄。若 `FS.Root` 目录包含大量文件,请确保你的程序通过 `'ulimit -n'` 来保证有足够的“可打开文件”。 不需要对单个 `FS` 实例创建多个请求 handler ,只需重用即可。 ### type HijackHandler ```go type HijackHandler func(c net.Conn) ``` `HijackHandler` 必须处理拦截的连接 `c` 。 在 `HijackHandler` 返回后连接 `c` 会被自动关闭。 在 `HijackHandler` 返回后连接 `c` 必须不可再被使用。 ### type HostClient ```go type HostClient struct { // 以逗号分隔的上游 HTTP 服务器 host 地址列表,通过轮询传递给 Dial // // 如果默认的 dialer 被使用,每一个地址都需要包含端口。 // 例子: // // - foobar.com:80 // - foobar.com:443 // - foobar.com:8080 Addr string // 客户端名,用于 User-Agent 请求头。 Name string // 建立到指定 host 的新连接后的回调函数。 // // 如果未被设置,则会使用默认 Dial 函数。 Dial DialFunc // 若被设为 true ,则会试图连接 ipv4 和 ipv6 的地址。 // // 这个选项仅在使用默认 TCP dialer 时有效, // 例如:Dial 为空。 // // 默认情况下客户端仅会连接 ipv4 地址, // 因为 ipv6 在世界上的大多数网络中都仍然不可用 :) DialDualStack bool // 是否使用 TLS 。 IsTLS bool // 可选的 TLS 配置。 TLSConfig *tls.Config // 每个 host 可以被建立的最大连接数。 // // 如果未被设置,则使用默认的 DefaultMaxConnsPerHost 。 MaxConns int // 在这个时间间隔后, keep-alive 连接会被关闭。 // 默认值为无限制。 MaxConnDuration time.Duration // 在这个时间间隔后,空闲的 keep-alive 连接会被关闭。 // 默认值为 DefaultMaxIdleConnDuration 。 MaxIdleConnDuration time.Duration // 每个连接响应读取时的缓冲大小。 // 这个值也限制了最大头大小。 // // 默认值为 0 。 ReadBufferSize int // 每个连接请求写入时的缓冲大小。 // // 默认值为 0 。 WriteBufferSize int // 完整的响应读取(包含响应体)可用的最大时间。 // // 默认为无限制。 ReadTimeout time.Duration // 完整的请求写入(包含请求体)可用的最大时间。 // // 默认为无限制。 WriteTimeout time.Duration // 相应体的最大大小。 // // 当该值大于 0 ,且相应体超过它时,客户端返回 ErrBodyTooLarge 。 // 默认为无限制。 MaxResponseBodySize int DisableHeaderNamesNormalizing bool // 包含被过滤或未导出的属性 } ``` `HostClient` 均衡地向列于 `Addr` 中的 host 发起请求。 禁止拷贝 `HostClient` 实例。应使用创建新的实例。 在多个运行的 goroutine 间执行 `HostClient` 方法是安全的。 例子: ```go package main import ( "log" "github.com/valyala/fasthttp" ) func main() { // 准备一个客户端,用于通过监听于 localhost:8080 的 HTTP 代理获取网页 c := &fasthttp.HostClient{ Addr: "localhost:8080", } // 使用本地代理获取谷歌页面。 statusCode, body, err := c.Get(nil, "http://google.com/foo/bar") if err != nil { log.Fatalf("Error when loading google page through local proxy: %s", err) } if statusCode != fasthttp.StatusOK { log.Fatalf("Unexpected status code: %d. Expecting %d", statusCode, fasthttp.StatusOK) } useResponseBody(body) // 通过本地代理获取 foobar 页面。重用 body 缓冲。 statusCode, body, err = c.Get(body, "http://foobar.com/google/com") if err != nil { log.Fatalf("Error when loading foobar page through local proxy: %s", err) } if statusCode != fasthttp.StatusOK { log.Fatalf("Unexpected status code: %d. Expecting %d", statusCode, fasthttp.StatusOK) } useResponseBody(body) } func useResponseBody(body []byte) { // 处理 body } ``` #### func (*HostClient) Do ```go func (c *HostClient) Do(req *Request, resp *Response) error ``` `Do` 发出指定的 http 请求,在得到响应后并且填充指定的 http 响应对象。 请求必须至少包含一个非空的 RequestURI (包含协议和 host)或非空的 Host 头 + RequestURI。 客户端以以下顺序确定待请求的服务端: - 如果 RequestURI 包含完整的带有协议和 host 的 url ,则从 RequestURI 中取得。 - 否则就从 Host 头中取得。 这个函数不会跟随重定向。若要跟随重定向,请使用 `Get*` 。 如果 `resp` 是 `nil` ,那么响应会被忽略。 如果向指定请求 host 的所有 `DefaultMaxConnsPerHost` 数量的连接都被占用,那么会返回 `ErrNoFreeConns`。 在有性能要求的代码中,推荐通过 `AcquireRequest` 和 `AcquireResponse` 来获取 `req` 和 `resp` 。 #### func (*HostClient) DoDeadline ```go func (c *HostClient) DoDeadline(req *Request, resp *Response, deadline time.Time) error ``` `DoDeadline` 发出指定的 http 请求,并且在指定的 deadline 之前得到响应后填充指定的 http 响应对象。 请求必须至少包含一个非空的 RequestURI (包含协议和 host)或非空的 Host 头 + RequestURI。 客户端以以下顺序确定待请求的服务端: - 如果 RequestURI 包含完整的带有协议和 host 的 url ,则从 RequestURI 中取得。 - 否则就从 Host 头中取得。 这个函数不会跟随重定向。若要跟随重定向,请使用 `Get*` 。 如果 `resp` 是 `nil` ,那么响应会被忽略。 如果向指定请求 host 的所有 `DefaultMaxConnsPerHost` 数量的连接都被占用,那么会返回 `ErrNoFreeConns`。 在有性能要求的代码中,推荐通过 `AcquireRequest` 和 `AcquireResponse` 来获取 `req` 和 `resp` 。 #### func (*HostClient) DoTimeout ```go func (c *HostClient) DoTimeout(req *Request, resp *Response, timeout time.Duration) error ``` `DoTimeout` 发出指定的 http 请求,并且在指定的超时之前得到响应后填充指定的 http 响应对象。 请求必须至少包含一个非空的 RequestURI (包含协议和 host)或非空的 Host 头 + RequestURI。 客户端以以下顺序确定待请求的服务端: - 如果 RequestURI 包含完整的带有协议和 host 的 url ,则从 RequestURI 中取得。 - 否则就从 Host 头中取得。 这个函数不会跟随重定向。若要跟随重定向,请使用 `Get*` 。 如果 `resp` 是 `nil` ,那么响应会被忽略。 如果向指定请求 host 的所有 `DefaultMaxConnsPerHost` 数量的连接都被占用,那么会返回 `ErrNoFreeConns`。 在有性能要求的代码中,推荐通过 `AcquireRequest` 和 `AcquireResponse` 来获取 `req` 和 `resp` 。 #### func (*HostClient) Get ```go func (c *HostClient) Get(dst []byte, url string) (statusCode int, body []byte, err error) ``` `Get` 向 `dst` 追加 url 信息,并且通过 `body` 返回它。 这个函数会跟随重定向。若要手动操作重定向,请使用 `Do*` 。 如果 `dst` 为 `nil` ,那么则会分配一个新的 `body` 缓冲。 #### func (*HostClient) GetDeadline ```go func (c *HostClient) GetDeadline(dst []byte, url string, deadline time.Time) (statusCode int, body []byte, err error) ``` `GetDeadline` 向 `dst` 追加 url 信息,并且通过 `body` 返回它。 这个函数会跟随重定向。若要手动操作重定向,请使用 `Do*` 。 如果 `dst` 为 `nil` ,那么则会分配一个新的 `body` 缓冲。 若在指定的 deadline 之前没能获取到响应,那么会返回 `ErrTimeout` 。 #### func (*HostClient) GetTimeout ```go func (c *HostClient) GetTimeout(dst []byte, url string, timeout time.Duration) (statusCode int, body []byte, err error) ``` `GetTimeout` 向 `dst` 追加 url 信息,并且通过 `body` 返回它。 这个函数会跟随重定向。若要手动操作重定向,请使用 `Do*` 。 如果 `dst` 为 `nil` ,那么则会分配一个新的 `body` 缓冲。 若在指定的超时之前没能获取到响应,那么会返回 `ErrTimeout` 。 #### func (*HostClient) LastUseTime ```go func (c *HostClient) LastUseTime() time.Time ``` `LastUseTime` 返回客户端最后被使用的时间。 #### func (*HostClient) PendingRequests ```go func (c *HostClient) PendingRequests() int ``` `PendingRequests` 返回正在执行的请求数。 #### func (*HostClient) Post ```go func (c *HostClient) Post(dst []byte, url string, postArgs *Args) (statusCode int, body []byte, err error) ``` `Post` 使用指定 POST 参数向指定 `url` 发出 POST 请求。 请求体会追加值 `dst` ,并且通过 `body` 返回。 这个函数会跟随重定向。若要手动操作重定向,请使用 `Do*` 。 若 `dst` 是 `nil` ,那么新的 `body` 缓冲会被分配。 如果 `postArgs` 是 `nil` ,则发送空 POST 请求体。 ### type Logger ```go type Logger interface { // Printf 必须与 log.Printf 有相同的语义。 Printf(format string, args ...interface{}) } ``` `Logger` 被用于记录格式化信息日志。 ### type PathRewriteFunc ```go type PathRewriteFunc func(ctx *RequestCtx) []byte ``` `PathRewriteFunc` 必须返回基于 `ctx.Path()` 的新请求路径。 该函数用于在 `FS` 中转义当前请求路径至相对于 `FS.Root` 的相对路径。 处于安全原因,返回的路径中不允许包含 `'/../'` 子字符串。 ### func NewPathPrefixStripper ```go func NewPathPrefixStripper(prefixSize int) PathRewriteFunc ``` `NewPathPrefixStripper` 返回重写路径函数,返回移除的前缀大小。 例子: - prefixSize = 0, 原路径: "/foo/bar", 结果: "/foo/bar" - prefixSize = 3, 原路径: "/foo/bar", 结果: "o/bar" - prefixSize = 7, 原路径: "/foo/bar", 结果: "r" 返回的路径重写函数可能会被 `FS.PathRewrite` 使用。 ### func NewPathSlashesStripper ```go func NewPathSlashesStripper(slashesCount int) PathRewriteFunc ``` `NewPathSlashesStripper` 返回重写路径函数,返回移除的路径分隔符数量。 例子: - slashesCount = 0, 原路径: "/foo/bar", 结果: "/foo/bar" - slashesCount = 1, 原路径: "/foo/bar", 结果: "/bar" - slashesCount = 2, 原路径: "/foo/bar", 结果: "" 返回的路径重写函数可能会被 `FS.PathRewrite` 使用。 ### type PipelineClient ```go type PipelineClient struct { // 连接的 host 的地址 Addr string // 连接至 Addr 的最大并发数。 // // 默认为单连接。 MaxConns int // 单个连接至 Addr 的最大等待管道请求数量。 // // 默认为 DefaultMaxPendingRequests 。 MaxPendingRequests int // 在批量发送管道请求至服务器前的最大延时。 // // 默认为无延时。 MaxBatchDelay time.Duration /// 建立到指定 host 的新连接后的回调函数。 // // 如果未被设置,则会使用默认 Dial 函数。 Dial DialFunc // 若被设为 true ,则会试图连接 ipv4 和 ipv6 的地址。 // // 这个选项仅在使用默认 TCP dialer 时有效, // 例如:Dial 为空。 // // 默认情况下客户端仅会连接 ipv4 地址, // 因为 ipv6 在世界上的大多数网络中都仍然不可用 :) DialDualStack bool // 是否使用 TLS 。 IsTLS bool // 可选的 TLS 配置。 TLSConfig *tls.Config // 在这个时间间隔后,空闲的 keep-alive 连接会被关闭。 // 默认值为 DefaultMaxIdleConnDuration 。 MaxIdleConnDuration time.Duration // 每个连接响应读取时的缓冲大小。 // 这个值也限制了最大头大小。 // // 默认值为 0 。 ReadBufferSize int // 每个连接请求写入时的缓冲大小。 // // 默认值为 0 。 WriteBufferSize int // 完整的响应读取(包含响应体)可用的最大时间。 // // 默认为无限制。 ReadTimeout time.Duration // 完整的请求写入(包含请求体)可用的最大时间。 // // 默认为无限制。 WriteTimeout time.Duration // 用于记录客户端错误的日志记录器。 // // 默认为标准 log 库。 Logger Logger // 包含被过滤或未导出的属性 } ``` `PipelineClient` 通过一个指定的并发连接限制数,来发送请求。 这个客户端可能被用于高负载的 RPC 系统。更多详情参阅 https://en.wikipedia.org/wiki/HTTP_pipelining 。 禁止拷贝 `PipelineClient` 实例。应该创建新实例。 在运行的 goroutine 间调用 `PipelineClient` 方法是安全的。 #### func (*PipelineClient) Do ```go func (c *PipelineClient) Do(req *Request, resp *Response) error ``` `Do` 发出指定的 http 请求,在得到响应后并且填充指定的 http 响应对象。 请求必须至少包含一个非空的 RequestURI (包含协议和 host)或非空的 Host 头 + RequestURI。 客户端以以下顺序确定待请求的服务端: - 如果 RequestURI 包含完整的带有协议和 host 的 url ,则从 RequestURI 中取得。 - 否则就从 Host 头中取得。 这个函数不会跟随重定向。若要跟随重定向,请使用 `Get*` 。 如果 `resp` 是 `nil` ,那么响应会被忽略。 如果向指定请求 host 的所有 `DefaultMaxConnsPerHost` 数量的连接都被占用,那么会返回 `ErrNoFreeConns`。 在有性能要求的代码中,推荐通过 `AcquireRequest` 和 `AcquireResponse` 来获取 `req` 和 `resp` 。 #### func (*PipelineClient) DoDeadline ```go func (c *PipelineClient) DoDeadline(req *Request, resp *Response, deadline time.Time) error ``` `DoDeadline` 发出指定的 http 请求,并且在指定的 deadline 之前得到响应后填充指定的 http 响应对象。 请求必须至少包含一个非空的 RequestURI (包含协议和 host)或非空的 Host 头 + RequestURI。 客户端以以下顺序确定待请求的服务端: - 如果 RequestURI 包含完整的带有协议和 host 的 url ,则从 RequestURI 中取得。 - 否则就从 Host 头中取得。 这个函数不会跟随重定向。若要跟随重定向,请使用 `Get*` 。 如果 `resp` 是 `nil` ,那么响应会被忽略。 如果向指定请求 host 的所有 `DefaultMaxConnsPerHost` 数量的连接都被占用,那么会返回 `ErrNoFreeConns`。 在有性能要求的代码中,推荐通过 `AcquireRequest` 和 `AcquireResponse` 来获取 `req` 和 `resp` 。 #### func (*PipelineClient) DoTimeout ```go func (c *PipelineClient) DoTimeout(req *Request, resp *Response, timeout time.Duration) error ``` `DoTimeout` 发出指定的 http 请求,并且在指定的超时之前得到响应后填充指定的 http 响应对象。 请求必须至少包含一个非空的 RequestURI (包含协议和 host)或非空的 Host 头 + RequestURI。 客户端以以下顺序确定待请求的服务端: - 如果 RequestURI 包含完整的带有协议和 host 的 url ,则从 RequestURI 中取得。 - 否则就从 Host 头中取得。 这个函数不会跟随重定向。若要跟随重定向,请使用 `Get*` 。 如果 `resp` 是 `nil` ,那么响应会被忽略。 如果向指定请求 host 的所有 `DefaultMaxConnsPerHost` 数量的连接都被占用,那么会返回 `ErrNoFreeConns`。 在有性能要求的代码中,推荐通过 `AcquireRequest` 和 `AcquireResponse` 来获取 `req` 和 `resp` 。 #### func (*PipelineClient) PendingRequests ```go func (c *PipelineClient) PendingRequests() int ``` `PendingRequests` 返回正在执行的请求数。 ### type Request ```go type Request struct { // 请求头 // // 按值拷贝 Header 是禁止的。应使用指针。 Header RequestHeader // 包含被过滤或未导出的属性 } ``` `Request` 代表一个 HTTP 请求。 禁止拷贝 `Request` 实例。应该创建新实例或使用 `CopyTo` 。 `Request` 实例必须不能再多个运行的 goroutine 间使用。 #### func AcquireRequest ```go func AcquireRequest() *Request ``` `AcquireRequest` 从请求池中返回一个空的 `Request` 实例。 返回的 `Request` 实例在不再需要时可以通过 `ReleaseRequest` 释放回池。这可以降低垃圾回收负载。 #### func (*Request) AppendBody ```go func (req *Request) AppendBody(p []byte) ``` `AppendBody` 追加 `p` 至请求体。 在函数返回后重用 `p` 是安全的。 #### func (*Request) AppendBodyString

2 个评论

手速真快
哈哈,竟然用issue当blog

要回复文章请先登录注册