docs: remove async-function (#1713)

eggjs · Nov 29, 2017 · d043148 · d043148
1 parent e3ef3ec
commit d043148
Show file tree

Hide file tree

Showing 8 changed files with 19 additions and 327 deletions.
diff --git a/docs/source/_data/guide_toc.yml b/docs/source/_data/guide_toc.yml
@@ -32,7 +32,6 @@ Core:
 Tutorials:
   MySQL: /tutorials/mysql.html
   RESTful API: /tutorials/restful.html
-  Async Function: /tutorials/async-function.html
   # Passport: /core/passport.html
 Advanced:
   Loader: /advanced/loader.html

diff --git a/docs/source/en/intro/egg-and-koa.md b/docs/source/en/intro/egg-and-koa.md
@@ -129,11 +129,11 @@ More about plugin, please check [Plugin](../basics/plugin.md) section.
 
 #### Egg 1.x
 
-When Egg 1.x released, the Node.js LTS version does not support async function，so Egg 1.x is based on Koa 1.x. On the basis of this, Egg has added full async function support. Egg is completely compatible with middlewares in Koa 2.x, all application layer are implemented based on [async function](../tutorials/async-function.md).
+When Egg 1.x released, the Node.js LTS version does not support async function，so Egg 1.x is based on Koa 1.x. On the basis of this, Egg has added full async function support. Egg is completely compatible with middlewares in Koa 2.x, all application could write with `async function`.
 
 - The underlying is based on Koa 1.x, asynchronous solution is based on generator function wrapped by [co].
 - Official plugin and core of Egg are written in generator function,  keep supporting Node.js LTS version, use [co] when necessary to be compatiable with async function.
-- Application developers can choose either async function (Node.js 7.6+) or generator function (Node.js 6.0+), **we recommend generator function way for ensuring you application can be runned on Node.js LTS version**.
+- Application developers can choose either async function (Node.js 8.x+) or generator function (Node.js 6.x+).
 
 #### Egg 2.x
 

diff --git a/docs/source/en/tutorials/async-function.md b/docs/source/en/tutorials/async-function.md
diff --git a/docs/source/en/tutorials/index.md b/docs/source/en/tutorials/index.md
@@ -3,7 +3,6 @@ title: Tutorials
 - [Quick Start](../intro/quickstart.md)
 - [Progressive Development](./progressive.md)
 - [RESTful API](./restful.md)
-- [Async Function](./async-function.md)
 
 ## Template Engines
 

diff --git a/docs/source/languages/zh-cn.yml b/docs/source/languages/zh-cn.yml
@@ -58,7 +58,6 @@ guide_toc:
   Plugin Development: 插件开发
   Framework: 框架开发
   Progressive: 渐进式开发
-  Async Function: Async Function
   Deployment: 应用部署
   # Loader:
   Community: 社区

diff --git a/docs/source/zh-cn/intro/egg-and-koa.md b/docs/source/zh-cn/intro/egg-and-koa.md
@@ -128,11 +128,11 @@ exports.handler = ctx => {
 
 #### Egg 1.x
 
-Egg 1.x 发布时，Node.js 的 LTS 版本尚不支持 async function，所以 Egg 1.x 仍然基于 Koa 1.x 开发，但是在此基础上，Egg 全面增加了 async function 的支持，再加上 Egg 对 Koa 2.x 的中间件也完全兼容，应用层代码可以完全基于 [async function 来实现](../tutorials/async-function.md)。
+Egg 1.x 发布时，Node.js 的 LTS 版本尚不支持 async function，所以 Egg 1.x 仍然基于 Koa 1.x 开发，但是在此基础上，Egg 全面增加了 async function 的支持，再加上 Egg 对 Koa 2.x 的中间件也完全兼容，应用层代码可以完全基于 `async function` 来开发。
 
 - 底层基于 Koa 1.x，异步解决方案基于 [co] 封装的 generator function。
 - 官方插件以及 Egg 核心使用 generator function 编写，保持对 Node.js LTS 版本的支持，在必要处通过 co 包装以兼容在 async function 中的使用。
-- 应用开发者可以选择 async function（Node.js 7.6+） 或者 generator function（Node.js 6.0+）进行编写，**我们推荐 generator function 方案以确保应用可以运行在 Node.js LTS 版本上**。
+- 应用开发者可以选择 async function（Node.js 8.x+） 或者 generator function（Node.js 6.x+）进行编写。
 
 #### Egg 2.x
 

diff --git a/docs/source/zh-cn/migration.md b/docs/source/zh-cn/migration.md
@@ -25,7 +25,8 @@ Egg 的理念之一是`渐进式增强`，故我们为开发者提供`渐进升
 ## 快速升级
 
 - Node.js 使用最新的 LTS 版本（`>=8.9.0`）。
-- 执行 `egg-bin autod`，会自动升级 `egg` 的依赖为 `^2.0.0`，以及其他插件版本。
+- 修改 `package.json` 中 `egg` 的依赖为 `^2.0.0`。
+- 检查相关插件是否发布新版本（可选）。
 - 重新安装依赖，跑单元测试。
 
 **搞定！不需要修改任何一行代码，就已经完成了升级。**
@@ -44,7 +45,9 @@ Egg 的理念之一是`渐进式增强`，故我们为开发者提供`渐进升
 
 > 2.x 仍然保持对 1.x 风格的中间件的兼容，故不修改也能继续使用。
 
-- 返回的函数入参改为 `(ctx, next)` 的形式。
+- 返回的函数入参改为 Koa 2 的 `(ctx, next)` 风格。
+  - 第一个参数为 `ctx`，代表当前请求的上下文，是 [Context](./basics/extend.md#Context) 的实例。
+  - 第二个参数为 `next`，用 await 执行它来执行后续中间件的逻辑。
 - 不建议使用 `async (ctx, next) => {}` 格式，避免错误堆栈丢失函数名。
 - `yield next` 改为函数调用 `await next()` 的方式。
 
@@ -63,7 +66,7 @@ module.exports = () => {
 module.exports = () => {
   return async function responseTime(ctx, next) {
     const start = Date.now();
-    // 注意：函数调用
+    // 注意，和 generator function 格式的中间件不同，此时 next 是一个方法，必须要调用它
     await next();
     const delta = Math.ceil(Date.now() - start);
     ctx.set('X-Response-Time', delta + 'ms');
@@ -84,7 +87,7 @@ module.exports = () => {
 - generators (delegation)
 - generator functions (delegation)
 
-而原生的 `yield` 和 `await` 只支持其中的一部分，故在移除 `co` 后，我们需要根据不同场景自行处理：
+尽管 `generator` 和 `async` 两者的编程模型基本一模一样，但由于上述的 `co` 的一些特殊处理，导致在移除 `co` 后，我们需要根据不同场景自行处理：
 
 #### promise
 
@@ -177,10 +180,11 @@ const { news, user } = await app.toPromise(ctx.service.biz.list(topic, uid));
 - [toAsyncFunction][app.toAsyncFunction] 和 [toPromise][app.toPromise] 实际使用的是 [co] 包装，因此会带回对应的性能损失和堆栈问题，建议开发者还是尽量全链路升级。
 - [toAsyncFunction][app.toAsyncFunction] 在调用 async function 时不会有损失。
 
+@sindresorhus 编写了许多[基于 promise 的 helper 方法](https://github.com/sindresorhus/promise-fun)，灵活的运用它们配合 async function 能让代码更加具有可读性。
 
 ## 插件升级
 
-`应用开发者`只需升级`插件开发者`修改后的依赖版本即可，可以用我们提供的命令 `egg-bin autod` 快速更新。
+`应用开发者`只需升级`插件开发者`修改后的依赖版本即可，也可以用我们提供的命令 `egg-bin autod` 快速更新。
 
 以下内容针对`插件开发者`，指导如何升级插件：
 
@@ -231,6 +235,12 @@ task = app.toAsyncFunction(schedule.task);
 - 修改 `README.md` 的示例为 async function。
 - 修改 `test/fixtures` 为 async function，可选，建议分开另一个 PR 方便 Review。
 
+一般还会需要继续维护上一个版本，故需要：
+  - 对上一个版本建立一个 `1.x` 这类的 branch 分支
+  - 修改上一个版本的 `package.json` 的 `publishConfig.tag` 为 `release-1.x`
+  - 这样如果上一个版本有 BugFix 时，npm 版本时就会发布为 `release-1.x` 这个 tag，用户通过 `npm i [email protected]` 来引入旧版本。
+  - 参见 [npm 文档](https://docs.npmjs.com/cli/dist-tag)。
+
 
 [co]: https://github.com/tj/co
 [egg-schedule]: https://github.com/eggjs/egg-schedule