应使用 go get github.com/gofiber/fiber/v2 安装 Fiber v2，因其支持 Go 1.19+、生态成熟稳定；v3 尚处测试阶段且要求 Go 1.24+。必须搭配 go-playground/validator/v10 并配置全局 ErrorHandler，否则校验失败时 400 响应体为空，前端无法解析错误字段。
直接用 go get github.com/gofiber/fiber/v2 安装，别碰 v3；校验必须配 go-playground/validator/v10 + 全局 ErrorHandler，否则 400 响应体为空，前端根本没法解析错误字段。
安装 Fiber：v2 是唯一生产可用选项
Fiber v3 要求 Go 1.24+，且截至 2026 年 10 月仍属测试阶段——文档不全、中间件生态未对齐、fiber.NewWithCustomCtx 等新 API 在 CI 中易因版本漂移失败。绝大多数项目应锁定 v2：
- 先确认 Go 版本：
go version，v2 支持 Go 1.19+，低于则需升级 - 执行：
go mod init myapp && go get github.com/gofiber/fiber/v2（不用-u，避免次版本意外升级） - 初始化必须用
fiber.New()，fiber.Default()默认启用日志和 recover 中间件，上线后 I/O 直接拖垮 QPS
绑定并校验请求参数：结构体 + validate tag 是核心
Fiber 本身不内置校验逻辑，得靠 go-playground/validator/v10。关键点不是“怎么写 struct”，而是“怎么让校验结果可被前端消费”：
- struct 字段必须首字母大写（否则反射不可见），tag 写法如：
type User struct { Email string `json:"email" validate:"required,email"` } - Query 参数用
c.QueryParser(&v)，Body 用c.BodyParser(&v)，Form 用c.BodyParser(&v)（注意 tag 用form:"username"而非json） -
c.BodyParser默认遇到校验失败就返回空 400 响应体——这完全没法用，必须提前注册全局ErrorHandler
配置 ErrorHandler：让校验失败返回结构化错误
这是最容易漏掉、也最影响前后端协作的一环。不能靠字符串匹配错误信息，必须用 errors.As 类型断言：
- 在
fiber.New()初始化时传入Config.ErrorHandler - 用
errors.As(err, &ve)判断是否为 validator 错误（ve是validator.ValidationErrors类型） - 遍历
ve构造map[string]string，key 是字段名（e.Field()），value 是提示（e.Error()） - 返回
c.Status(400).JSON(fiber.Map{...})，确保前端能按字段名拿到具体错误
混合来源校验（Query + Params + Body）：没有银弹，只能手动组合
Fiber 不支持单条路由自动合并多源数据进一个 struct。比如你既要校验 /users/:id 的路径参数，又要校验 ?page=1 查询参数，还要校验 POST body 里的 name，就得拆开处理：
- 先定义多个 struct，分别对应不同来源（
PathParams、QueryParams、RequestBody） - 依次调用
c.Params、c.QueryParser、c.BodyParser，各自校验 - 任一校验失败，统一走
ErrorHandler返回的格式——别在 handler 里手写c.Status(400).JSON，否则和全局错误结构不一致 - 如果字段语义强关联（比如
:id和 body 里的user_id必须一致），这种逻辑必须写在 handler 里做运行时判断，validator 无法跨源约束
真正麻烦的从来不是“怎么写校验规则”，而是“怎么让错误以稳定格式透出”——ErrorHandler 配错，或者忘了注册，整个校验链就变成黑盒；混合来源场景下字段分散、错误聚合逻辑容易遗漏，这些才是线上排查时最耗时间的地方。
