koajs/koa

[][gitter-url] [][npm-url] [][github-action-url] [][coveralls-url] [](#backers) [](#sponsors) [][pr-welcoming-url] Expressive HTTP middleware framework for node.js to make web applications and APIs more enjoyable to write. Koa's middleware stack flows in a stack-like manner, allowing you to perform actions downstream then filter and manipulate the response upstream. Only methods that are common to nearly all HTTP servers are integrated directly into Koa's small ~570 SLOC codebase. This includes things like content negotiation, normalization of node inconsistencies, redirection, and a few others. Koa is not bundled with any middleware. ## 安装 Koa requires __node v18.0.0__ or higher for ES2015 and async function support. ``` npm install koa ``` ## Hello Koa ``` const Koa = require('koa'); const app = new Koa(); // response app.use(ctx => { ctx.body = 'Hello Koa'; }); app.listen(3000); ``` ## 入门 - [Kick-Off-Koa](https://github.com/koajs/kick-off-koa) - An intro to Koa via a set of self-guided workshops. - [Guide](docs/guide.md) - Go straight to the docs. ## 中间件 Koa is a middleware framework that can take two different kinds of functions as middleware: * async function * common function Here is an example of logger middleware with each of the different functions: ### ___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 中间件签名 The middleware signature changed between v1.x and v2.x. The older signature is deprecated. **Old signature middleware support has been removed in v3** Please see the [Migration Guide from v2.x to v3.x](docs/migration-v2-to-v3.md) for information on upgrading from v2.x to v3.x, and the [Migration Guide from v1.x to v2.x](docs/migration-v1-to-v2.md) for information on upgrading from v1.x to v2.x. ## Context, Request 和 Response Each middleware receives a Koa `Context` object that encapsulates an incoming http message and the corresponding response to that message. `ctx` is often used as the parameter name for the context object. ``` app.use(async (ctx, next) => { await next(); }); ``` Koa provides a `Request` object as the `request` property of the `Context`. Koa's `Request` object provides helpful methods for working with http requests which delegate to an [IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage) from the node `http` module. Here is an example of checking that a requesting client supports 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 provides a `Response` object as the `response` property of the `Context`. Koa's `Response` object provides helpful methods for working with http responses which delegate to a [ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse) . Koa's pattern of delegating to Node's request and response objects rather than extending them provides a cleaner interface and reduces conflicts between different middleware and with Node itself as well as providing better support for stream handling. The `IncomingMessage` can still be directly accessed as the `req` property on the `Context` and `ServerResponse` can be directly accessed as the `res` property on the `Context`. Here is an example using Koa's `Response` object to stream a file as the response body. ``` app.use(async (ctx, next) => { await next(); ctx.response.type = 'xml'; ctx.response.body = fs.createReadStream('really_large.xml'); }); ``` The `Context` object also provides shortcuts for methods on its `request` and `response`. In the prior examples, `ctx.type` can be used instead of `ctx.response.type` and `ctx.accepts` can be used instead of `ctx.request.accepts`. For more information on `Request`, `Response` and `Context`, see the [Request API Reference](docs/api/request.md), [Response API Reference](docs/api/response.md) and [Context API Reference](docs/api/context.md). ## Koa 应用 The object created when executing `new Koa()` is known as the Koa application object. The application object is Koa's interface with node's http server and handles the registration of middleware, dispatching to the middleware from http, default error handling, as well as configuration of the context, request and response objects. Learn more about the application object in the [Application API Reference](docs/api/index.md). ## 文档 - [Usage Guide](docs/guide.md) - [Error Handling](docs/error-handling.md) - [Koa for Express Users](docs/koa-vs-express.md) - [FAQ](docs/faq.md) - [API documentation](docs/api/index.md) ## 故障排除 Check the [Troubleshooting Guide](docs/troubleshooting.md) or [Debugging Koa](docs/guide.md#debugging-koa) in the general Koa guide. ## 运行测试 ``` $ npm test ``` ## 报告漏洞 To report a security vulnerability, please do not open an issue, as this notifies attackers of the vulnerability. Instead, please email [dead_horse](mailto:heyiyu.deadhorse@gmail.com), [jonathanong](mailto:me@jongleberry.com), and [niftylettuce](mailto:niftylettuce@gmail.com) to disclose. ## 作者 See [AUTHORS](AUTHORS). # 许可证 [MIT](https://github.com/koajs/koa/blob/master/LICENSE)

标签：API开发, Async/Await, CMS安全, DNS解析, ES2017, GNU通用公共许可证, HTTP服务, JavaScript, Koa, MITM代理, Node.js, Syscall, Web开发, Web框架, 中间件, 全栈, 后端开发, 开源项目, 异步编程, 数据可视化, 服务端, 自定义脚本, 自定义脚本, 轻量级框架