Fiber v3 适配器模式：17 种写法随便用，老代码"即插即用"🔌

🤔 先问一句：为什么需要"适配器"？

想象你要搬家到新房子（Fiber v3）：

• 🛋️ 老沙发（net/http 代码）：用了 3 年，坐着挺舒服，扔了可惜
• ⚡ 电竞椅（fasthttp 代码）：性能党最爱，换掉怕掉帧
• 🎮 游戏手柄（Express 风格）：团队用习惯了，换操作方式得重新练

Fiber v3 的适配器模式 就是给你配了个"万能转换插头"：

老家具不用扔，新房子直接住，慢慢升级不折腾！🎉

---

🔌 四大类"插头"，17 种写法全兼容

Fiber v3 路由器能识别 4 大类、共 17 种 不同的 Handler 签名。咱们一类一类看，用生活场景帮你理解👇

---

1️⃣ 原生 Fiber 处理器：亲儿子，最顺手 👨‍👦

🍋 就像用自家厨房做饭，锅碗瓢盆都趁手，推荐新代码都用这个！

支持写法 ：func(c fiber.Ctx) error

// ✅ 健康检查：一句话搞定
app.Get("/health", func(c fiber.Ctx) error {
    return c.SendString("ok 🟢")
})

// ✅ 创建用户：自动绑定 + 错误处理
app.Post("/users", func(c fiber.Ctx) error {
    var user User
    // Bind() 自动解析 JSON/Form，像智能收件箱
    if err := c.Bind().Body(&user); err != nil {
        return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{
            "error": err.Error(),
        })
    }
    // 业务逻辑...
    return c.Status(fiber.StatusCreated).JSON(user)
})

// ✅ 设置响应头：链式调用超丝滑
app.Get("/api/info", func(c fiber.Ctx) error {
    return c.
        Set("X-API-Version", "v3.0.0").
        Set("Content-Type", "application/json").
        JSON(fiber.Map{
            "service": "Fiber API",
            "status":  "running 🚀",
        })
})

💡 小技巧 ：原生写法支持 Bind()、QueryParser()、Params() 等便利方法，开发效率拉满！

---

2️⃣ 标准库 net/http 处理器：老代码救星 🦖

🔄 就像给老式两脚插头配转换器，http.Handler 代码不用改，直接插 Fiber 上用！

支持 3 种签名：

1. func(http.ResponseWriter, *http.Request)
2. http.Handler 接口
3. http.HandlerFunc 类型

import (
    "net/http"
    "github.com/gofiber/fiber/v3"
)

// 🔹 类型1：普通函数写法（最常见）
func legacyHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    w.Write([]byte(`{"message": "legacy endpoint 🦕"}`))
}

// 🔹 类型2：结构体实现 http.Handler 接口
type LegacyService struct{}
func (s *LegacyService) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("Legacy service response ⚙️"))
}

// 🔹 类型3：标准库 ServeMux（路由集合）
mux := http.NewServeMux()
mux.HandleFunc("/old/path", func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("old route 🗺️"))
})

// 🎯 在 Fiber 中直接注册，零修改！
app := fiber.New()
app.Get("/legacy1", legacyHandler)                // 直接传函数
app.Get("/legacy2", (&LegacyService{}).ServeHTTP) // 传方法
app.Get("/legacy3", mux.ServeHTTP)               // 传整个 mux

🎯 效果：跑了 3 年的老接口，复制粘贴一行代码就能在 Fiber v3 上跑，测试用例都不用改！

---

3️⃣ fasthttp 处理器：性能党的保留地 ⚡

🏎️ 就像赛车手的专属调校，为速度而生的代码，Fiber v3 让你不用为了迁移牺牲性能！

支持 1 种签名 ：func(*fasthttp.RequestCtx)

import (
    "github.com/gofiber/fiber/v3"
    "github.com/valyala/fasthttp"
)

// 🔹 基础写法：直接操作 fasthttp 上下文
func fastHandler(ctx *fasthttp.RequestCtx) {
    ctx.SetStatusCode(fasthttp.StatusOK)
    ctx.SetContentType("application/json")
    ctx.WriteString(`{"performance": "critical 🚀"}`)
}

// 🔹 进阶写法：根据 Method 分支处理
func fastUserHandler(ctx *fasthttp.RequestCtx) {
    switch string(ctx.Method()) {
    case "GET":
        userID := ctx.UserValue("id").(string)
        ctx.WriteString("User: " + userID)
    case "POST":
        body := ctx.PostBody() // 零拷贝读取，快！
        ctx.Write(body)
    default:
        ctx.Error("Method not allowed", fasthttp.StatusMethodNotAllowed)
    }
}

// 🎯 注册到 Fiber 路由
app := fiber.New()
app.Get("/fast-endpoint", fastHandler)
app.Get("/fast/users/:id", fastUserHandler)
app.Post("/fast/users", fastUserHandler)

💡 适用场景：QPS > 1000 的高频接口、文件上传、实时推送等性能敏感模块。

---

4️⃣ Express 风格处理器：Node.js 团队友好 🌐

🎭 如果你熟悉 Express 的 req/res/next，这个写法零学习成本，迁移像换皮肤！

支持 8 种变体（2 种 Handler + 6 种 Middleware）：

🔸 Handler 写法（2 参数）

