Koa. Part 1.

Koa. Part 1.


Introduction

Введение

Koa is a new web framework designed by the team behind Express, which aims to be a smaller, more expressive, and more robust foundation for web applications and APIs.

Koa - это новая веб-инфраструктура, разработанная командой Express, которая направлена ​​на меньшую, более выразительную и более надежную основу для веб-приложений и API.

Through leveraging generators Koa allows you to ditch callbacks and greatly increase error-handling.

Благодаря использованию генераторов Koa позволяет выполнять обратные вызовы и значительно увеличивать обработку ошибок.

Koa does not bundle any middleware within core, and provides an elegant suite of methods that make writing servers fast and enjoyable.

Koa не связывает какое-либо промежуточное ПО внутри ядра и предоставляет элегантный набор методов, которые делают письменные серверы быстрыми и приятными.

Installation

Установка

Koa requires node v7.6.0 or higher for ES2015 and async function support.

Koa требует узла v7.6.0 или выше для ES2015 и поддержки асинхронной функции.

You can quickly install a supported version of node with your favorite version manager:

Вы можете быстро установить поддерживаемую версию узла с вашим любимым менеджером версий: 

 $ nvm install 7 
 $ npm i koa 
 $ node my-koa-app.js



Async Functions with Babel

Асинхронные функции с Babel

To use async functions in Koa in versions of node < 7.6, we recommend using babel's require hook .

Чтобы использовать async функции в Koa в версиях узла <7.6, мы рекомендуем использовать привязку babel . 

 require('babel-core/register');
 // require the rest of the app that needs to be transpiled after the hook 
// требуется остальное приложение, которое необходимо перевести после перехвата 
 const app = require('./app');



To parse and transpile async functions, you should at a minimum have the transform-async-to-generator or transform-async-to-module-method plugins.

Для синтаксического анализа и переадресации асинхронных функций вы должны иметь как минимум плагины transform-async-to-generator или transform-async-to-module-method .

For example, in your .babelrc file, you should have:

Например, в вашем файле .babelrc вы должны иметь: 

 {
  "plugins": ["transform-async-to-generator"] 
 }



You can also use the env preset with a target option "node": "current" instead.

Вы также можете использовать пресет env с целевой опцией "node": "current" вместо этого "node": "current" .

Application

Приложение

A Koa application is an object containing an array of middleware functions which are composed and executed in a stack-like manner upon request.

Приложение Koa представляет собой объект, содержащий массив функций промежуточного программного обеспечения, которые по запросу формируются и выполняются по стеку.

Koa is similar to many other middleware systems that you may have encountered such as Ruby's Rack, Connect, and so on - however a key design decision was made to provide high level "sugar" at the otherwise low-level middleware layer.

Koa похож на многие другие системы промежуточного программного обеспечения, с которыми вы столкнулись, например, Ruby's Rack, Connect и т. Д. - однако было принято ключевое дизайнерское решение, чтобы обеспечить высокий уровень «сахара» на уровне промежуточного программного обеспечения низкого уровня.

This improves interoperability, robustness, and makes writing middleware much more enjoyable.

Это улучшает интероперабельность, надежность и делает удобство написания промежуточного программного обеспечения более приятным.

This includes methods for common tasks like content-negotiation, cache freshness, proxy support, and redirection among others.

Это включает в себя методы для общих задач, таких как согласование контента, кеш-свежесть, поддержка прокси-сервера и перенаправление между другими.

Despite supplying a reasonably large number of helpful methods Koa maintains a small footprint, as no middleware are bundled.

Несмотря на то, что поставляется достаточно разумное количество полезных методов, Koa поддерживает небольшую площадь, поскольку в комплект поставки не входит промежуточное программное обеспечение.

The obligatory hello world application:

Обязательное приветственное приложение мира: 

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

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

 app.listen(3000);


Cascading

Каскадность

Koa middleware cascade in a more traditional way as you may be used to with similar tools - this was previously difficult to make user friendly with node's use of callbacks.

