本文共 4456 字，大约阅读时间需要 14 分钟。

Koa框架入门指南

一、基本用法

1.1 架设 HTTP 服务

Koa 是一款简单高效的 Web 框架，仅需三行代码即可轻松架设一个 HTTP 服务。以下是实现步骤：

const Koa = require('koa');const app = new Koa();app.listen(3000);

运行后，打开浏览器访问 http://127.0.0.1:3000，你会看到 "Not Found" 页面。这是因为 Koa 并未指定返回内容。

通过脚手架构建服务

可以通过脚手架快速构建项目：

npm install koa-generator -g

创建项目：

koa2 -e hello-koa2

二、路由

2.1 默认路由

通过 ctx.request.path 判断请求路径，实现简单的路由：

const Koa = require('koa');const app = new Koa();const fs = require('fs');app.use(ctx => {    if (ctx.request.path !== '/') {        ctx.response.type = 'html';        ctx.response.body = 'Index Page1';    } else {        ctx.response.body = 'Hello World';    }}).listen(3000);

2.2 使用 koa-route 模块

原生路由较为复杂，推荐使用第三方模块 koa-route：

const Koa = require('koa');const route = require('koa-route');const fs = require('fs');const main = route.get('/', ctx => {    ctx.response.type = 'html';    ctx.response.body = 'Index Page1';});const about = route.get('/about', ctx => {    ctx.response.body = 'Hello World';});app.use(main);app.use(about);app.listen(3000);

三、中间件

3.1 中间件的概念

中间件是 Koa 核心的灵魂，位于 HTTP 请求和响应之间。通过 app.use() 加载中间件，中间件按栈式执行。每个中间件接受 Context 对象和下一个中间件的调用。

3.2 中间件栈执行顺序

中间件执行遵循先进后出原则：

const Koa = require('koa');const one = (ctx, next) => {    console.log('> one');    next();    console.log('< one');};const two = (ctx, next) => {    console.log('> two');    next();    console.log('< two');};const three = (ctx, next) => {    console.log('> three');    next();    console.log('< three');};app.use(one);app.use(two);app.use(three);app.listen(3000);

执行结果为：

> one > two > three < three < two < one

3.3 异步中间件

对于需要异步操作的中间件，需标记为 async 函数：

const fs = require('fs.promised');const Koa = require('koa');const main = async (ctx, next) => {    ctx.response.type = 'html';    ctx.response.body = await fs.readFile('./demos/template.html', 'utf8');};app.use(main);app.listen(3000);

3.4 中间件合成

使用 koa-compose 模块合成为一个中间件：

const Koa = require('koa');const compose = require('koa-compose');const logger = (ctx, next) => {    console.log(`${Date.now()} ${ctx.request.method} ${ctx.request.url}`);    next();};const main = ctx => {    ctx.response.body = 'Hello World';};const middlewares = compose([logger, main]);app.use(middlewares);app.listen(3000);

四、错误处理

4.1 500 错误

使用 ctx.throw() 方法抛出错误：

const Koa = require('koa');const app = new Koa();const main = ctx => {    ctx.throw(500);};app.use(main);app.listen(3000);

4.2 404 错误

手动设置响应状态码：

const Koa = require('koa');const app = new Koa();const main = ctx => {    ctx.response.status = 404;    ctx.response.body = 'Page Not Found';};app.use(main);app.listen(3000);

4.3 错误处理中间件

使用中间件捕获错误：

const Koa = require('koa');const app = new Koa();const handler = async (ctx, next) => {    try {        await next();    } catch (err) {        ctx.response.status = err.statusCode || 500;        ctx.response.body = { message: err.message };    }};const main = ctx => {    ctx.throw(500);};app.use(handler);app.use(main);app.listen(3000);

4.4 错误事件监听

监听 Koa 的错误事件：

const Koa = require('koa');const app = new Koa();const main = ctx => {    ctx.throw(500);};app.on('error', (err, ctx) => {    console.error('server error', err);});app.use(main);app.listen(3000);

五、Web 应用功能

5.1 Cookies

通过 ctx.cookies 管理 Cookie：

const Koa = require('koa');const app = new Koa();const main = (ctx) => {    const views = ctx.cookies.get('view') || 0;    ctx.cookies.set('view', views + 1);    ctx.response.body = `${views + 1} views`;};app.use(main);app.listen(3000);

5.2 表单处理

使用 koa-body 模块处理 POST 请求：

const Koa = require('koa');const koaBody = require('koa-body');const app = new Koa();const main = async (ctx) => {    const body = ctx.request.body;    if (!body.name) {        ctx.throw(400, '.name required');    }    ctx.body = { name: body.name };};app.use(koaBody());app.use(main);app.listen(3000);

5.3 文件上传

处理文件上传：

const os = require('os');const path = require('path');const fs = require('fs');const Koa = require('koa');const koaBody = require('koa-body');const app = new Koa();const main = async (ctx) => {    const tmpdir = os.tmpdir();    const filePaths = [];    const files = ctx.request.body.files || {};    for (let key in files) {        const file = files[key];        const filePath = path.join(tmpdir, file.name);        const reader = fs.createReadStream(file.path);        const writer = fs.createWriteStream(filePath);        reader.pipe(writer);        filePaths.push(filePath);    }    ctx.body = filePaths;};app.use(koaBody({ multipart: true }));app.use(main);app.listen(3000);

转载地址：http://hxjfk.baihongyu.com/