常用官方中间件介绍与使用

中间件在Koa2中的作用

Koa2的核心设计理念就是中间件机制。中间件是一个函数，接收两个参数：ctx和next。ctx是上下文对象，封装了请求和响应；next是一个函数，调用它会把控制权交给下一个中间件。这种机制允许开发者通过组合不同的中间件来处理HTTP请求。

app.use(async (ctx, next) => {
  console.log('第一个中间件开始');
  await next();
  console.log('第一个中间件结束');
});

app.use(async (ctx, next) => {
  console.log('第二个中间件开始');
  await next();
  console.log('第二个中间件结束');
});

koa-bodyparser

koa-bodyparser用于解析请求体，支持JSON、表单和文本格式。安装方式：

npm install koa-bodyparser

基本使用：

const Koa = require('koa');
const bodyParser = require('koa-bodyparser');

const app = new Koa();
app.use(bodyParser());

app.use(async ctx => {
  // 获取POST请求体
  const body = ctx.request.body;
  ctx.body = `接收到的数据: ${JSON.stringify(body)}`;
});

高级配置选项：

app.use(bodyParser({
  enableTypes: ['json', 'form', 'text'],
  extendTypes: {
    json: ['application/x-javascript'],
    text: ['text/xml']
  },
  onerror: function(err, ctx) {
    ctx.throw(422, 'body parse error');
  }
}));

koa-router

koa-router是Koa2最常用的路由中间件。安装：

npm install @koa/router

基本路由定义：

const Router = require('@koa/router');
const router = new Router();

router.get('/', async (ctx) => {
  ctx.body = '首页';
});

router.get('/users/:id', async (ctx) => {
  ctx.body = `用户ID: ${ctx.params.id}`;
});

app.use(router.routes()).use(router.allowedMethods());

嵌套路由示例：

const users = new Router();
users.get('/', async (ctx) => {
  ctx.body = '用户列表';
});

const posts = new Router();
posts.get('/', async (ctx) => {
  ctx.body = '文章列表';
});

const api = new Router();
api.use('/users', users.routes());
api.use('/posts', posts.routes());

app.use(api.routes());

koa-static

koa-static用于提供静态文件服务。安装：

npm install koa-static

基本用法：

const static = require('koa-static');
app.use(static('public'));

配置选项示例：

app.use(static('public', {
  maxage: 365 * 24 * 60 * 60 * 1000, // 缓存一年
  hidden: true, // 允许访问隐藏文件
  index: 'default.html', // 默认文件
  defer: true // 先执行其他中间件
}));

koa-views

koa-views用于模板渲染。安装：

npm install koa-views

配合EJS模板引擎使用：

const views = require('koa-views');
app.use(views(__dirname + '/views', {
  extension: 'ejs'
}));

app.use(async ctx => {
  await ctx.render('index', {
    title: 'Koa2视图',
    user: {name: '张三'}
  });
});

支持多模板引擎：

app.use(views(__dirname + '/views', {
  map: {
    html: 'handlebars',
    ejs: 'ejs'
  }
}));

koa-session

koa-session提供会话管理功能。安装：

npm install koa-session

基本配置：

const session = require('koa-session');
app.keys = ['some secret key'];
app.use(session(app));

app.use(async ctx => {
  if (ctx.path === '/login') {
    ctx.session.user = {name: 'admin'};
    ctx.body = '登录成功';
  } else if (ctx.path === '/user') {
    ctx.body = ctx.session.user || '未登录';
  }
});

自定义存储：

const store = {
  get(key) {
    // 从数据库获取session
  },
  set(key, sess, maxAge) {
    // 存储到数据库
  },
  destroy(key) {
    // 从数据库删除
  }
};

app.use(session({
  store,
  key: 'koa:sess',
  maxAge: 86400000,
  autoCommit: true,
  overwrite: true,
  httpOnly: true,
  signed: true,
  rolling: false,
  renew: false
}, app));

koa-helmet

koa-helmet通过设置各种HTTP头来增强应用安全性。安装：

npm install koa-helmet

基本使用：

const helmet = require('koa-helmet');
app.use(helmet());

自定义安全策略：

