fiber

Fiber 核心知识

完整参考：有关使用 go-playground/validator 进行验证、WebSocket 配置、自定义错误处理、prefork 模式和优雅关闭，请参阅 advanced.md。

深入了解：使用 mcp__documentation__fetch_docs，并将 technology 设为：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(":8080")
}

配置

app := fiber.New(fiber.Config{
    Prefork:       true,               // Multiple processes
    StrictRouting: true,               // /foo != /foo/
    CaseSensitive: true,               // /Foo != /foo
    BodyLimit:     4 * 1024 * 1024,    // 4MB
    ReadTimeout:   10 * time.Second,
    WriteTimeout:  10 * time.Second,
})

路由

app.Get("/users", listUsers)
app.Get("/users/:id", getUser)
app.Post("/users", createUser)
app.Put("/users/:id", updateUser)
app.Delete("/users/:id", deleteUser)

// Path parameters
app.Get("/users/:id", func(c *fiber.Ctx) error {
    id := c.Params("id")
    return c.JSON(fiber.Map{"id": id})
})

// Optional parameter
app.Get("/users/:name?", func(c *fiber.Ctx) error {
    name := c.Params("name", "anonymous")
    return c.JSON(fiber.Map{"name": name})
})

// Route groups
api := app.Group("/api")
v1 := api.Group("/v1")
v1.Get("/users", listUsersV1)

上下文 - 请求数据

app.Post("/users", func(c *fiber.Ctx) error {
    // Path params
    id := c.Params("id")
    idInt, _ := c.ParamsInt("id")

    // Query params
    page := c.Query("page", "1")
    pageInt := c.QueryInt("page", 1)

    // Headers
    auth := c.Get("Authorization")

    // Cookies
    session := c.Cookies("session_id")

    return c.SendStatus(fiber.StatusOK)
})

请求体解析

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

app.Post("/users", func(c *fiber.Ctx) error {
    var req CreateUserRequest
    if err := c.BodyParser(&req); err != nil {
        return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{
            "error": err.Error(),
        })
    }
    return c.Status(fiber.StatusCreated).JSON(req)
})

中间件

import (
    "github.com/gofiber/fiber/v2/middleware/logger"
    "github.com/gofiber/fiber/v2/middleware/recover"
    "github.com/gofiber/fiber/v2/middleware/cors"
    "github.com/gofiber/fiber/v2/middleware/limiter"
)

app.Use(recover.New())
app.Use(logger.New())

app.Use(cors.New(cors.Config{
    AllowOrigins: "https://example.com",
    AllowMethods: "GET,POST,PUT,DELETE",
}))

app.Use(limiter.New(limiter.Config{
    Max:        100,
    Expiration: 1 * time.Minute,
}))

健康检查

app.Get("/health", func(c *fiber.Ctx) error {
    return c.JSON(fiber.Map{"status": "healthy"})
})

app.Get("/ready", func(c *fiber.Ctx) error {
    if err := db.Ping(); err != nil {
        return c.Status(fiber.StatusServiceUnavailable).JSON(fiber.Map{
            "status": "not ready",
        })
    }
    return c.JSON(fiber.Map{"status": "ready"})
})

不应使用此技能的情况

• Gin 项目 - Gin 的上下文 API 不同
• Echo 项目 - Echo 的中间件模式不同
• Chi 项目 - Chi 与标准库兼容
• 需要标准 net/http - Fiber 使用 fasthttp，而不是 net/http
• gRPC 服务 - Fiber 不支持 gRPC

反模式

反模式	不良影响	解决方案
未在中间件中调用 c.Next()	中断中间件链	除非要停止处理，否则始终调用 c.Next()
多次使用 c.Body()	请求体会被消耗	先将请求体保存到变量中
未处理错误	导致静默失败	检查 BodyParser() 的返回值
未谨慎设置 Prefork	可能导致状态问题	仅在没有共享状态时使用 Prefork
未启用速率限制	存在 DDoS 漏洞	使用 limiter 中间件

快速故障排查

问题	诊断	修复方法
未找到路由	方法或路径错误	检查路由注册是否完全匹配
请求体解析失败	Content-Type 错误	确保 Content-Type 标头正确
CORS 错误	未配置	使用 cors.New() 中间件
中间件未执行	顺序错误	将中间件放在路由处理程序之前
Prefork 问题	共享状态问题	使用 Prefork 时避免共享可变状态

生产环境检查清单

• 已启用恢复中间件
• 已配置 CORS
• 已启用速率限制
• 已设置请求体大小限制
• 已配置超时
• 结构化日志记录
• 健康检查/就绪状态端点
• 优雅关闭
• 输入验证

参考文档

• 路由
• 上下文
• 中间件