Extension of the Request and Response objects

Koa2 is a lightweight web framework based on Node.js, with its core design philosophy centered around middleware mechanisms. The Request and Response objects are key components in Koa2 for handling HTTP requests and responses. By extending these two objects, the framework's functionality and flexibility can be enhanced.

Extending the Request Object

Koa2's ctx.request object is a wrapper around Node.js's native http.IncomingMessage, providing many convenient properties and methods. Developers can extend the Request object to add custom functionality.

Custom Properties

For example, you can extend the Request object to add an isMobile property to determine whether the request comes from a mobile device:

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

This way, subsequent middleware can directly use ctx.request.isMobile to check the request's origin.

Custom Methods

In addition to properties, you can also add custom methods to the Request object. For example, add a parseQuery method to parse query strings:

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

When used, you can call ctx.request.parseQuery() to get the parsed query parameter object.

Extending with Third-Party Libraries

The Koa2 community offers many third-party libraries to extend the functionality of the Request object. For example, koa-request-id can add a unique ID to each request:

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

After installation, each request's ctx.request.id will contain a unique identifier.

Extending the Response Object

The ctx.response object is a wrapper around Node.js's native http.ServerResponse and can similarly be extended to enhance functionality.

Custom Properties

For example, you can add a cache property to the Response object to control caching behavior:

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

When used, you can call ctx.response.cache(3600) to set the cache duration to 1 hour.

Custom Methods

You can also add custom methods to the Response object. For example, add a jsonp method to support JSONP responses:

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();
});

When used, you can call ctx.response.jsonp({ foo: 'bar' }) to return data in JSONP format.

Extending with Third-Party Libraries

The community also offers many libraries to extend the Response object's functionality. For example, koa-json can automatically convert response data to JSON format:

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

After installation, you can directly use ctx.body = { foo: 'bar' } to return JSON data without manually setting the Content-Type.

Combining Middleware for Extension

In practical development, it's common to combine middleware to extend the functionality of both Request and Response objects. For example, the following middleware extends both objects:

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

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

  await next();
});

This way, subsequent middleware can directly use ctx.request.getClientIP() and ctx.response.success() methods.

Dynamic vs. Static Extension

Koa2's extension methods can be divided into dynamic and static extensions. Dynamic extensions temporarily add properties or methods within middleware, while static extensions permanently add functionality by modifying the prototype chain of Request or Response.

Dynamic Extension Example

Dynamic extensions offer higher flexibility but redefine properties or methods with each request:

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

Static Extension Example

Static extensions modify the prototype chain and only need to be defined once:

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 };
};

Static extensions offer better performance but require caution to avoid naming conflicts.

Practical Use Cases for Extensions

Extending Request and Response objects has many practical applications in development. Here are some common examples:

User Authentication

Extend the Request object to add authentication-related methods:

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 Formatting

Extend the Response object to standardize API response formats:

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 Logging

Extend the Request object to log requests:

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

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

Considerations for Extensions

When extending Request and Response objects, keep the following in mind:

1. Naming Conflicts: Avoid clashes with native properties or third-party library properties.
2. Performance Impact: Dynamic extensions may slightly affect performance, especially in high-concurrency scenarios.
3. Maintainability: Encapsulate extension logic in standalone middleware for easier maintenance and reuse.

Comparison with Other Frameworks

Compared to other Node.js frameworks like Express, Koa2's Request and Response object extensions are more flexible. Express extensions are typically implemented via app.use or direct prototype modification, while Koa2's middleware mechanism makes extensions more modular.

Express Extension Example

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

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

In contrast, Koa2's extension approach aligns better with modern JavaScript's modular design principles.