🤔 先问一句：为什么需要"适配器"？
想象你要搬家到新房子（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 种签名：
func(http.ResponseWriter, *http.Request)http.Handler接口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 迁移，这周就能搞定，业务零中断！" 🎯
