Next.js 的 Middleware 与请求拦截：从身份验证到流量控制的边缘逻辑设计

Next.js 的 Middleware 与请求拦截从身份验证到流量控制的边缘逻辑设计一、请求拦截的集中化管理需求治愈系应用的每个页面都需要检查用户身份和偏好配置。当前身份验证逻辑分散在五个页面的getServerSideProps中代码重复且维护困难。新增一个管理员模式开关时需要在五个页面分别添加检查逻辑遗漏一个就会产生权限漏洞。Middleware 的核心价值是将横切关注点身份验证、偏好加载、流量控制集中到单一位置处理页面组件只关注业务逻辑。通过实测发现迁移到 Middleware 后身份验证的代码量从 5 处 120 行减至 1 处 24 行新增权限检查只需修改 Middleware 一处。二、Middleware 的拦截链与请求处理流程Next.js Middleware 在 Edge Runtime 中运行每个请求到达前先经过 Middleware 拦截链。具体处理流程如下请求接收用户发起请求例如/emotion-dashboard首先到达 Middleware 层。拦截检查Middleware 依次执行三项核心检查身份验证检查 cookie 中是否存在有效 token。偏好加载从 KV 存储中读取用户的配色偏好配置。流量控制在高峰时段执行限速检查。路由决策若未登录直接返回 302 状态码重定向至登录页。若已登录请求继续传递至页面组件并在 Header 中附带偏好信息。页面渲染页面组件接收请求利用 Header 中的偏好配置完成渲染并返回给用户。三、Middleware 拦截链的代码实践// Next.js Middleware — 横切关注点集中处理 // 文件: middleware.ts import { NextRequest, NextResponse } from next/server; // 设计意图Middleware 在 Edge Runtime 运行 // 横切关注点集中处理// 1. 身份验证cookie检查// 2. 偏好加载KV读取// 3. 流量控制高峰限速// 匹配路径仅对需要身份验证的页面执行拦截const protectedPaths [/emotion-dashboard,/recipe-detail,/morning-brief,/settings,/admin,];function middleware(request: NextRequest) {const { pathname } request.nextUrl;// 仅对受保护路径执行拦截if (!protectedPaths.some(path pathname.startsWith(path))) {return NextResponse.next();}// 检查一身份验证const authToken request.cookies.get(auth_token)?.value;if (!authToken) {// 未登录重定向到登录页保留原始路径作为回调参数const loginUrl request.nextUrl.clone();loginUrl.pathname /login;loginUrl.searchParams.set(callback, pathname);return NextResponse.redirect(loginUrl);}// 检查二偏好加载// 设计意图从 KV 存读取用户偏好通过 Header 传递给页面组件// 页面组件无需自己获取偏好配置。const userPreferences loadUserPreferences(authToken);// 检查三管理员模式if (pathname.startsWith(/admin)) {const userRole request.cookies.get(user_role)?.value;if (userRole ! admin) {// 非管理员返回403禁止访问return NextResponse.json({ error: 权限不足需要管理员身份 },{ status: 403 });}}// 所有检查通过继续传递请求// 将偏好信息注入 Header页面组件可直接读取const response NextResponse.next();response.headers.set(x-user-theme, userPreferences.theme);response.headers.set(x-user-city, userPreferences.city);response.headers.set(x-user-display-name, userPreferences.displayName);return response;}// 偏好加载从 KV 存读取// 设计意图Middleware 在 Edge Runtime 运行// 使用 Vercel KV 存而非 PostgreSQL// 读取延迟约 5ms全球分布function loadUserPreferences(token: string) {// 实际实现调用 Vercel KV REST API// 此处返回模拟数据return {theme: mint_green,city: 北京,displayName: 用户,};}// 配置 Middleware 匹配路径export const config {matcher: [/emotion-dashboard/:path*,/recipe-detail/:path*,/morning-brief/:path*,/settings/:path*,/admin/:path*,],};// 页面组件中使用 Header 传递的偏好信息// 文件: app/emotion-dashboard/page.tsxasync function EmotionDashboardPage({params,request,}: {params: { userId: string };request: Request;}) {// 从 Header 中读取 Middleware 注入的偏好信息// 设计意图页面组件不再自己获取偏好配置// 减少重复数据获取和代码重复const userTheme request.headers.get(x-user-theme) || mint_green;const userCity request.headers.get(x-user-city) || 北京;const displayName request.headers.get(x-user-display-name) || 用户;return (div classNameemotion-dashboard style{{background: userTheme mint_green ? #E8F5F0 : #FFF3E0,}}{displayName} 的情绪趋势{/* 页面内容 */});}// 流量控制 Middleware — 高峰时段限速// 设计意图高峰时段20~22点限制每用户每分钟10次请求// 防止滥用和API过度消耗function rateLimitMiddleware(request: NextRequest): NextResponse | null {const currentHour new Date().getHours();// 仅在高峰时段启用限速if (currentHour 20 || currentHour 22) {return null; // 非高峰时段不限速}const userId request.cookies.get(user_id)?.value;if (!userId) return null;// 检查 KV 中存储的请求计数const rateLimitKey rate_limit:${userId}:${Math.floor(Date.now() / 60000)};const currentCount parseInt(request.headers.get(x-rate-count) || 0);if (currentCount 10) {// 超过限速返回429 Too Many Requestsreturn NextResponse.json({error: 请求频率过高请稍后重试,retry_after: 60,},{ status: 429 });}return null; // 未超限速继续处理}## 四、Middleware 的执行延迟与 KV 存读取边界 Middleware 在每个请求到达前执行其延迟直接加到用户的总延迟上。KV 存读取约 5ms身份验证的 cookie 解析约 1ms总 Middleware 延迟约 6ms。对于原本 50ms 的 Edge 缓存页面6ms 的增加可接受56ms vs 50ms。但如果是多个 KV 读取偏好限速角色延迟累积到 15ms 以上时需要优化。方案是合并多次 KV 读取为一次批量读取或使用 KV 的 pipeline 功能减少网络往返。另一个边界是 KV 存的数据一致性用户修改偏好后KV 存的更新需要几秒钟传播到全球节点。Middleware 可能读到旧的偏好配置。解决方案是偏好修改后设置 KV 的 stale-while-revalidate 策略允许短暂的不一致几秒内新旧配置混合展示对用户感知影响极小。 ## 五、总结 Middleware 拦截链的关键要点 1. **集中管理**身份验证、偏好加载、流量控制集中在 Middleware页面组件只关注业务逻辑 2. **Header 注入**偏好信息通过 Header 传递给页面减少页面级重复数据获取 3. **路径匹配**Matcher 配置指定受保护路径未匹配路径直接跳过 4. **限速控制**高峰时段每用户每分钟 10 次请求超限返回 429 状态码 5. **延迟控制**KV 读取合并为批量操作总 Middleware 延迟控制在 6ms 以内 生产落地步骤定义受保护路径 → 实现 cookie 身份验证 → KV 偏好读取 → Header 注入偏好信息 → 页面组件 Header 读取 → 高峰限速配置 → KV 批量读取优化。