Koa v2.x 中文文檔

此係列文章的應用示例已發佈於 GitHub: koa-docs-Zh-CN. 能夠 Fork 幫助改進或 Star 關注更新. 歡迎 Star.

此項目同步自 koajs / koa 項目中的 docs. 除特殊狀況, 將保持每個月一次的同步頻率.

用 node.js 來實現 HTTP 的中間件框架，讓 Web 應用程序和 API 能夠更加愉快地編寫。Koa 的中間件堆棧以相似堆棧的方式流動，容許您執行下游操做，而後過濾並操縱上游的響應。

幾乎全部 HTTP 服務器通用的方法都被直接集成到 Koa 大約570行源碼的代碼庫中。其中包括好比內容協商，規範節點不一致性，重定向等其它操做。

Koa沒有捆綁任何中間件。

安裝

Koa 依賴 node v7.6.0 或 ES2015及更高版本和 async 方法支持.

$ npm install koa

Hello koa

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

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

app.listen(3000);

入門

• Kick-Off-Koa - 經過一系列自身指引的講解介紹了 Koa。
• Workshop - 經過學習 Koa 的講解，快速領會精髓。
• Introduction Screencast - 關於 Koa 安裝入門的介紹。

中間件

Koa 是一箇中間件框架，能夠將兩種不一樣的功能做爲中間件：

• async function
• common function

如下是每一個不一樣功能記錄器的中間件示例：

async functions (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`);
});

Common function

// 中間件一般帶有兩個參數 (ctx, next), ctx 是一個請求的上下文,
// next 是調用執行下游中間件的函數. 在代碼執行完成後經過 then 方法返回一個 Promise.

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 中刪除

請參閱 遷移指南 獲取有關從 v1.x 升級並使用 v2.x 中間件的更多信息。

上下文, 請求和響應

每一箇中間件都接收一個 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);
  // 至關於:
  // if (!ctx.request.accepts('xml')) ctx.throw(406);
  await next();
});

Koa提供了一個 Response 對象做爲 Context 的 response 屬性。
Koa的 Response 對象提供了用於處理 http 響應的方法，該響應委託給 ServerResponse。

Koa 對 Node 的請求和響應對象進行委託而不是擴展它們。這種模式提供了更清晰的接口，並減小了不一樣中間件與 Node 自己之間的衝突，併爲流處理提供了更好的支持。
IncomingMessage 仍然能夠直接被訪問，由於 Context 和 ServerResponse 上的 req 屬性能夠直接做爲 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.request.type，而 ctx.accepts 能夠用來代替 ctx.request.accepts。

關於 Request, Response 和 Context 更多詳細信息, 參閱 請求 API 參考,
響應 API 參考 和 上下文 API 參考.

Koa 應用程序

在執行 new Koa() 時建立的對象被稱爲 Koa 應用程序對象。

應用對象是 Koa 與 node 的 http 服務器和處理中間件註冊的接口，從 http 發送到中間件，默認錯誤處理，以及上下文，請求和響應對象的配置。

瞭解有關應用程序對象的更多信息請到 應用 API 參考.

文檔

• 使用指南
• 錯誤處理
• Koa 與 Express
• 常見問題
• 從 Koa v1.x 遷移到 v2.x

• API 文檔

  • 上下文(Context)
  • 請求(Request)
  • 響應(Response)
• Koa 中間件列表

Babel 配置

若是你正在使用的不是 node v7.6+, 咱們推薦你用 babel-preset-env 配置 babel :

$ npm install babel-register babel-preset-env --save

在你入口文件配置 babel-register:

require('babel-register');

還有你的 .babelrc 配置:

{
  "presets": [
    ["env", {
      "targets": {
        "node": true
      }
    }]
  ]
}

運行測試

$ npm test

若是這篇文章對您有幫助, 感謝 下方點贊 或 Star GitHub: koa-docs-Zh-CN 支持, 謝謝.