Request 和 Response 对象的扩展

Koa2 是一个基于 Node.js 的轻量级 Web 框架，它的核心设计理念是中间件机制。Request 和 Response 对象是 Koa2 中处理 HTTP 请求和响应的关键对象，通过扩展这两个对象，可以增强框架的功能性和灵活性。

Request 对象的扩展

Koa2 的 ctx.request 对象是对 Node.js 原生 http.IncomingMessage 的封装，提供了许多便捷的属性和方法。开发者可以通过扩展 Request 对象来添加自定义功能。

自定义属性

例如，可以通过扩展 Request 对象来添加一个 isMobile 属性，用于判断请求是否来自移动设备：

app.use(async (ctx, next) => {
  ctx.request.isMobile = /mobile/i.test(ctx.get('User-Agent'));
  await next();
});

这样，在后续的中间件中就可以直接通过 ctx.request.isMobile 来判断请求的来源。

自定义方法

除了属性，还可以为 Request 对象添加自定义方法。例如，添加一个 parseQuery 方法来解析查询字符串：

app.use(async (ctx, next) => {
  ctx.request.parseQuery = function() {
    const querystring = require('querystring');
    return querystring.parse(this.query);
  };
  await next();
});

使用时，可以通过 ctx.request.parseQuery() 来获取解析后的查询参数对象。

使用第三方库扩展

Koa2 社区提供了许多第三方库来扩展 Request 对象的功能。例如，koa-request-id 可以为每个请求添加唯一的 ID：

const requestId = require('koa-request-id');
app.use(requestId());

安装后，每个请求的 ctx.request.id 都会包含一个唯一的标识符。

Response 对象的扩展

ctx.response 对象是对 Node.js 原生 http.ServerResponse 的封装，同样可以通过扩展来增强功能。

自定义属性

例如，可以为 Response 对象添加一个 cache 属性，用于控制缓存行为：

app.use(async (ctx, next) => {
  ctx.response.cache = function(maxAge) {
    this.set('Cache-Control', `public, max-age=${maxAge}`);
  };
  await next();
});

使用时，可以通过 ctx.response.cache(3600) 来设置缓存时间为 1 小时。

自定义方法

还可以为 Response 对象添加自定义方法。例如，添加一个 jsonp 方法来支持 JSONP 响应：

app.use(async (ctx, next) => {
  ctx.response.jsonp = function(data) {
    const callback = ctx.query.callback || 'callback';
    this.type = 'text/javascript';
    this.body = `${callback}(${JSON.stringify(data)})`;
  };
  await next();
});

使用时，可以通过 ctx.response.jsonp({ foo: 'bar' }) 来返回 JSONP 格式的数据。

使用第三方库扩展

社区中也有许多库可以扩展 Response 对象的功能。例如，koa-json 可以自动将响应数据转换为 JSON 格式：

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

安装后，可以直接通过 ctx.body = { foo: 'bar' } 来返回 JSON 数据，无需手动设置 Content-Type。

结合中间件的扩展

在实际开发中，通常会结合中间件来扩展 Request 和 Response 对象的功能。例如，以下中间件同时扩展了 Request 和 Response 对象：

app.use(async (ctx, next) => {
  // 扩展 Request
  ctx.request.getClientIP = function() {
    return this.ip || this.headers['x-forwarded-for'] || this.connection.remoteAddress;
  };

  // 扩展 Response
  ctx.response.success = function(data) {
    this.status = 200;
    this.body = { success: true, data };
  };

  await next();
});

这样，在后续的中间件中就可以直接使用 ctx.request.getClientIP() 和 ctx.response.success() 方法。

动态扩展与静态扩展的区别

Koa2 的扩展方式可以分为动态扩展和静态扩展。动态扩展是在中间件中临时添加属性或方法，而静态扩展是通过修改 Request 或 Response 的原型链来永久添加功能。

动态扩展示例

动态扩展的灵活性较高，但每次请求都会重新定义属性或方法：

app.use(async (ctx, next) => {
  ctx.request.timestamp = Date.now();
  await next();
});

静态扩展示例

静态扩展通过修改原型链来实现，只需定义一次：

const Koa = require('koa');
const app = new Koa();

app.request.__proto__.timestamp = function() {
  return Date.now();
};

app.response.__proto__.error = function(message, code = 400) {
  this.status = code;
  this.body = { success: false, message };
};

静态扩展的性能更好，但需要注意避免命名冲突。

扩展的实际应用场景

扩展 Request 和 Response 对象在实际开发中有许多应用场景。以下是一些常见的例子：

用户认证

通过扩展 Request 对象来添加用户认证相关的方法：

app.use(async (ctx, next) => {
  ctx.request.isAuthenticated = function() {
    return !!this.session.user;
  };

  ctx.request.getUser = function() {
    return this.session.user;
  };

  await next();
});

API 响应格式化

通过扩展 Response 对象来统一 API 响应的格式：

app.use(async (ctx, next) => {
  ctx.response.apiSuccess = function(data) {
    this.body = { code: 0, data };
  };

  ctx.response.apiError = function(message, code = 1) {
    this.body = { code, message };
  };

  await next();
});

请求日志

通过扩展 Request 对象来记录请求日志：

app.use(async (ctx, next) => {
  ctx.request.log = function() {
    console.log(`[${new Date().toISOString()}] ${this.method} ${this.url}`);
  };

  ctx.request.log();
  await next();
});

扩展的注意事项

在扩展 Request 和 Response 对象时，需要注意以下几点：

1. 命名冲突：避免与原生属性或第三方库的属性名冲突。
2. 性能影响：动态扩展可能会对性能产生轻微影响，尤其是在高并发场景下。
3. 可维护性：尽量将扩展逻辑封装到独立的中间件中，便于维护和复用。

与其他框架的对比

与其他 Node.js 框架（如 Express）相比，Koa2 的 Request 和 Response 对象扩展更加灵活。Express 的扩展通常通过 app.use 或直接修改原型链实现，而 Koa2 的中间件机制使得扩展更加模块化。

Express 的扩展示例

const express = require('express');
const app = express();

app.request.__proto__.isMobile = function() {
  return /mobile/i.test(this.get('User-Agent'));
};

相比之下，Koa2 的扩展方式更加符合现代 JavaScript 的模块化思想。