版本: v3.x

📦 Fiber

服务器启动

New

此方法创建一个新的 **App** 实例。创建新实例时，可以传递可选的 config。

签名
func New(config ...Config) *App

示例
// Default config
app := fiber.New()

// ...

配置

在创建新的 Fiber 实例时，可以传递一个可选的 Config。

示例
// Custom config
app := fiber.New(fiber.Config{
    CaseSensitive: true,
    StrictRouting: true,
    ServerHeader:  "Fiber",
    AppName: "Test App v1.0.1",
})

// ...

Config 字段

属性	类型	描述	默认值
AppName	`string`	设置日志和 Server 标头中使用的应用程序名称	`""`
BodyLimit	`int`	设置请求正文允许的最大大小。零或负值将回退到默认限制。如果大小超过配置的限制，它将发送 `413 - Request Entity Too Large` 响应。此限制也适用于通过 `net/http` 的适配器中间件运行 Fiber 时。	`4 * 1024 * 1024`
CaseSensitive	`bool`	启用时，`/Foo` 和 `/foo` 是不同的路由。禁用时，`/Foo` 和 `/foo` 被视为相同。	`false`
ColorScheme	`颜色`	您可以定义自定义颜色方案。它们将用于启动消息、路由列表和一些中间件。	`DefaultColors`
CompressedFileSuffixes	`map[string]string`	向原始文件名添加一个后缀，并尝试以新文件名保存生成的压缩文件。	`{"gzip": ".fiber.gz", "br": ".fiber.br", "zstd": ".fiber.zst"}`
Concurrency	`int`	最大并发连接数。	`256 * 1024`
DisableDefaultContentType	`bool`	如果为 true，则从响应中省略默认的 Content-Type 标头。	`false`
DisableDefaultDate	`bool`	如果为 true，则从响应中省略 Date 标头。	`false`
DisableHeaderNormalizing	`bool`	默认情况下，所有标头名称都会被规范化：conteNT-tYPE -> Content-Type	`false`
DisableKeepalive	`bool`	禁用保持活动连接，以便服务器在第一次响应后关闭每个连接。	`false`
DisablePreParseMultipartForm	`bool`	如果设置为 true，则不会预解析 Multipart Form 数据。此选项对于希望将 multipart form 数据视为二进制 blob 或选择何时解析数据的服务器非常有用。	`false`
DisableHeadAutoRegister	`bool`	防止 Fiber 自动为每个 `GET` 路由注册 `HEAD` 路由，以便您可以提供自定义的 `HEAD` 处理程序；手动 `HEAD` 路由仍然会覆盖生成的路由。	`false`
EnableIPValidation	`bool`	如果设置为 true，`c.IP()` 和 `c.IPs()` 将在返回 IP 地址之前验证它们。此外，`c.IP()` 将仅返回第一个有效的 IP，而不是可能是一个逗号分隔字符串的原始标头值。警告：执行此验证会带来轻微的性能成本。如果速度是您唯一的关注点，并且您的应用程序位于已经验证了此标头的受信任代理之后，请将其禁用。	`false`
EnableSplittingOnParsers	`bool`	启用时，在逗号上分割查询、正文和标头参数。例如，`/api?foo=bar,baz` 变为 `foo[]=bar&foo[]=baz`。	`false`
TrustProxy	`bool`	如果为 true，Fiber 会根据 `TrustProxyConfig.Proxies` 验证代理 IP。默认情况下，`c.Protocol()`、`c.IP()` 和 `c.Hostname()` 从标准的 X-Forwarded 标头中读取值。如果远程 IP 匹配受信任的代理，这些方法将表现得好像 `TrustProxy` 被禁用一样。否则，`c.Protocol()` 反映连接方案，`c.IP()` 使用 Fasthttp 的 `RemoteIP()`，`c.Hostname()` 使用 `fasthttp.Request.URI().Host()`	`false`
ErrorHandler	`ErrorHandler`	当从 fiber.Handler 返回错误时，将执行 ErrorHandler。挂载的 Fiber 错误处理程序会保留在顶层应用程序中，并应用于前缀相关的请求。	`DefaultErrorHandler`
GETOnly	`bool`	如果设置为 true，则拒绝所有非 GET 请求。此选项可用作仅接受 GET 请求的服务器的抗 DoS 保护。如果设置了 GETOnly，请求大小受 ReadBufferSize 限制。	`false`
IdleTimeout	`time.Duration`	启用保持活动状态时，等待下一个请求的最大时间量。如果 IdleTimeout 为零，则使用 ReadTimeout 的值。	`nil`
Immutable	`bool`	启用时，上下文方法返回的所有值都是不可变的。默认情况下，它们在您从处理程序返回之前有效；请参阅 issue #185。	`false`
JSONEncoder	`utils.JSONMarshal`	允许灵活使用其他 json 库进行编码。	`json.Marshal`
JSONDecoder	`utils.JSONUnmarshal`	允许灵活使用其他 json 库进行解码。	`json.Unmarshal`
CBOREncoder	`utils.CBORMarshal`	允许灵活使用其他 cbor 库进行编码。	`*binder.UnimplementedCborMarshal`
CBORDecoder	`utils.CBORUnmarshal`	允许灵活使用其他 cbor 库进行解码。	`*binder.UnimplementedCborUnmarshal`
MsgpackEncoder	`utils.MsgpackMarshal`	允许灵活使用其他 msgpack 库进行编码。	`*binder.UnimplementedMsgpackMarshal`
MsgpackDecoder	`utils.MsgpackUnmarshal`	允许灵活使用其他 msgpack 库进行解码。	`*binder.UnimplementedMsgpackUnmarshal`
PassLocalsToViews	`bool`	PassLocalsToViews 启用将设置在 fiber.Ctx 上的 locals 传递给模板引擎。有关支持的引擎，请参阅我们的模板中间件。	`false`
ProxyHeader	`string`	这将使 `c.IP()` 返回给定标头键的值。默认情况下，`c.IP()` 将返回 TCP 连接的远程 IP，此属性在您位于负载均衡器后方时非常有用，例如 X-Forwarded-*。	`""`
ReadBufferSize	`int`	每连接的请求读取缓冲区大小。这也限制了最大标头大小。如果客户端发送多 KB 的 RequestURI 和/或多 KB 的标头（例如，BIG cookies），请增加此缓冲区。	`4096`
ReadTimeout	`time.Duration`	读取完整请求（包括正文）所允许的时间量。默认超时是无限的。	`nil`
ReduceMemoryUsage	`bool`	如果设置为 true，则以增加 CPU 使用率为代价，积极地减少内存使用。	`false`
RequestMethods	`[]string`	RequestMethods 提供了对 HTTP 方法的可定制性。您可以随意添加/删除方法。	`DefaultMethods`
ServerHeader	`string`	启用带有给定值的 `Server` HTTP 标头。	`""`
StreamRequestBody	`bool`	StreamRequestBody 启用请求正文流式传输，并在给定正文大于当前限制时更早调用处理程序。	`false`
StrictRouting	`bool`	启用时，路由器将 `/foo` 和 `/foo/` 视为不同。否则，路由器将 `/foo` 和 `/foo/` 视为相同。	`false`
StructValidator	`StructValidator`	如果你想在绑定时自动验证 header/form/query...，你可以定义结构验证器。Fiber 没有默认的验证器，所以如果你不使用任何验证器，它将跳过验证步骤。	`nil`
TrustProxyConfig	`TrustProxyConfig`	配置受信任的代理 IP。查看 `TrustProxy` 文档。 `TrustProxyConfig.Proxies` 可以接受 IP 或 IP 范围地址。	`nil`
UnescapePath	`bool`	将路由中所有编码的字符恢复原状后再为上下文设置路径，以便路由也可以处理 URL 编码的特殊字符	`false`
Views	`Views`	Views 是包装 Render 函数的接口。有关支持的引擎，请参阅我们的模板中间件。	`nil`
ViewsLayout	`string`	Views Layout 是所有模板渲染的全局布局，直到在 Render 函数中覆盖。有关支持的引擎，请参阅我们的模板中间件。	`""`
WriteBufferSize	`int`	响应写入的每连接缓冲区大小。	`4096`
WriteTimeout	`time.Duration`	响应写入超时前的最大持续时间。默认超时是无限的。	`nil`
XMLEncoder	`utils.XMLMarshal`	允许灵活使用其他 XML 库进行编码。	`xml.Marshal`
XMLDecoder	`utils.XMLUnmarshal`	允许灵活使用其他 XML 库进行解码。	`xml.Unmarshal`