app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "'unsafe-inline'"],
      styleSrc: ["'self'", "'unsafe-inline'"]
    }
  },
  hsts: {
    maxAge: 31536000,
    includeSubDomains: true
  },
  noCache: true
}));

koa-compress

koa-compress提供响应压缩功能。安装：

npm install koa-compress

基本配置：

const compress = require('koa-compress');
app.use(compress({
  filter: contentType => /text|javascript/i.test(contentType),
  threshold: 2048,
  gzip: {
    flush: require('zlib').constants.Z_SYNC_FLUSH
  },
  deflate: {
    flush: require('zlib').constants.Z_SYNC_FLUSH
  },
  br: false
}));

koa-logger

koa-logger提供请求日志功能。安装：

npm install koa-logger

使用示例：

const logger = require('koa-logger');
app.use(logger());

// 自定义日志格式
app.use(logger((str, args) => {
  console.log(`[${new Date().toISOString()}] ${str}`);
}));

koa-json

koa-json美化JSON响应。安装：

npm install koa-json

基本用法：

const json = require('koa-json');
app.use(json());

app.use(ctx => {
  ctx.body = {message: 'Hello', data: [1, 2, 3]};
  // 输出格式化的JSON
});

配置选项：

app.use(json({
  pretty: process.env.NODE_ENV !== 'production',
  param: 'pretty',
  spaces: 2
}));

koa-respond

koa-respond简化HTTP响应。安装：

npm install koa-respond

使用示例：

const respond = require('koa-respond');
app.use(respond());

app.use(ctx => {
  if (ctx.accepts('html')) {
    return ctx.html('<h1>Hello</h1>');
  }
  if (ctx.accepts('json')) {
    return ctx.json({message: 'Hello'});
  }
  return ctx.send(400, 'Bad Request');
});

koa-cors

koa-cors处理跨域请求。安装：

npm install @koa/cors

基本配置：

const cors = require('@koa/cors');
app.use(cors());

// 自定义配置
app.use(cors({
  origin: 'https://example.com',
  allowMethods: ['GET', 'POST', 'PUT'],
  allowHeaders: ['Content-Type'],
  exposeHeaders: ['X-Custom-Header'],
  credentials: true,
  maxAge: 3600
}));

koa-ratelimit

koa-ratelimit提供速率限制功能。安装：

npm install koa-ratelimit

使用Redis存储的示例：

const ratelimit = require('koa-ratelimit');
const Redis = require('ioredis');

app.use(ratelimit({
  driver: 'redis',
  db: new Redis(),
  duration: 60000,
  errorMessage: '请求太频繁',
  id: ctx => ctx.ip,
  headers: {
    remaining: 'Rate-Limit-Remaining',
    reset: 'Rate-Limit-Reset',
    total: 'Rate-Limit-Total'
  },
  max: 100,
  disableHeader: false
}));

koa-conditional-get

koa-conditional-get与koa-etag配合实现缓存控制。安装：

npm install koa-conditional-get koa-etag

使用示例：

const conditional = require('koa-conditional-get');
const etag = require('koa-etag');

app.use(conditional());
app.use(etag());

app.use(ctx => {
  ctx.body = {data: '需要缓存的内容'};
});

koa-parameter

koa-parameter提供参数验证功能。安装：

npm install koa-parameter

基本用法：

const parameter = require('koa-parameter');
app.use(parameter(app));

app.use(ctx => {
  ctx.verifyParams({
    name: {type: 'string', required: true},
    age: {type: 'number', min: 18}
  });
  
  // 参数验证通过后继续处理
  ctx.body = ctx.request.body;
});

自定义错误处理：

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    if (err.code === 'INVALID_PARAM') {
      ctx.status = 422;
      ctx.body = {error: err.message, errors: err.errors};
    }
  }
});

koa-jwt

koa-jwt处理JSON Web Token。安装：

npm install koa-jwt

基本配置：

const jwt = require('koa-jwt');
app.use(jwt({
  secret: 'shared-secret',
  key: 'jwtdata'
}).unless({
  path: [/^\/public/]
}));

// 受保护的路由
app.use(ctx => {
  ctx.body = {
    user: ctx.state.jwtdata
  };
});

自定义令牌获取：

app.use(jwt({
  secret: 'shared-secret',
  getToken: ctx => ctx.cookies.get('token')
}));