Koa промежуточного каскада более традиционным способом, так как вы можете использовать аналогичные инструменты - это было ранее трудно сделать удобным для пользователя с использованием обратных вызовов узла.

However with async functions we can achieve "true" middleware.

Однако с помощью асинхронных функций мы можем достичь «истинного» промежуточного программного обеспечения.

Contrasting Connect's implementation which simply passes control through series of functions until one returns, Koa invoke "downstream", then control flows back "upstream".

Контрастная реализация Connect, которая просто передает управление через ряд функций до тех пор, пока не вернется, Koa вызовет «вниз по течению», затем управление потоками обратно «вверх по течению».

The following example responds with "Hello World", however first the request flows through the x-response-time and logging middleware to mark when the request started, then continue to yield control through the response middleware.

Следующий пример отвечает «Hello World», однако сначала запрос протекает через промежуточное программное обеспечение x-response-time и logging для маркировки при запуске запроса, а затем продолжает получать контроль через промежуточное ПО ответа.

When a middleware invokes next() the function suspends and passes control to the next middleware defined.

Когда промежуточное программное обеспечение вызывает next() функция приостанавливает и передает управление следующему промежуточному программному обеспечению.

After there are no more middleware to execute downstream, the stack will unwind and each middleware is resumed to perform its upstream behaviour.

После того, как нет более промежуточного программного обеспечения для выполнения нисходящего потока, стек будет разматываться, и каждое промежуточное программное обеспечение будет возобновлено для выполнения его восходящего поведения. 

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

 // x-response-time

 app.use(async (ctx, next) => {
 const start = Date.now();
 await next();
 const ms = Date.now() - start;
 ctx.set('X-Response-Time', `${ms}ms`);
 }); 

 // logger

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

 // response

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

 app.listen(3000);



Settings

Настройки

Application settings are properties on the app instance, currently the following are supported:

Параметры приложения - это свойства экземпляра app , в настоящее время поддерживаются следующие параметры:

  • app.env defaulting to the NODE_ENV or "development" app.env для NODE_ENV или "development"
  • app.proxy when true proxy header fields will be trusted app.proxy когда истинным полям заголовка прокси будут доверять
  • app.subdomainOffset offset of .subdomains to ignore [2] app.subdomainOffset offset .subdomains игнорировать [2]

app.listen(...)

A Koa application is not a 1-to-1 representation of a HTTP server.

Приложение Koa не представляет собой 1-к-1 представление HTTP-сервера.

One or more Koa applications may be mounted together to form larger applications with a single HTTP server.

Одно или несколько приложений Koa могут монтироваться вместе, чтобы сформировать более крупные приложения с одним HTTP-сервером.

Create and return an HTTP server, passing the given arguments to Server#listen()

. Создайте и верните HTTP-сервер, передав данные аргументы Server#listen()

. These arguments are documented on nodejs.org .

Эти аргументы задокументированы на nodejs.org .

The following is a useless Koa application bound to port 3000 :

Следующее - бесполезное приложение Koa, связанное с портом 3000 : 

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



The app.listen(...) method is simply sugar for the following:

Метод app.listen(...) - это просто сахар для следующего: 

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



This means you can spin up the same application as both HTTP and HTTPS or on multiple addresses:

Это означает, что вы можете развернуть то же приложение, что и HTTP и HTTPS, либо по нескольким адресам: 

 const http = require('http'); 
 const https = require('https'); 
 const Koa = require('koa'); 
 const app = new Koa();
 http.createServer(app.callback()).listen(3000); 
 https.createServer(app.callback()).listen(3001);


app.callback()

Return a callback function suitable for the http.createServer() method to handle a request.

Возвратите функцию обратного вызова, подходящую для http.createServer() для обработки запроса.

You may also use this callback function to mount your koa app in a Connect/Express app.

Вы также можете использовать эту функцию обратного вызова для монтирования своего приложения koa в приложении Connect / Express.

