Development of custom route resolvers

Koa2 is a lightweight Node.js framework, and its middleware mechanism and onion model allow developers to flexibly handle HTTP requests. A custom route resolver can better meet the needs of complex business scenarios, such as dynamic routing, permission control, or route grouping. Below, we will break down how to develop a custom route resolver step by step, from implementation principles to specific code.

Core Concepts of a Route Resolver

The core function of a route resolver is to map HTTP request paths and methods (GET, POST, etc.) to corresponding handler functions. Koa2 does not natively provide routing functionality, so it usually requires third-party libraries or custom implementations. A custom route resolver needs to address the following issues:

1. Route Matching: How to find the corresponding handler function based on the URL path and HTTP method.
2. Parameter Extraction: How to extract parameters from dynamic routes (e.g., /users/:id).
3. Middleware Support: How to apply middleware to specific routes.

Basic Route Resolver Implementation

The simplest route resolver can use a JavaScript object to store route information, where the key is the path and method, and the value is the corresponding handler function. For example:

const router = {
  'GET /users': async (ctx) => {
    ctx.body = 'User list';
  },
  'GET /users/:id': async (ctx) => {
    ctx.body = `User ID: ${ctx.params.id}`;
  }
};

When used, the key is constructed by concatenating ctx.method and ctx.path, and the corresponding handler function is looked up in the router object:

app.use(async (ctx, next) => {
  const routeKey = `${ctx.method} ${ctx.path}`;
  const handler = router[routeKey];
  if (handler) {
    await handler(ctx, next);
  } else {
    await next();
  }
});

This implementation is simple but does not support dynamic parameters or middleware.

Route Resolver with Dynamic Parameter Support

Dynamic routes (e.g., /users/:id) require parsing parameters from the URL. This can be achieved using regular expressions to match paths and extract parameters. Here’s an improved version of the route resolver:

const routes = [
  {
    method: 'GET',
    path: '/users/:id',
    handler: async (ctx) => {
      ctx.body = `User ID: ${ctx.params.id}`;
    }
  }
];

app.use(async (ctx, next) => {
  const matchedRoute = routes.find(route => {
    // Convert the path to a regular expression, e.g., /users/:id -> /^\/users\/([^\/]+)$/
    const pattern = route.path.replace(/:\w+/g, '([^\/]+)');
    const regex = new RegExp(`^${pattern}$`);
    return route.method === ctx.method && regex.test(ctx.path);
  });

  if (matchedRoute) {
    // Extract parameters
    const pattern = matchedRoute.path.replace(/:\w+/g, '([^\/]+)');
    const regex = new RegExp(`^${pattern}$`);
    const matches = ctx.path.match(regex);
    ctx.params = {};
    matchedRoute.path.split('/').forEach((segment, index) => {
      if (segment.startsWith(':')) {
        const paramName = segment.slice(1);
        ctx.params[paramName] = matches[index];
      }
    });
    await matchedRoute.handler(ctx, next);
  } else {
    await next();
  }
});

Route Resolver with Middleware Support

Middleware is a core feature of Koa2, and a custom route resolver also needs to support middleware. You can configure an array of middleware for each route and execute them sequentially:

const routes = [
  {
    method: 'GET',
    path: '/admin',
    middlewares: [
      async (ctx, next) => {
        if (!ctx.headers['x-auth-token']) {
          ctx.status = 401;
          ctx.body = 'Unauthorized';
          return;
        }
        await next();
      }
    ],
    handler: async (ctx) => {
      ctx.body = 'Admin panel';
    }
  }
];

app.use(async (ctx, next) => {
  const matchedRoute = routes.find(route => {
    const pattern = route.path.replace(/:\w+/g, '([^\/]+)');
    const regex = new RegExp(`^${pattern}$`);
    return route.method === ctx.method && regex.test(ctx.path);
  });

  if (matchedRoute) {
    // Execute the middleware chain
    const middlewareChain = [...matchedRoute.middlewares, matchedRoute.handler];
    let idx = 0;
    const dispatch = async (i) => {
      if (i < middlewareChain.length) {
        await middlewareChain[i](ctx, () => dispatch(i + 1));
      }
    };
    await dispatch(0);
  } else {
    await next();
  }
});

Route Grouping and Nesting

In real-world projects, routes may need to be grouped, such as adding logging middleware to all routes starting with /api. This can be achieved using prefix matching:

const apiRoutes = {
  prefix: '/api',
  middlewares: [
    async (ctx, next) => {
      console.log(`API request: ${ctx.path}`);
      await next();
    }
  ],
  routes: [
    {
      method: 'GET',
      path: '/users',
      handler: async (ctx) => {
        ctx.body = 'API User list';
      }
    }
  ]
};

app.use(async (ctx, next) => {
  if (ctx.path.startsWith(apiRoutes.prefix)) {
    // Execute group middleware
    const middlewareChain = [...apiRoutes.middlewares];
    for (const route of apiRoutes.routes) {
      const fullPath = `${apiRoutes.prefix}${route.path}`;
      const pattern = fullPath.replace(/:\w+/g, '([^\/]+)');
      const regex = new RegExp(`^${pattern}$`);
      if (route.method === ctx.method && regex.test(ctx.path)) {
        middlewareChain.push(route.handler);
        break;
      }
    }
    let idx = 0;
    const dispatch = async (i) => {
      if (i < middlewareChain.length) {
        await middlewareChain[i](ctx, () => dispatch(i + 1));
      }
    };
    await dispatch(0);
  } else {
    await next();
  }
});

Performance Optimization and Caching

Frequent regular expression matching can impact performance, so you can optimize by caching route matching results:

const routeCache = new Map();

app.use(async (ctx, next) => {
  const cacheKey = `${ctx.method} ${ctx.path}`;
  if (routeCache.has(cacheKey)) {
    const { params, handler } = routeCache.get(cacheKey);
    ctx.params = params;
    await handler(ctx, next);
    return;
  }

  // Original route matching logic...
  if (matchedRoute) {
    routeCache.set(cacheKey, { params: ctx.params, handler: matchedRoute.handler });
    await matchedRoute.handler(ctx, next);
  } else {
    await next();
  }
});

Error Handling and Fallback Logic

A custom route resolver needs to handle cases where no route is matched, such as returning a 404 or redirecting:

app.use(async (ctx, next) => {
  // Route matching logic...
  if (!matchedRoute) {
    ctx.status = 404;
    ctx.body = 'Not Found';
    return;
  }
  await next();
});

You can also configure error-handling middleware for specific routes:

const routes = [
  {
    method: 'GET',
    path: '/danger',
    handler: async (ctx) => {
      throw new Error('Something went wrong!');
    },
    errorHandler: async (ctx, error) => {
      ctx.status = 500;
      ctx.body = `Error: ${error.message}`;
    }
  }
];

app.use(async (ctx, next) => {
  try {
    // Route matching and execution logic...
    if (matchedRoute) {
      await matchedRoute.handler(ctx, next);
    } else {
      await next();
    }
  } catch (error) {
    if (matchedRoute?.errorHandler) {
      await matchedRoute.errorHandler(ctx, error);
    } else {
      throw error;
    }
  }
});