H3框架中间件(Middleware)深度解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01018/article/details/148548897

H3框架中间件(Middleware)深度解析

h3 ⚡️ Minimal H(TTP) framework built for high performance and portability 项目地址: https://gitcode.com/gh_mirrors/h31/h3

什么是H3中间件

H3框架中的中间件是一种强大的请求处理机制，它允许开发者在请求到达路由处理器之前或之后拦截请求、响应和错误。中间件本质上是一个函数，它接收事件对象(event)作为参数，并可以选择性地调用下一个中间件或路由处理器。

中间件核心概念

中间件工作流程

请求拦截：中间件可以在请求到达路由处理器之前进行处理
响应拦截：中间件可以修改路由处理器返回的响应
错误处理：中间件可以捕获并处理请求处理过程中的错误

中间件执行顺序

H3中间件遵循"洋葱模型"执行顺序：

先注册的中间件先执行
每个中间件可以选择继续执行下一个中间件或直接返回响应
响应会按照相反的顺序经过中间件返回

中间件使用方式

基础中间件注册

最简单的中间件形式是一个接收事件对象的函数：

app.use((event) => {
  console.log('请求路径:', event.path);
});

带路径匹配的中间件

可以指定中间件只对特定路径生效：

app.use('/api/*', (event) => {
  console.log('API请求:', event.path);
});

带方法匹配的中间件

可以限制中间件只对特定HTTP方法生效：

app.use('/user', (event) => {
  console.log('用户相关请求');
}, {
  method: ['GET', 'POST']
});

中间件高级用法

响应拦截

通过使用next参数，中间件可以拦截并修改响应：

app.use(async (event, next) => {
  const response = await next(); // 执行后续中间件和路由处理器
  return `${response} (已处理)`; // 修改响应
});

错误处理中间件

H3提供了专门的错误处理中间件：

import { onError } from 'h3';

app.use(onError((event, error) => {
  console.error('请求处理出错:', error);
  return '发生错误，请稍后再试';
}));

路由级中间件

可以为特定路由单独注册中间件：

app.get('/protected', handler, {
  middleware: [
    authMiddleware,
    loggingMiddleware
  ]
});

最佳实践建议

优先使用组合式工具：除非必要，否则优先使用组合式函数而非全局中间件
保持中间件职责单一：每个中间件应该只做一件事
合理使用路径匹配：避免全局中间件处理所有请求
注意执行顺序：中间件的注册顺序会影响执行顺序
谨慎使用响应拦截：过度拦截可能导致难以追踪的问题

常见中间件模式

日志记录中间件

app.use(onRequest((event) => {
  console.log(`[${new Date().toISOString()}] ${event.method} ${event.path}`);
}));

认证中间件

app.use('/admin', (event) => {
  if (!event.context.user || !event.context.user.isAdmin) {
    throw createError({ statusCode: 403, message: '无权访问' });
  }
});

响应时间中间件

app.use(async (event, next) => {
  const start = Date.now();
  const response = await next();
  const duration = Date.now() - start;
  event.res.setHeader('X-Response-Time', `${duration}ms`);
  return response;
});