服务器正在监听

Config

在调用 Listen 或 Listener 方法时，您可以传递自己的 ListenConfig。

示例
// Custom config
app.Listen(":8080", fiber.ListenConfig{
    EnablePrefork: true,
    DisableStartupMessage: true,
})

Config 字段

属性	类型	描述	默认值
BeforeServeFunc	`func(app *App) error`	允许在提供应用程序之前自定义和访问 Fiber 应用程序。	`nil`
CertClientFile	`string`	客户端证书的路径。如果要使用 mTLS，则必须输入此字段。	`""`
CertFile	`string`	证书文件的路径。如果要使用 TLS，则必须输入此字段。	`""`
CertKeyFile	`string`	证书私钥的路径。如果要使用 TLS，则必须输入此字段。	`""`
DisableStartupMessage	`bool`	如果设置为 true，它将不会打印出 “Fiber” ASCII 艺术和监听地址。	`false`
EnablePrefork	`bool`	如果设置为 true，这将产生多个 Go 进程监听同一个端口。	`false`
EnablePrintRoutes	`bool`	如果设置为 true，将打印所有路由及其方法、路径和处理程序。	`false`
GracefulContext	`context.Context`	用于通过给定上下文优雅地关闭 Fiber 的字段。	`nil`
ShutdownTimeout	`time.Duration`	指定等待服务器优雅关闭的最大持续时间。当达到超时时间时，优雅关闭过程将被中断并强制终止，并且 `context.DeadlineExceeded` 错误将传递给 `OnPostShutdown` 回调。设置为 0 表示禁用超时并无限期等待。	`10 * time.Second`
ListenerAddrFunc	`func(addr net.Addr)`	允许访问和自定义 `net.Listener`。	`nil`
ListenerNetwork	`string`	已知的网络有 "tcp", "tcp4" (仅限 IPv4), "tcp6" (仅限 IPv6), "unix" (Unix 域套接字)。警告：当 prefork 设置为 true 时，只能选择 "tcp4" 和 "tcp6"。	`tcp4`
UnixSocketFileMode	`os.FileMode`	为 Unix 域套接字设置的文件模式 (ListenerNetwork 必须是 "unix")	`0770`
TLSConfigFunc	`func(tlsConfig *tls.Config)`	允许按需自定义 `tls.Config`。如果设置了 `TLSConfig`，则忽略此项。	`nil`
TLSConfig	`*tls.Config`	推荐的基础 TLS 配置（已克隆）。用于通过 `GetCertificate` 的外部证书提供程序。设置后，将忽略其他 TLS 字段。	`nil`
AutoCertManager	`*autocert.Manager`	使用 ACME 协议自动管理 TLS 证书。启用与 Let's Encrypt 或其他 ACME 兼容提供商的集成。	`nil`
TLSMinVersion	`uint16`	允许自定义 TLS 最小版本。	`tls.VersionTLS12`