app.use(function)

Add the given middleware function to this application.

Добавьте данную промежуточную программу в это приложение.

See Middleware for more information.

Дополнительную информацию см. В разделе Middleware .

app.keys=

Set signed cookie keys.

Установите подписанные файлы cookie.

These are passed to KeyGrip , however you may also pass your own KeyGrip instance.

Они передаются в KeyGrip , однако вы также можете передать свой собственный экземпляр KeyGrip .

For example the following are acceptable:

Например, допустимы следующие: 

 app.keys = ['im a newer secret', 'i like turtle'];
 app.keys = new KeyGrip(['im a newer secret', 'i like turtle'], 'sha256');


These keys may be rotated and are used when signing cookies with the { signed: true } option:

Эти ключи могут быть повернуты и используются при подписании файлов cookie с опцией { signed: true } : 

 ctx.cookies.set('name', 'tobi', { signed: true });

app.context

app.context is the prototype from which ctx is created from.

app.context - это прототип, из которого создается ctx .

You may add additional properties to ctx by editing app.context .

Вы можете добавить дополнительные свойства в ctx , отредактировав app.context .

This is useful for adding properties or methods to ctx to be used across your entire app, which may be more performant (no middleware) and/or easier (fewer require() s) at the expense of relying more on ctx , which could be considered an anti-pattern.

Это полезно для добавления свойств или методов в ctx которые будут использоваться во всем приложении, что может быть более эффективным (без промежуточного программного обеспечения) и / или проще (меньше require() s) за счет того, что больше полагается на ctx , что может быть считается анти-шаблон.

For example, to add a reference to your database from ctx :

Например, чтобы добавить ссылку на вашу базу данных из ctx : 

 app.context.db = db();

 app.use(async ctx => {
 console.log(ctx.db);
 });


Note:

  • Many properties on ctx are defined using getters, setters, and Object.defineProperty() .
  • Многие свойства на ctx определяются с помощью геттеров, сеттеров и Object.defineProperty() .
  • You can only edit these properties (not recommended) by using Object.defineProperty() on app.context .
  • Вы можете редактировать эти свойства (не рекомендуется), используя Object.defineProperty() в app.context . See https://github.com/koajs/koa/issues/652 .
  • Mounted apps currently use its parent's ctx and settings.
  • В установленных приложениях в настоящее время используются ctx и настройки родителя.
  • Thus, mounted apps are really just groups of middleware.
  • Таким образом, установленные приложения - это действительно просто группы промежуточного программного обеспечения.

Error Handling

Обработка ошибок

By default outputs all errors to stderr unless app.silent is true .

По умолчанию app.silent все ошибки в stderr, если app.silent является true

The default error handler also won't outputs errors when err.status is 404 or err.expose is true .

Обработчик ошибок по умолчанию также не будет err.status ошибки, если err.status равен 404 или err.expose - true .

To perform custom error-handling logic such as centralized logging you can add an "error" event listener:

Для выполнения пользовательской логики обработки ошибок, такой как централизованное ведение журнала, вы можете добавить прослушиватель событий «error»: 

 app.on('error', err => {
 log.error('server error', err)
 });


If an error is in the req/res cycle and it is not possible to respond to the client, the Context instance is also passed:

Если в цикле req / res возникает ошибка, и на клиент невозможно ответить, экземпляр Context также передается: 

 app.on('error', (err, ctx) => {
 log.error('server error', err, ctx)
 });


When an error occurs and it is still possible to respond to the client, aka no data has been written to the socket, Koa will respond appropriately with a 500 "Internal Server Error".

При возникновении ошибки и по-прежнему можно ответить клиенту, так как данные не были записаны в сокет, Koa ответит соответствующим образом с «Внутренней ошибкой сервера» 500. In either case an app-level "error" is emitted for logging purposes. В любом случае «ошибка» уровня приложения испускается для целей ведения журнала.

Context

Контекст

