The composition and function of the Context object

Composition and Role of the Context Object

The Context object in the Koa2 framework encapsulates Node.js's native request and response objects, providing a unified API interface to simplify web development. A new Context instance is created for each request and persists throughout the entire middleware processing pipeline.

Core Property Analysis

The Context object includes the following main properties:

1. request: Koa's Request object, which encapsulates Node.js's native http.IncomingMessage.
2. response: Koa's Response object, which encapsulates Node.js's native http.ServerResponse.
3. app: A reference to the application instance.
4. state: A recommended namespace for passing information between middleware.
5. cookies: Convenient methods for handling cookies.

app.use(async (ctx) => {
  // Access the request object
  console.log(ctx.request.method);
  
  // Access the response object
  ctx.response.status = 200;
  
  // Use state to share data
  ctx.state.user = await User.find(1);
  
  // Manipulate cookies
  ctx.cookies.set('name', 'value');
});

Commonly Used Proxy Properties

The Context object proxies many commonly used properties of Request and Response, allowing direct access via ctx:

// Request proxy properties example
ctx.header      // Equivalent to ctx.request.header
ctx.method      // Equivalent to ctx.request.method
ctx.url         // Equivalent to ctx.request.url
ctx.path        // Equivalent to ctx.request.path
ctx.query       // Equivalent to ctx.request.query
ctx.host        // Equivalent to ctx.request.host

// Response proxy properties example
ctx.status      // Equivalent to ctx.response.status
ctx.body        // Equivalent to ctx.response.body
ctx.set         // Equivalent to ctx.response.set
ctx.type        // Equivalent to ctx.response.type

Detailed Explanation of Common Methods

1. The throw Method

Used to throw HTTP errors:

ctx.throw(404, 'Resource not found');
ctx.throw(400, 'Parameter error', { user: user.id });

2. The assert Method

Assertion validation; throws an error if the condition is not met:

ctx.assert(ctx.state.user, 401, 'Please log in first');
ctx.assert(ctx.query.id, 400, 'Missing ID parameter');

3. The redirect Method

Implements page redirection:

ctx.redirect('/login');
ctx.redirect('https://example.com');

4. The attachment Method

Sets up file downloads:

ctx.attachment('report.pdf');
ctx.body = fs.createReadStream('/path/to/report.pdf');

Request Handling

1. Retrieving Request Parameters

// Query string ?name=koa
ctx.query.name  // "koa"

// POST request body
const body = await parseBody(ctx);

// Dynamic route parameters
router.get('/user/:id', (ctx) => {
  ctx.params.id  // 123
});

2. Handling File Uploads

const koaBody = require('koa-body');

app.use(koaBody({
  multipart: true,
  formidable: {
    uploadDir: './uploads'
  }
}));

app.use(async (ctx) => {
  const file = ctx.request.files.file;
  const reader = fs.createReadStream(file.path);
  const stream = fs.createWriteStream(path.join('./uploads', file.name));
  reader.pipe(stream);
});

Response Handling

1. Setting Response Headers

ctx.set('Cache-Control', 'no-cache');
ctx.set({
  'X-Powered-By': 'Koa',
  'Author': 'Your Name'
});

2. Sending Different Types of Responses

// JSON response
ctx.body = { success: true };

// HTML response
ctx.type = 'html';
ctx.body = '<h1>Hello World</h1>';

// Stream response
ctx.body = fs.createReadStream('./large-file.txt');

3. Custom Response Handling

app.use(async (ctx, next) => {
  await next();
  
  // Unified 404 handling
  if (ctx.status === 404 && !ctx.body) {
    ctx.status = 404;
    ctx.body = 'Custom 404 page';
  }
  
  // Unified error handling
  if (ctx.status >= 400) {
    ctx.app.emit('error', ctx.status, ctx);
  }
});

State Management

ctx.state is the recommended namespace for sharing data between middleware:

// Authentication middleware
app.use(async (ctx, next) => {
  const token = ctx.headers['authorization'];
  ctx.state.user = await verifyToken(token);
  await next();
});

// Business middleware
app.use(async (ctx) => {
  const posts = await Post.findAll({
    where: { userId: ctx.state.user.id }
  });
  ctx.body = posts;
});

Advanced Usage

1. Customizing the Context Prototype

You can extend the Context prototype to add custom methods:

app.context.db = require('./database');

app.use(async ctx => {
  const users = await ctx.db.query('SELECT * FROM users');
  ctx.body = users;
});

2. Request/Response Interception

app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  ctx.set('X-Response-Time', `${ms}ms`);
});

3. Content Negotiation

app.use(async (ctx) => {
  ctx.response.vary('Accept');
  
  switch (ctx.request.accepts('json', 'html')) {
    case 'json':
      ctx.type = 'json';
      ctx.body = { data: '...' };
      break;
    case 'html':
      ctx.type = 'html';
      ctx.body = '<p>data</p>';
      break;
    default:
      ctx.type = 'text';
      ctx.body = 'data';
  }
});

Error Handling Mechanism

The Context object integrates error-handling capabilities:

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = {
      message: err.message,
      code: err.code
    };
    ctx.app.emit('error', err, ctx);
  }
});

// Triggering errors
app.use(async (ctx) => {
  if (!ctx.query.token) {
    const error = new Error('Token required');
    error.status = 401;
    throw error;
  }
});

Performance Optimization Tips

1. Avoiding Memory Leaks

// Bad example: Attaching large objects to the context
app.use(async (ctx) => {
  ctx.hugeData = await getHugeData(); // Risk of memory leak
});

// Correct approach
app.use(async (ctx) => {
  const hugeData = await getHugeData();
  ctx.body = processData(hugeData);
});

2. Proper Use of Stream Processing

app.use(async (ctx) => {
  ctx.type = 'application/json';
  ctx.body = database.query('SELECT * FROM large_table')
    .stream()
    .pipe(JSONStream.stringify());
});

3. Batch Processing Middleware

const compose = require('koa-compose');

const middleware1 = async (ctx, next) => { /* ... */ };
const middleware2 = async (ctx, next) => { /* ... */ };

app.use(compose([middleware1, middleware2]));