update for 2.12.0

Readme.md

@@ -6,6 +6,7 @@
   [![Test coverage][coveralls-image]][coveralls-url]
   [![OpenCollective Backers][backers-image]](#backers)
   [![OpenCollective Sponsors][sponsors-image]](#sponsors)
+  [![PR's Welcome][pr-welcoming-image]][pr-welcoming-url]
 
 > 此项目同步自 [koajs](https://github.com/koajs) / [koa](https://github.com/koajs/koa) 项目中的  docs. 除特殊情况, 将保持每月一次的同步频率.
 
@@ -155,24 +156,30 @@ app.use(async (ctx, next) => {
 
 ## Babel 配置
 
-如果你正在使用的不是 `node v7.6+`, 我们推荐你用 [`babel-preset-env`](https://github.com/babel/babel-preset-env) 配置 `babel` :
+如果你正在使用的不是 `node v7.6+`, 我们推荐你用 [`@babel/preset-env`](https://babeljs.io/docs/en/next/babel-preset-env) 配置 `babel` :
 
 ```bash
-$ npm install babel-register babel-preset-env --save
+$ npm install @babel/register @babel/preset-env @babel/cli --save-dev
 ```
 
-在你入口文件配置 `babel-register`:
+在开发环境中, 你可能想要使用 [`@babel/register`](https://babeljs.io/docs/en/next/babel-register):
 
-```js
-require('babel-register');
+```bash
+node --require @babel/register <your-entry-file>
+```
+
+在生产环境中, 你可能想要使用 [`@babel/cli`](https://babeljs.io/docs/en/babel-cli) 构建文件. 假设你正在编译 `src` 文件夹且想要输出 non-javascript 文件拷贝到新的 `dist` 文件夹中:
+
+```bash
+babel src --out-dir dist --copy-files
 ```
 
 还有你的 `.babelrc` 配置:
 
 ```json
 {
   "presets": [
-    ["env", {
+    ["@babel/preset-env", {
       "targets": {
         "node": true
       }
@@ -205,3 +212,5 @@ $ npm test
 [gitter-image]: https://img.shields.io/gitter/room/koajs/koa.svg?style=flat-square
 [gitter-url]: https://gitter.im/koajs/koa?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
 [#koajs]: https://webchat.freenode.net/?channels=#koajs
+[pr-welcoming-image]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
+[pr-welcoming-url]: https://github.com/koajs/koa/pull/new

api/context.md

@@ -70,15 +70,16 @@ koa 使用 [cookies](https://github.com/pillarjs/cookies) 模块，其中只需
 ### ctx.cookies.set(name, value, [options])
 
   通过 `options` 设置 cookie `name` 的 `value` :
-
- - `maxAge` 一个数字表示从 Date.now() 得到的毫秒数
- - `signed` cookie 签名值
- - `expires` cookie 过期的 `Date`
- - `path` cookie 路径, 默认是`'/'`
- - `domain` cookie 域名
- - `secure` 安全 cookie
- - `httpOnly` 服务器可访问 cookie,  默认是 __true__
- - `overwrite` 一个布尔值，表示是否覆盖以前设置的同名的 cookie (默认是 __false__). 如果是 true, 在同一个请求中设置相同名称的所有 Cookie（不管路径或域）是否在设置此Cookie 时从 Set-Cookie 消息头中过滤掉。
+
+ * `maxAge`: 一个数字, 表示从 `Date.now()` 得到的毫秒数.
+* `expires`: 一个 `Date` 对象, 表示 cookie 的到期日期 (默认情况下在会话结束时过期).
+* `path`: 一个字符串, 表示 cookie 的路径 (默认是`/`).
+* `domain`: 一个字符串, 指示 cookie 的域 (无默认值).
+* `secure`: 一个布尔值, 表示 cookie 是否仅通过 HTTPS 发送 (HTTP 下默认为 `false`, HTTPS 下默认为 `true`). [阅读有关此参数的更多信息](https://github.com/pillarjs/cookies#secure-cookies).
+* `httpOnly`: 一个布尔值, 表示 cookie 是否仅通过 HTTP(S) 发送，, 且不提供给客户端 JavaScript (默认为 `true`).
+* `sameSite`: 一个布尔值或字符串,  表示该 cookie 是否为 "相同站点" cookie (默认为 `false`). 可以设置为 `'strict'`, `'lax'`, `'none'`, 或 `true` (映射为 `'strict'`).
+* `signed`: 一个布尔值, 表示是否要对 cookie 进行签名 (默认为 `false`). 如果为 `true`, 则还会发送另一个后缀为 `.sig` 的同名 cookie, 使用一个 27-byte url-safe base64 SHA1 值来表示针对第一个 [Keygrip](https://www.npmjs.com/package/keygrip) 键的 _cookie-name_=_cookie-value_ 的哈希值. 此签名密钥用于检测下次接收 cookie 时的篡改.
+* `overwrite`: 一个布尔值, 表示是否覆盖以前设置的同名的 cookie (默认是 `false`). 如果是 true, 在同一个请求中设置相同名称的所有 Cookie（无论路径或域）是否在设置此Cookie 时从 Set-Cookie 消息头中过滤掉.
 
 koa 使用传递简单参数的 [cookies](https://github.com/pillarjs/cookies) 模块。
 

api/index.md

@@ -156,7 +156,23 @@ https.createServer(app.callback()).listen(3001);
 
 ## app.use(function)
 
-将给定的中间件方法添加到此应用程序。参阅 [Middleware](https://github.com/koajs/koa/wiki#middleware) 获取更多信息.
+将给定的中间件方法添加到此应用程序。`app.use()` 返回 `this`, 因此可以链式表达.
+
+```js
+app.use(someMiddleware)
+app.use(someOtherMiddleware)
+app.listen(3000)
+```
+
+它等同于
+
+```js
+app.use(someMiddleware)
+  .use(someOtherMiddleware)
+  .listen(3000)
+```
+
+参阅 [Middleware](https://github.com/koajs/koa/wiki#middleware) 获取更多信息.
 
 ## app.keys=
 

api/response.md

@@ -85,6 +85,15 @@ Koa `Response` 对象是在 node 的原生响应对象之上的抽象，提供
 
 __注意__: 不用太在意记住这些字符串, 如果你写错了,可以查阅这个列表随时更正.
 
+由于 `response.status` 默认设置为 `404`，因此发送没有 body 且状态不同的响应的操作如下：
+
+```js
+ctx.response.status = 200;
+
+// 或其他任何状态
+ctx.response.status = 204;
+```
+
 ### response.message
 
 获取响应的状态消息. 默认情况下, `response.message` 与 `response.status` 关联.
@@ -149,7 +158,7 @@ Content-Type 默认为 `application/octet-stream`。
 const PassThrough = require('stream').PassThrough;
 
 app.use(async ctx => {
-  ctx.body = someHTTPStream.on('error', ctx.onerror).pipe(PassThrough());
+  ctx.body = someHTTPStream.on('error', (err) => ctx.onerror(err)).pipe(PassThrough());
 });
 ```