A Koa Context encapsulates node's request and response objects into a single object which provides many helpful methods for writing web applications and APIs.

Контекст Koa инкапсулирует объекты request и response узла в один объект, который предоставляет множество полезных методов для написания веб-приложений и API.

These operations are used so frequently in HTTP server development that they are added at this level instead of a higher level framework, which would force middleware to re-implement this common functionality.

Эти операции используются так часто в разработке HTTP-сервера, что они добавляются на этом уровне, а не в структуру более высокого уровня, что заставило бы промежуточное ПО повторно реализовать эту общую функциональность.

A Context is created per request, and is referenced in middleware as the receiver, or the ctx identifier, as shown in the following snippet:

Context создается для каждого запроса и упоминается в промежуточном программном обеспечении как получатель или идентификатор ctx , как показано в следующем фрагменте: 

 app.use(async ctx => {
 ctx; // is the Context // является контекстом 
 ctx.request; // is a koa Request // является запросом koa 
 ctx.response // is a koa Response // является ответом koa 
 });


Many of the context's accessors and methods simply delegate to their ctx.request or ctx.response equivalents for convenience, and are otherwise identical.

Многие из аксессуаров и методов контекста просто делегируют их эквиваленты ctx.request или ctx.response для удобства и в остальном идентичны.

For example ctx.type and ctx.length delegate to the response object, and ctx.path and ctx.method delegate to the request .

Например, ctx.type и ctx.length для объекта response , а ctx.path и ctx.method делегируют request .

API

Context specific methods and accessors.

Context зависимые методы и аксессоры.

ctx.req

Node's request object.

Объект request узла.

ctx.res

Node's response object.

Объект response узла.

Bypassing Koa's response handling is not supported .

Обход управления обработкой Koa не поддерживается .

Avoid using the following node properties:

Избегайте использования следующих свойств узла:

  • res.statusCode
  • res.writeHead()
  • res.write()
  • res.end()

ctx.request

A koa Request object.

Объект Request koa.

ctx.response

A koa Response object.

Объект Response koa.

ctx.state

The recommended namespace for passing information through middleware and to your frontend views.

Рекомендуемое пространство имен для передачи информации через промежуточное программное обеспечение и ваши представления в интерфейсе. 

 ctx.state.user = await User.find(id);

ctx.app

Application instance reference.

Ссылка на экземпляр приложения.

ctx.cookies.get(name, [options])

Get cookie name with options :

Получить name файла cookie с options :

  • signed the cookie requested should be signed
  • signed запрошенный файл cookie должен быть подписан

koa uses the cookies module where options are simply passed.

koa использует модуль cookie, где параметры просто передаются.

ctx.cookies.set(name, value, [options])

Set cookie name to value with options :

Задайте name файла cookie для value с options :

  • maxAge a number representing the milliseconds from Date.now() for expiry
  • maxAge число, представляющее миллисекунды из Date.now () для истечения срока действия
  • signed sign the cookie value
  • signed знак значения cookie
  • expires a Date for cookie expiration
  • expires Date истечения срока действия файла cookie
  • path cookie path, /' by default
  • path файлу cookie, /' по умолчанию
  • domain cookie domain
  • domain cookie
  • secure secure cookie
  • безопасный файл cookie
  • httpOnly server-accessible cookie, true by default
  • httpOnly доступный для сервера cookie, true по умолчанию
  • overwrite a boolean indicating whether to overwrite previously set cookies of the same name ( false by default).
  • overwrite логическое значение, указывающее, следует ли перезаписывать ранее установленные файлы cookie с тем же именем (по умолчанию - false ).
  • If this is true, all cookies set during the same request with the same name (regardless of path or domain) are filtered out of the Set-Cookie header when setting this cookie.
  • Если это так, все cookie, установленные во время одного и того же запроса с тем же именем (независимо от пути или домена), отфильтровываются из заголовка Set-Cookie при настройке этого файла cookie.

