知识库

Appearance

Return to top
On this page

Koa快速入门

Koa是由Express原班人马打造的新一代Web框架，致力于成为更小、更富有表现力、更健壮的Web框架。通过利用async函数，Koa让你摆脱回调地狱，并极大地简化了错误处理。

安装Koa

创建项目

首先创建一个新的Node.js项目并安装Koa：

bash
mkdir my-koa-app
cd my-koa-app
npm init -y
npm install koa

基本服务器

创建一个最简单的Koa服务器：

javascript
// app.js
const Koa = require('koa');
const app = new Koa();

app.use(async ctx => {
  ctx.body = 'Hello World';
});

app.listen(3000);
console.log('Server running on port 3000');

运行服务器：

bash
node app.js

Koa vs Express对比

Koa与Express的主要区别在于：

  • 异步处理：Koa原生支持async/await，而Express主要基于回调
  • 中间件模型：Koa使用洋葱模型，Express使用线性模型
  • 体积：Koa核心更小，功能通过中间件扩展
  • 上下文：Koa将req和res合并为ctx对象

基本中间件

Koa的中间件采用函数形式，接收ctx和next参数：

javascript
const Koa = require('koa');
const app = new Koa();

// 最简单的中间件
app.use(async (ctx, next) => {
  console.log('A');
  await next();
  console.log('A end');
});

app.use(async (ctx, next) => {
  console.log('B');
  await next();
  console.log('B end');
});

app.use(async ctx => {
  console.log('Response');
  ctx.body = 'Hello Koa';
});

app.listen(3000);
// 输出: A -> B -> Response -> B end -> A end

上下文(Context)对象

Koa将Node.js的request和response对象封装到单独的context对象中：

javascript
app.use(async ctx => {
  // ctx.request 和 ctx.response 是Koa的请求和响应对象
  // ctx.req 和 ctx.res 是Node.js的原生对象
  
  // 常用属性
  console.log(ctx.method);    // HTTP方法
  console.log(ctx.url);       // URL
  console.log(ctx.path);      // 路径
  console.log(ctx.query);     // 查询参数
  console.log(ctx.headers);   // 请求头
  
  // 响应设置
  ctx.body = 'Response body';  // 设置响应体
  ctx.status = 200;           // 设置状态码
  ctx.type = 'text/html';     // 设置内容类型
});

路由处理

Koa本身不提供路由功能，但可以使用koa-router中间件：

bash
npm install @koa/router
javascript
const Koa = require('koa');
const Router = require('@koa/router');
const app = new Koa();
const router = new Router();

// GET路由
router.get('/', async (ctx) => {
  ctx.body = 'Home page';
});

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

// POST路由
router.post('/users', async (ctx) => {
  ctx.body = 'Create user';
});

app.use(router.routes());
app.listen(3000);

请求体解析

Koa需要中间件来解析请求体：

bash
npm install koa-bodyparser
javascript
const Koa = require('koa');
const Router = require('@koa/router');
const bodyParser = require('koa-bodyparser');

const app = new Koa();
const router = new Router();

app.use(bodyParser());

router.post('/users', async (ctx) => {
  const { name, email } = ctx.request.body;
  ctx.body = { name, email };
});

app.use(router.routes());
app.listen(3000);

静态文件服务

使用koa-static中间件提供静态文件服务：

bash
npm install koa-static
javascript
const Koa = require('koa');
const serve = require('koa-static');

const app = new Koa();

// 提供public目录下的静态文件
app.use(serve('./public'));

app.listen(3000);

错误处理

Koa提供了全局错误处理机制：

javascript
const app = new Koa();

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

app.use(async (ctx) => {
  if (ctx.path === '/error') {
    throw new Error('Something went wrong');
  }
  ctx.body = 'OK';
});

app.listen(3000);

常用中间件

日志中间件

javascript
const logger = async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
};

app.use(logger);

CORS中间件

bash
npm install @koa/cors
javascript
const cors = require('@koa/cors');

app.use(cors());

推荐的项目结构 

my-koa-app/
├── package.json
├── app.js
├── middleware/
│   ├── logger.js
│   └── error-handler.js
├── routes/
│   ├── index.js
│   └── user.js
├── controllers/
│   └── user-controller.js
├── models/
│   └── user.js
├── public/
│   ├── css/
│   └── js/
└── config/
    └── index.js

环境配置

使用环境变量管理配置：

javascript
const port = process.env.PORT || 3000;
const env = process.env.NODE_ENV || 'development';

这个快速入门涵盖了Koa的核心概念，接下来可以深入了解中间件系统、路由管理等高级特性。