应直接用 $request->header('X-API-Key') 读取并校验请求头，集中处理于中间件 handle() 中，空值用 empty() 判断，拒绝非法请求时直接 return response()->json(..., 401)，避免嵌套、重复注册和硬编码校验逻辑。
中间件里怎么读取和校验请求头
直接用 $request->header('X-API-Key') 拿值，别碰 $_SERVER 或 getallheaders() —— Laravel 的 $request 已经做了标准化处理，大小写不敏感，还兼容 CGI 环境。常见错误是写成 $request->headers->get('x-api-key')，虽然能跑，但多了一层对象访问，没必要，也容易在测试 mock 时出错。
校验逻辑建议集中写在中间件的 handle() 里，别拆到其他方法或 service 中——头信息验证就是一次性的前置动作，过度抽象反而增加调用链和 debug 成本。
- 空值判断必须用
empty()或! $request->header('X-API-Key')，不能只用== null，因为 header 不存在时返回的是null，但值为''（空字符串）时也会失败 - 如果需要区分“未传”和“传了空值”，得用
$request->headers->has('X-API-Key') - 敏感头如
Authorization建议用Str::startsWith($auth, 'Bearer ')切分，别用explode(' ', $auth)，避免空格污染导致数组越界
Laravel 中间件如何拒绝非法请求并返回标准错误
别用 abort(401) 或 response()->json(...)->setStatusCode(401) 手动构造响应——Laravel 中间件里最干净的做法是直接 return 一个 Response 实例，比如 return response()->json(['message' => 'Invalid API key'], 401);。这样既跳过后续中间件和路由，又保持响应格式统一。
注意：不要在中间件里 throw Exception 期望被异常处理器捕获来返回 JSON，除非你明确重写了 App\Exceptions\Handler::render() 并对所有中间件异常做 JSON 化处理，否则开发环境会吐 HTML 错误页，线上可能暴露路径或堆栈。
- 状态码优先选
401 Unauthorized（缺认证凭据）或403 Forbidden（凭据存在但无效），别混用 - 响应体字段保持和项目其他接口一致，比如都用
message字段，别在中间件里突然改成error - 别在中间件里调用
Log::warning()记录每个失败请求——高频请求下 I/O 拖慢明显，真要审计，用 Laravel 的failed_login事件或 DB 日志表更合适
多个请求头联合校验时怎么组织逻辑
比如既要校验 X-API-Key，又要检查 X-Request-ID 长度、User-Agent 是否含爬虫关键词，别写成一长串 if (...) { if (...) { if (...) { ... } } }。用提前 return 拆解判断，每步只关心一个头，失败就立刻返回。
示例逻辑结构：
if (! $request->header('X-API-Key')) {
return response()->json(['message' => 'API key required'], 401);
}
if (strlen($request->header('X-Request-ID') ?? '') !== 32) {
return response()->json(['message' => 'Invalid request ID'], 400);
}
if (Str::contains(strtolower($request->header('User-Agent') ?? ''), ['bot', 'crawl', 'spider'])) {
return response()->json(['message' => 'Bot access denied'], 403);
}
这种写法比嵌套清晰，也方便后续抽离成独立验证方法，比如封装成 validateApiKey()、validateRequestId()，但前提是这些校验真会在别处复用——多数情况下，头校验是业务强相关的，硬拆反而让流程变散。
- 联合校验不等于“必须同时存在”，有些头是可选的（如
X-Correlation-ID），只做格式校验，不影响主流程 - 别把正则校验写死在中间件里，像邮箱、UUID 这类通用格式，用
filter_var()或Str::isUuid()更稳 - 如果某请求头需查数据库（如校验 API key 是否启用），记得加缓存，用
Cache::remember()包一层，key 里带上头的值哈希，避免每次请求都打 DB
中间件注册顺序和全局 vs 路由组影响
头验证中间件必须放在 app/Http/Kernel.php 的 $middleware 或 $middlewareGroups['api'] 里，且位置要靠前——它得在路由匹配、参数绑定、模型解析之前执行。如果放到了 $middlewareGroups['web'] 里却用在 API 路由上，压根不会触发。
最容易被忽略的是：同一个中间件类，如果在不同位置注册（比如既在全局又在某个路由组里显式加了一次），会导致重复执行。比如你在 routes/api.php 里写了 ->middleware(VerifyHeader::class)，又在 $middlewareGroups['api'] 里配了同一中间件，那请求进来会校验两遍。
- 推荐做法：只在
$middlewareGroups['api']里注册一次，然后所有 API 路由都用Route::middleware('api')统一包裹 - 如果某些接口不需要头校验（比如公开的健康检查
/health），别在中间件里写白名单逻辑，而是在路由定义时跳过：Route::get('/health')->withoutMiddleware([VerifyHeader::class]) - 中间件类名别起太泛，比如叫
AuthMiddleware，容易和 Laravel 自带的auth冲突；建议用具体功能命名，如VerifyApiHeader