koa uses the cookies module where options are simply passed.

koa использует модуль cookie, где параметры просто передаются.

ctx.throw([status], [msg], [properties])

Helper method to throw an error with a .status property defaulting to 500 that will allow Koa to respond appropriately.

Помощник метод, чтобы выбросить ошибку с .status свойство по .status 500 что позволит Koa ответить соответствующим образом.

The following combinations are allowed:

Возможны следующие комбинации: 

 ctx.throw(400);
 ctx.throw(400, 'name required'); 
 ctx.throw(400, 'name required', { user: user });

For example ctx.throw(400, 'name required') is equivalent to:

Например, ctx.throw(400, 'name required') эквивалентно: 

 const err = new Error('name required');
 err.status = 400;
 err.expose = true;
 throw err;

Note that these are user-level errors and are flagged with err.expose meaning the messages are appropriate for client responses, which is typically not the case for error messages since you do not want to leak failure details.

Обратите внимание, что это ошибки на уровне пользователя и помечены как err.expose означает, что сообщения подходят для ответов клиентов, что обычно не относится к сообщениям об ошибках, так как вы не хотите утечки деталей сбоя.

You may optionally pass a properties object which is merged into the error as-is, useful for decorating machine-friendly errors which are reported to the requester upstream.

Вы можете опционально передать объект properties который объединен с ошибкой как есть, полезен для декорирования машинных ошибок, которые сообщаются реквестору вверх по течению. 

 ctx.throw(401, 'access_denied', { user: user });

koa uses http-errors to create errors.

koa использует http-ошибки для создания ошибок.

ctx.assert(value, [status], [msg], [properties])

Helper method to throw an error similar to .throw() when !value .

Вспомогательный метод для .throw() ошибки, аналогичной .throw() when !value .

Similar to node's assert() method.

Подобно методу assert () узла. 

 ctx.assert(ctx.state.user, 401, 'User not found. Please login!');


koa uses http-assert for assertions.

koa использует http-assert для утверждений.

ctx.respond

To bypass Koa's built-in response handling, you may explicitly set ctx.respond = false;

Чтобы обойти встроенную обработку ответа ctx.respond = false; , вы можете явно установить ctx.respond = false; . ,

Use this if you want to write to the raw res object instead of letting Koa handle the response for you.

Используйте это, если вы хотите записать объект raw res вместо того, чтобы позволить Koa обрабатывать ответ для вас.

Note that using this is not supported by Koa.

Обратите внимание, что использование этого не поддерживается Koa.

This may break intended functionality of Koa middleware and Koa itself.

Это может нарушить предполагаемую функциональность промежуточного программного обеспечения Koa и самого Koa.

Using this property is considered a hack and is only a convenience to those wishing to use traditional fn(req, res) functions and middleware within Koa.

Использование этого свойства считается взломом и является лишь удобством для тех, кто хочет использовать традиционные функции fn(req, res) и промежуточное ПО в Koa.

Request aliases

Запросить aliases

The following accessors and alias Request equivalents:

Следующие аксессоры и псевдоним Идентификаторы запроса :

  • ctx.header
  • ctx.headers
  • ctx.method
  • ctx.method=
  • ctx.url
  • ctx.url=
  • ctx.originalUrl
  • ctx.origin
  • ctx.href
  • ctx.path
  • ctx.path=
  • ctx.query
  • ctx.query=
  • ctx.querystring
  • ctx.querystring=
  • ctx.host
  • ctx.hostname
  • ctx.fresh
  • ctx.stale
  • ctx.socket
  • ctx.protocol
  • ctx.secure
  • ctx.ip
  • ctx.ips
  • ctx.subdomains
  • ctx.is()
  • ctx.accepts()
  • ctx.acceptsEncodings()
  • ctx.acceptsCharsets()
  • ctx.acceptsLanguages()
  • ctx.get()
Report content on this page

Report Page

Please submit your DMCA takedown request to dmca@telegram.org