Listen

Listen 从给定的地址提供 HTTP 请求服务。

签名
func (app *App) Listen(addr string, config ...ListenConfig) error

基本 Listen 用法
// Listen on port :8080
app.Listen(":8080")

// Listen on port :8080 with Prefork
app.Listen(":8080", fiber.ListenConfig{EnablePrefork: true})

// Custom host
app.Listen("127.0.0.1:8080")

Prefork

Prefork 是一项功能，允许您生成多个 Go 进程来监听同一个端口。这对于跨多个 CPU 核心进行扩展很有用。

Prefork 监听器
app.Listen(":8080", fiber.ListenConfig{EnablePrefork: true})

这会将传入的连接分配给生成的进程，并允许同时处理更多请求。

TLS

优先使用 TLSConfig 进行 TLS 配置，以便您可以完全控制证书和设置。当设置了 TLSConfig 时，Fiber 会忽略 CertFile、CertKeyFile、CertClientFile、TLSMinVersion、AutoCertManager 和 TLSConfigFunc。

TLS 从给定地址提供 HTTPS 请求服务，使用 certFile 和 keyFile 路径作为 TLS 证书和密钥文件。

使用 cert 和 key 文件的 TLS
app.Listen(":443", fiber.ListenConfig{CertFile: "./cert.pem", CertKeyFile: "./cert.key"})

