Expressive middleware for node.js using ES2017 async functions

This repository is empty

Auto Translate

Koa 是一个富有表现力的 node.js HTTP 中间件框架，让 Web 应用和 API 的编写过程更加愉悦。Koa 的中间件栈以类似堆栈的方式流转，使你能够先执行下游操作，然后在上游对响应进行过滤和处理。

Koa 精简的代码库仅约 570 行代码（SLOC），仅直接集成了几乎所有 HTTP 服务器都通用的方法。其中包括内容协商、node 不一致性的规范化、重定向以及其他一些功能。

Koa 未捆绑任何中间件。

安装

Koa 需要 node v18.0.0 或更高版本以支持 ES2015 和 async 函数。

npm install koa

你好 Koa

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

// response
app.use(ctx => {
  ctx.body = 'Hello Koa';
});

app.listen(3000);

快速开始

Kick-Off-Koa - 通过一系列自主学习的实践课程来介绍 Koa。
指南 - 直接查看文档。

中间件

Koa 是一个中间件框架，它可以将两种不同类型的函数作为中间件：

async 函数
- 普通函数

以下是使用不同函数类型实现的日志中间件示例：

async 函数（Node v7.6+）

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

常用函数

// Middleware normally takes two parameters (ctx, next), ctx is the context for one request,
// next is a function that is invoked to execute the downstream middleware. It returns a Promise with a then function for running code after completion.

app.use((ctx, next) => {
  const start = Date.now();
  return next().then(() => {
    const ms = Date.now() - start;
    console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
  });
});

Koa v1.x 中间件签名

v1.x 和 v2.x 版本之间的中间件签名发生了变化。旧版签名已被弃用。

v3 版本已移除对旧版签名中间件的支持

有关从 v2.x 升级到 v3.x 的信息，请参阅从 v2.x 迁移到 v3.x 的指南；有关从 v1.x 升级到 v2.x 的信息，请参阅从 v1.x 迁移到 v2.x 的指南。

上下文（Context）、请求（Request）和响应（Response）

每个中间件都会接收一个 Koa Context 对象，该对象封装了传入的 HTTP 消息以及对该消息的相应响应。ctx 常被用作上下文对象的参数名。

app.use(async (ctx, next) => { await next(); });

Koa 提供了一个 Request 对象，作为 Context 的 request 属性。 Koa 的 Request 对象提供了一些实用的方法来处理 HTTP 请求，这些方法委托给了 node http 模块中的 IncomingMessage。

以下是一个检查请求客户端是否支持 xml 的示例。

app.use(async (ctx, next) => {
  ctx.assert(ctx.request.accepts('xml'), 406);
  // equivalent to:
  // if (!ctx.request.accepts('xml')) ctx.throw(406);
  await next();
});

Koa 提供了一个 Response 对象，作为 Context 的 response 属性。 Koa 的 Response 对象提供了一些实用的方法来处理 HTTP 响应，这些方法委托给了 ServerResponse。

Koa 采用委托给 Node 的请求和响应对象而非对其进行扩展的模式，这提供了更清晰的接口，减少了不同中间件之间以及与 Node 本身的冲突，同时也更好地支持流处理。IncomingMessage 仍可通过 Context 的 req 属性直接访问，ServerResponse 可通过 Context 的 res 属性直接访问。

以下是一个使用 Koa 的 Response 对象将文件作为响应体进行流式传输的示例。

app.use(async (ctx, next) => {
  await next();
  ctx.response.type = 'xml';
  ctx.response.body = fs.createReadStream('really_large.xml');
});

Context 对象还为其 request 和 response 上的方法提供了快捷方式。在前面的示例中，可以使用 ctx.type 代替 ctx.response.type，使用 ctx.accepts 代替 ctx.request.accepts。

有关 Request、Response 和 Context 的更多信息，请参阅 Request API 参考、Response API 参考和 Context API 参考。

Koa 应用程序

执行 new Koa() 时创建的对象称为 Koa 应用程序对象。

应用程序对象是 Koa 与 node 的 http 服务器的接口，负责中间件的注册、从 http 向中间件的调度、默认错误处理，以及上下文、请求和响应对象的配置。

在 Application API 参考中了解有关应用程序对象的更多信息。

文档

故障排除

请查看故障排除指南或 general Koa 指南中的调试 Koa。

运行测试

$ npm test

报告漏洞

若要报告安全漏洞，请不要创建 issue，因为这会将漏洞信息泄露给攻击者。请通过电子邮件向 dead_horse、jonathanong 和 niftylettuce 进行披露。

作者

详见 AUTHORS。

社区

支持者

通过每月捐赠支持我们，助力我们持续开展各项活动。

赞助商

成为赞助商，您的 logo 将展示在我们 Github 上的 README 中，并附带指向您网站的链接。

许可证

MIT

Introduction

koajs/koa：Koa 是由 Express.js 团队精心打造的一款基于 Node.js 的创新性 web 框架。该框架采用 ES6 生成器（现已升级为 async/await）以简化中间件编程，同时具备更轻量级的核心架构和更出色的错误处理功能。【此简介由AI生成】

MIT JavaScript 1.3 KCommitsweb框架

Customize your domain

README

Code of conduct

80035.69 K3.23 KVisit GitHub

koa:基于 Node.js 的 HTTP 中间件框架项目

安装