// ✅ 基础版：不返回 error
app.Get("/express/hello", func(req fiber.Req, res fiber.Res) {
    res.SendString("Hello from Express style 👋")
})

// ✅ 进阶版：返回 error，Fiber 自动捕获
app.Get("/express/data", func(req fiber.Req, res fiber.Res) error {
    if req.Query("token") != "secret" {
        return fmt.Errorf("unauthorized 🔒")
    }
    return res.JSON(fiber.Map{"data": "sensitive 💎"})
})

🔸 Middleware 写法（3 参数，核心是 next）

// ✅ 类型3：基础中间件，next() 无参数
app.Use(func(req fiber.Req, res fiber.Res, next func()) {
    fmt.Printf("📝 日志: %s %s\n", req.Method(), req.Path())
    res.Set("X-Middleware", "executed ✅")
    next() // 继续往下走
})

// ✅ 类型4：next() 返回 error，可传递错误
app.Use("/api", func(req fiber.Req, res fiber.Res, next func() error) error {
    if req.Get("Authorization") == "" {
        res.Status(401)
        return res.SendString("Missing authorization 🔑")
    }
    return next() // 把错误传给上层
})

// ✅ 类型5：next(err) 主动传错误（适合异步场景）
app.Use(func(req fiber.Req, res fiber.Res, next func(error)) {
    go func() {
        if err := doAsyncWork(); err != nil {
            next(err) // 异步错误也能捕获！
        } else {
            next(nil)
        }
    }()
})

// ✅ 类型6：完全控制，next(err) 还能返回 error
app.Use(func(req fiber.Req, res fiber.Res, next func(error) error) error {
    // 预处理：打时间戳
    req.Set("X-Processed-At", time.Now().String())
    
    // 执行下一个，并捕获它的错误
    if err := next(nil); err != nil {
        res.Status(500)
        return res.SendString("Handler error: " + err.Error())
    }
    
    // 后处理：记录成功
    fmt.Println("✅ Request completed")
    return nil
})

🎯 核心优势 ：next() 的 6 种变体覆盖了同步/异步、错误传递、错误包装等所有中间件场景，Express 老手秒上手！

---

🧪 实战：一个项目里混用 4 种风格

package main

import (
    "fmt"
    "net/http"
    "github.com/gofiber/fiber/v3"
    "github.com/valyala/fasthttp"
)

func main() {
    app := fiber.New()
    
    // 🔹 1. 原生 Fiber：新接口用这个
    app.Get("/fiber/health", func(c fiber.Ctx) error {
        return c.Set("X-Engine", "Fiber").SendString("Healthy 🟢")
    })
    
    // 🔹 2. net/http：老接口直接复用
    httpHandler := func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Legacy HTTP handler 🦖"))
    }
    app.Get("/http/legacy", httpHandler)
    
    // 🔹 3. fasthttp：高性能模块保留
    fastHandler := func(ctx *fasthttp.RequestCtx) {
        ctx.WriteString("FastHTTP performance ⚡")
    }
    app.Get("/fasthttp/fast", fastHandler)
    
    // 🔹 4. Express 风格：中间件链 + Handler
    // 中间件1：打追踪 ID
    app.Use(func(req fiber.Req, res fiber.Res, next func()) {
        res.Set("X-Trace-ID", "req-123 🔍")
        next()
    })
    
    // 中间件2：权限校验（带错误返回）
    app.Use(func(req fiber.Req, res fiber.Res, next func() error) error {
        if req.Path() == "/blocked" {
            res.Status(403)
            return res.SendString("Access denied 🚫")
        }
        return next()
    })
    
    // Handler：返回 JSON
    app.Get("/express/data", func(req fiber.Req, res fiber.Res) {
        res.JSON(fiber.Map{
            "style":  "express 🎭",
            "status": "ok ✅",
        })
    })
    
    // 🚀 启动！
    app.Listen(":3000")
}

---

🎯 使用建议：什么时候用哪种？

场景	推荐写法	原因
🆕 全新接口	func(c fiber.Ctx) error	零历史包袱，直接用最新特性
⚡ QPS > 1000	func(c fiber.Ctx) error	少一层适配，性能更极致
🔧 需要 Fiber 专属 API	func(c fiber.Ctx) error	如 Bind()、Locals、Hooks
🧓 老代码迁移中	任意兼容风格	先跑起来，再慢慢改
👥 团队有 Node.js 背景	Express 风格 (req, res, next)	降低学习成本，快速上手
📦 集成第三方 net/http 库	http.Handler	如 Prometheus、Swagger 等

💡 黄金法则：适配器是过渡工具，不是永久方案。新代码、高频代码，直接用原生 Fiber！

---

🎉 总结：适配器模式的真正价值

Fiber v3 的适配器模式，不是炫技，而是务实：

• 🔄 降低迁移成本：老接口不用重写，本周就能上线新版本
• 🧩 支持混合开发：新老代码可以共存迭代，团队不用"停更迁移"
• 🚀 平滑过渡：业务无感知，技术栈悄悄升级，老板满意，同事开心

💡 就像给老房子装修：不用拆了重建，换个智能插座，老电器照样用，新电器也能插，慢慢升级，生活不停摆。

现在，你可以自信地对团队说：

"Fiber v3 迁移，这周就能搞定，业务零中断！" 🎯

---