👋 欢迎

这是一个带有示例的在线 API 文档，你可以立即开始使用 Fiber 构建 Web 应用！

Fiber 是一个受 Express 启发的 Web 框架，构建在 Fasthttp 之上，Fasthttp 是 Go 语言中最快的 HTTP 引擎。它的设计目的是为了简化开发流程，实现快速开发，同时考虑到零内存分配和性能。

本文档适用于 Fiber v2，该版本于 2020 年 9 月 15 日发布。

安装​

首先，下载并安装 Go，版本需为 1.17 或更高。

使用 go get 命令进行安装：

go get github.com/gofiber/fiber/v2

零内存分配​

从 *fiber.Ctx 返回的一些值默认不是不可变的。

因为 fiber 针对高性能进行了优化，从 fiber.Ctx 返回的值默认是可变的，并且在多个请求之间会被复用。因此你只能在 handler 内部使用 context 的值，不能保留任何引用。一旦你从 handler 返回，这些值就会被后续的请求复用，并且会发生变化。示例如下：

func handler(c *fiber.Ctx) error {
    // 这个变量只在当前 handler 中有效
    result := c.Params("foo")
    // ...
}

如果你需要在 handler 外部持久化这些值，应该使用 copy 内建函数复制它们的底层 buffer。例如：

func handler(c *fiber.Ctx) error {
    // 这个变量只在当前 handler 中有效
    result := c.Params("foo")
    // 复制内容
    buffer := make([]byte, len(result))
    copy(buffer, result)
    resultCopy := string(buffer)
    // 现在这个变量可以永久使用
    // ...
}

我们还封装了一个名为 CopyString 的函数，功能就是做这件事，放在了 gofiber/utils 里。

app.Get("/:foo", func(c *fiber.Ctx) error {
    // 变量现在是不可变的
    result := utils.CopyString(c.Params("foo"))
    // ...
})

另外，你也可以启用 Immutable 配置，它会让 context 返回的所有值变成不可变的，这样就可以随意持久化使用了。当然，这样做会牺牲一些性能。

app := fiber.New(fiber.Config{
    Immutable: true,
})

更多细节可以参考 #426 和 #185。

Hello, World

下面是一个最基础的 Fiber 应用：

package main
import "github.com/gofiber/fiber/v2"
func main() {
    app := fiber.New()
    app.Get("/", func(c *fiber.Ctx) error {
        return c.SendString("Hello, World!")
    })
    app.Listen(":3000")
}

go run server.go

然后打开浏览器访问 http://localhost:3000，你应该能看到页面上显示了 Hello, World!。

基本路由​

路由是指应用如何响应来自客户端的请求，每个请求都会指向一个特定的端点，也就是一个 URI（路径）和一个 HTTP 请求方法（如 GET, PUT, POST 等）。

每个路由可以绑定多个 handler 函数，当匹配该路由时这些函数会依次执行。

定义路由的方式如下：

// 函数签名
app.Method(path string, ...func(*fiber.Ctx) error)

• app 是 Fiber 的实例
• Method 是一个 HTTP 请求方法：如 GET, PUT, POST 等
• path 是服务器上的虚拟路径
• func(*fiber.Ctx) error 是当路由匹配时被执行的回调函数，参数是 Context

简单路由

// 在根路径 "/" 上返回 "Hello, World!"
app.Get("/", func(c *fiber.Ctx) error {
    return c.SendString("Hello, World!")
})

带参数

// GET http://localhost:8080/hello%20world
app.Get("/:value", func(c *fiber.Ctx) error {
    return c.SendString("value: " + c.Params("value"))
    // => 请求结果: value: hello world
})

可选参数

// GET http://localhost:3000/john
app.Get("/:name?", func(c *fiber.Ctx) error {
    if c.Params("name") != "" {
        return c.SendString("Hello " + c.Params("name"))
        // => Hello john
    }
    return c.SendString("Where is john?")
})

通配符

// GET http://localhost:3000/api/user/john
app.Get("/api/*", func(c *fiber.Ctx) error {
    return c.SendString("API path: " + c.Params("*"))
    // => API path: user/john
})

静态文件​

要提供静态文件（比如 图片、CSS、JavaScript 文件），可以用目录路径来代替 handler 函数。

函数签名如下：

app.Static(prefix, root string, config ...Static)

下面这段代码会提供 ./public 目录中的文件：

app := fiber.New()
app.Static("/", "./public")
app.Listen(":3000")

现在你就可以访问 ./public 目录中的文件了，例如：

http://localhost:3000/hello.html
http://localhost:3000/js/jquery.js
http://localhost:3000/css/style.css

注意事项​

如果你想了解更多如何使用 Go 和 Fiber 构建 API，可以参考这篇很棒的文章：用 Fiber 构建 Express 风格的 API。