KeyAuth中间件必须前置注册且Extractor与客户端发送位置严格对齐，Validator需轻量快速并返回error，否则会导致密钥提取失败、校验跳过或404/401错误。
直接用 fiber.KeyAuth() 中间件就能实现，但密钥拿不到、校验总失败、请求直接 404 —— 这些问题几乎都出在提取路径没对齐或中间件注册顺序错了。
KeyAuth中间件必须放在路由注册之前
它不是“加在某个路由上就行”的装饰器，而是前置守门人。一旦放错位置，比如写在 app.Get("/api/users", handler) 之后，整个中间件就完全不触发。
- 正确写法：
app.Use(fiber.KeyAuth(...))或app.Get("/api/users", fiber.KeyAuth(...), handler) - 错误写法：
app.Get("/api/users", handler); app.Use(fiber.KeyAuth(...))—— 此时所有请求已进入业务逻辑，KeyAuth 彻底失效 - 如果只给部分接口加认证，优先用单路由绑定（
app.Get("/admin", auth, handler)），别依赖全局Use()后再靠路径过滤
Extractor配置必须和客户端实际发送位置一致
默认只从 X-Api-Key Header 读，但你的前端发的是 apikey、token 或 URL 参数 ?key=xxx，不显式改 Extractor 就永远拿不到值。
- Header 字段名大小写敏感：
FromHeader("apikey")✅，FromHeader("ApiKey")❌ - Query 提取适合调试：
FromQuery("key")，但生产环境禁用——密钥会进 access log、CDN 缓存、代理记录 - Form 提取仅适用于 POST 表单：
FromForm("api_key")，注意字段名要和c.FormValue()读取的一致 - 需要 fallback？自己写组合 extractor：先查 Header，查不到再查 Query，但别滥用，增加解析开销
Validator函数必须快且明确返回 error
KeyAuth 在每次请求里同步执行 Validator，它不能做 DB 查询、HTTP 调用或加密解密；超过 5ms 就可能拖慢整个接口的 P99 延迟。
- 推荐做法：把密钥预加载进内存 map 或 LRU cache，
Validator只做 O(1) 查表 + 简单过期判断 - 返回
nil表示通过，返回非nil error表示拒绝；不要用ctx.Status(401).Send()—— KeyAuth 自己会处理响应 - 自定义错误响应？配
ErrorHandler函数，它接收error和*fiber.Ctx，可调c.JSON()返回结构化错误 - 别在
Validator里调c.Locals存东西——KeyAuth 执行完就退出，后续中间件/Handler 拿不到
常见失败现象与定位方式
看到 401 却不知道哪步挂了？先确认三件事：
- 用
c.Get("X-Api-Key")或c.Query("key")手动打印原始值，验证客户端是否真发了、发对了位置 - 在
Validator开头加日志（如log.Printf("validating key: %s", key)），确认函数是否被调用 - 检查是否启用了
StrictRouting：如果客户端访问/api/users/（带尾斜杠）而你只注册了/api/users，请求根本到不了 KeyAuth 层，直接 404 - KeyAuth 不处理 OPTIONS 预检请求——如果你的前端发 CORS 请求，得单独放行或加
app.Options("/*", func(c *fiber.Ctx) error { return c.SendStatus(204) })
最易被忽略的是 extractor 和业务路径的耦合：一个微小的字段名拼写错误，或一个没意识到的尾斜杠，就会让整个认证链静默失效。上线前务必用真实请求路径 + 真实 Header 组合做端到端验证，别只测单元逻辑。