带有客户端 CA 证书的 TLS

仅当使用 CertFile/CertKeyFile 时，CertClientFile 才配置 mTLS 的客户端 CA。如果设置了 TLSConfig，则会忽略 CertClientFile，因此请在提供的 tls.Config 中配置客户端 CA。

带有客户端 CA 证书的 TLS
app.Listen(":443", fiber.ListenConfig{
    CertFile:       "./cert.pem",
    CertKeyFile:    "./cert.key",
    CertClientFile: "./ca-chain-cert.pem",
})

TLS 自动证书支持 (ACME / Let's Encrypt)

提供从 Let's Encrypt 和任何其他基于 ACME 的提供商自动访问证书管理的功能。

AutoCert (ACME) 配置
// Certificate manager
certManager := &autocert.Manager{
    Prompt: autocert.AcceptTOS,
    // Replace with your domain name
    HostPolicy: autocert.HostWhitelist("example.com"),
    // Folder to store the certificates
    Cache: autocert.DirCache("./certs"),
}

app.Listen(":444", fiber.ListenConfig{
    AutoCertManager:    certManager,
})

优先级和冲突

优先使用 TLSConfig，并忽略 CertFile/CertKeyFile、CertClientFile、AutoCertManager、TLSMinVersion 和 TLSConfigFunc。
AutoCertManager 不能与 CertFile/CertKeyFile 组合使用。

带有外部证书提供程序的 TLS

使用 TLSConfig 提供一个基础 tls.Config，该配置可以在运行时获取证书。TLSConfig 会被克隆并按原样使用。

带有动态证书提供程序的 TLSConfig
app.Listen(":443", fiber.ListenConfig{
    TLSConfig: &tls.Config{
        GetCertificate: func(info *tls.ClientHelloInfo) (*tls.Certificate, error) {
            return myProvider.Certificate(info.ServerName)
        },
    },
})

带有 TLSConfig 的双向 TLS

使用 TLSConfig 配置双向 TLS，方法是设置 ClientAuth 和 ClientCAs。当您直接管理 TLS 配置时，这会替换 CertClientFile。

带有客户端 CA 池的 TLSConfig
certPEM := []byte(certPEMString)
keyPEM := []byte(keyPEMString)
caPEM := []byte(caPEMString)

cert, err := tls.X509KeyPair(certPEM, keyPEM)
if err != nil {
    log.Fatal(err)
}

clientCAs := x509.NewCertPool()
if ok := clientCAs.AppendCertsFromPEM(caPEM); !ok {
    log.Fatal("failed to append client CA")
}

app.Listen(":443", fiber.ListenConfig{
    TLSConfig: &tls.Config{
        Certificates: []tls.Certificate{cert},
        ClientAuth:   tls.RequireAndVerifyClientCert,
        ClientCAs:    clientCAs,
    },
})

从内存或环境变量加载证书并通过 TLSConfig 提供它们。

带有内存中证书的 TLSConfig
certPEM := []byte(certPEMString)
keyPEM := []byte(keyPEMString)

cert, err := tls.X509KeyPair(certPEM, keyPEM)
if err != nil {
    log.Fatal(err)
}

app.Listen(":443", fiber.ListenConfig{
    TLSConfig: &tls.Config{
        Certificates: []tls.Certificate{cert},
    },
})

带有来自环境变量的证书的 TLSConfig
certPEM := []byte(os.Getenv("TLS_CERT_PEM"))
keyPEM := []byte(os.Getenv("TLS_KEY_PEM"))

cert, err := tls.X509KeyPair(certPEM, keyPEM)
if err != nil {
    log.Fatal(err)
}

app.Listen(":443", fiber.ListenConfig{
    TLSConfig: &tls.Config{
        Certificates: []tls.Certificate{cert},
    },
})

Listener

您可以使用 Listener 方法传递自己的 net.Listener。此方法可用于使用自定义 tls.Config 启用 TLS/HTTPS。

签名
func (app *App) Listener(ln net.Listener, config ...ListenConfig) error

示例
ln, _ := net.Listen("tcp", ":3000")

cer, _:= tls.LoadX509KeyPair("server.crt", "server.key")

ln = tls.NewListener(ln, &tls.Config{Certificates: []tls.Certificate{cer}})

app.Listener(ln)

Server

Server 返回底层的 fasthttp 服务器

签名
func (app *App) Server() *fasthttp.Server

示例
func main() {
    app := fiber.New()

    app.Server().MaxConnsPerIP = 1

    // ...
}

服务器关闭

优雅关闭 (Shutdown) 不会中断任何活动连接地关闭服务器。Shutdown 首先关闭所有打开的监听器，然后无限期地等待所有连接返回空闲状态，然后才关闭。

ShutdownWithTimeout 在超时到期后将强制关闭任何活动连接。

ShutdownWithContext 关闭服务器，如果上下文的截止时间超过，也可以强制关闭。即使在关闭过程中发生错误，关闭钩子仍将被执行，因为它们被推迟以确保无论发生什么错误都能进行清理。

func (app *App) Shutdown() error
func (app *App) ShutdownWithTimeout(timeout time.Duration) error
func (app *App) ShutdownWithContext(ctx context.Context) error

辅助函数

NewError

NewError 创建一个新的 HTTPError 实例，并带有一个可选的消息。

签名
func NewError(code int, message ...string) *Error

示例
app.Get("/", func(c fiber.Ctx) error {
    return fiber.NewError(782, "Custom error message")
})

NewErrorf

NewErrorf 创建一个新的 HTTPError 实例，并带有一个可选的格式化消息。

签名
func NewErrorf(code int, message ...any) *Error

示例
app.Get("/", func(c fiber.Ctx) error {
    return fiber.NewErrorf(782, "Custom error %s", "message")
})

IsChild

IsChild 确定当前进程是否是 Prefork 的结果。

签名
func IsChild() bool

示例
// Config app
app := fiber.New()

app.Get("/", func(c fiber.Ctx) error {
    if !fiber.IsChild() {
        fmt.Println("I'm the parent process")
    } else {
        fmt.Println("I'm a child process")
    }
    return c.SendString("Hello, World!")
})

// ...

// With prefork enabled, the parent process will spawn child processes
app.Listen(":8080", fiber.ListenConfig{EnablePrefork: true})

服务器启动​

New​

配置​

Config 字段​

服务器正在监听​

Config​

Config 字段​

Listen​

Prefork​

TLS​

带有客户端 CA 证书的 TLS​

TLS 自动证书支持 (ACME / Let's Encrypt)​

优先级和冲突​

带有外部证书提供程序的 TLS​

带有 TLSConfig 的双向 TLS​

Listener​

Server​

服务器关闭​

辅助函数​

NewError​

NewErrorf​

IsChild​

服务器启动

New

配置

Config 字段

服务器正在监听

Config

Config 字段

Listen

Prefork

TLS

带有客户端 CA 证书的 TLS

TLS 自动证书支持 (ACME / Let's Encrypt)

优先级和冲突

带有外部证书提供程序的 TLS

带有 TLSConfig 的双向 TLS

Listener

Server

服务器关闭

辅助函数

NewError

NewErrorf

IsChild