Node.js / 系统课时
实现基础路由
实现基础路由
原生 http.createServer() 只把请求交给一个回调,不会自动匹配控制器。基础路由可以先用“HTTP 方法 + pathname”作为匹配键,再把请求分发到独立处理函数。本篇会实现静态路由表,并正确区分查询参数、404 和 405。
学习目标
- 从
req.method与req.url提取稳定的路由匹配条件。 - 用路由表把多个处理函数从主回调中拆开。
- 正确区分“路径不存在”的 404 与“路径存在但方法不允许”的 405。
路由匹配不要直接使用完整 req.url
req.url 通常同时包含路径与查询字符串,例如 GET /search?q=node。如果直接拿完整字符串做键,/search?q=node 和 /search?q=http 会被误认为两个路由。先用 new URL(req.url, 'http://localhost') 解析,再只用 url.pathname 匹配。
一个请求 GET /search?q=node 应得到两个不同的信息:路由键是 GET /search,业务参数是 url.searchParams.get('q'),值为 node。查询参数属于处理函数输入,不属于静态路由身份。
用方法和路径建立路由表
基础路由表可以直接保存 { method, path, handler }。匹配时先找方法和路径都相同的项;若路径存在但方法不同,返回 405 并设置 Allow;若路径根本不存在,再返回 404。

这种做法适合几十条以内的静态路由和学习项目。它不会自动支持 /users/:id、通配符、中间件或嵌套路由,因此不要把字符串精确匹配误写成“参数路由”。
完整实现静态路由分发
下面示例定义三个路由:GET /、GET /search 与 POST /users。sendJson() 统一响应格式,主回调只负责解析 URL、查找路由和处理未匹配情况。
const http = require('node:http');
function sendJson(res, statusCode, payload, extraHeaders = {}) {
// 统一 JSON 响应,避免每个 handler 重复设置头部。
const body = JSON.stringify(payload);
res.writeHead(statusCode, {
'Content-Type': 'application/json; charset=utf-8',
'Content-Length': Buffer.byteLength(body),
...extraHeaders,
});
res.end(body);
}
// 路由表只保存静态 method、path 与对应处理函数。
const routes = [
{
method: 'GET',
path: '/',
handler(req, res) {
sendJson(res, 200, { message: 'home' });
},
},
{
method: 'GET',
path: '/search',
handler(req, res, url) {
sendJson(res, 200, { q: url.searchParams.get('q') ?? '' });
},
},
{
method: 'POST',
path: '/users',
handler(req, res) {
sendJson(res, 201, { created: true });
},
},
];
const server = http.createServer((req, res) => {
const method = req.method ?? 'GET';
const url = new URL(req.url ?? '/', 'http://localhost');
const pathname = url.pathname;
// 先做 method + path 精确匹配,避免 GET 与 POST 共用错误处理器。
const route = routes.find(
(item) => item.method === method && item.path === pathname,
);
if (route) {
route.handler(req, res, url);
return;
}
// 路径存在但方法不匹配时返回 405,并声明允许的方法。
const allowedMethods = routes
.filter((item) => item.path === pathname)
.map((item) => item.method);
if (allowedMethods.length > 0) {
sendJson(
res,
405,
{ error: 'Method Not Allowed' },
{ Allow: allowedMethods.join(', ') },
);
return;
}
// 连 pathname 都不存在时才返回 404。
sendJson(res, 404, { error: 'Not Found' });
});
server.listen(3000, () => {
console.log('Listening on http://localhost:3000');
});预期输出
Listening on http://localhost:3000保存为 server.js 并启动后,在另一个终端执行:
curl -s "http://localhost:3000/search?q=node"; echo
curl -s -o /dev/null -w "%{http_code}\n" -X POST "http://localhost:3000/search"
curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:3000/missing"预期输出
{"q":"node"}
405
404这里的 405 说明 /search 这个路径确实存在,但没有 POST 处理器;404 则表示 /missing 没有任何路由项。把二者区分开后,客户端和测试工具更容易判断失败原因。
处理尾斜杠与 HEAD 的边界
字符串精确匹配会把 /users 与 /users/ 当成两个不同路径。若项目决定忽略尾斜杠,可以在匹配前统一规则:根路径 / 保持不变,其他 pathname 若以 / 结尾就去掉最后一个字符。规则必须全局一致,不能只对部分路由处理。
HEAD 也需要显式决定策略。上面的路由表只有 GET /,因此 HEAD / 会返回 405;如果希望 HEAD 复用 GET 的状态码和响应头,就应专门增加 HEAD 路由或在匹配层实现明确的 HEAD 回退,而不是假设 Node.js 会替路由器自动转换方法。
什么时候该升级到路由库
当静态路由超过约 20~30 条,或开始需要 /users/:id、多层中间件、路由前缀和统一错误处理时,线性 find() 会让规则越来越难维护。此时可以迁移到成熟 Web 框架或路由库;但无论换成什么工具,底层判断仍然围绕方法、路径、参数解析与未匹配响应展开。
在小型服务里,先把路由键固定为“规范化后的 pathname + HTTP 方法”,再把查询参数留给 handler,是最容易测试也最不容易混淆的基础实现。