docs: change controller showcase style to ctx (#568)

docs/source/en/basics/app-start.md

@@ -19,12 +19,12 @@ module.exports = app => {
 };
 ```
 
-`cities` attribute has attached on the global `this.app`. It can be accessed in the controller,
+`cities` attribute has attached on the global `app`. It can be accessed in the controller,
 
 ```js
 // app/controller/city.js
-module.exports = function*() {
-    // this.app.cities // access `cities` property on the global `this.app`
+module.exports = function* (ctx) {
+    // ctx.app.cities // access `cities` property on the global `ctx.app`
 }
 ```
 

docs/source/zh-cn/advanced/plugin.md

@@ -325,7 +325,7 @@ module.exports = {
 // app/controller/post.js
 module.exports = app => {
   return class PostController extends app.Controller {
-    *list () {
+    * list() {
       const posts = yield this.app.mysql.query(sql, values);
     },
   };
@@ -366,7 +366,7 @@ exports.mysql = {
 // app/controller/post.js
 module.exports = app => {
   return class PostController extends app.Controller {
-    *list () {
+    * list() {
       const posts = yield this.app.mysql.get('db1').query(sql, values);
     },
   };
@@ -395,7 +395,7 @@ module.exports = app => {
 // app/controller/post.js
 module.exports = app => {
   return class PostController extends app.Controller {
-    *list () {
+    * list() {
       const posts = yield this.app.databse.query(sql, values);
     },
   };

docs/source/zh-cn/basics/app-start.md

@@ -22,8 +22,8 @@ module.exports = app => {
 
 ```js
 // app/controller/city.js
-module.exports = function*() {
-  // this.app.cities 在上面启动期间已经加载，可以直接使用
+module.exports = function* (ctx) {
+  // ctx.app.cities 在上面启动期间已经加载，可以直接使用
 }
 ```
 

docs/source/zh-cn/basics/controller.md

@@ -66,7 +66,7 @@ module.exports = {
 
 - `this.ctx`: 当前请求的上下文 [Context](./extend.md#context) 对象的实例，通过它我们可以拿到框架封装好的处理当前请求的各种便捷属性和方法。
 - `this.app`: 当前应用 [Application](./extend.md#application) 对象的实例，通过它我们可以拿到框架提供的全局对象和方法。
-- `this.service`：应用定义的 [Service](./service.md)，通过它我们可以访问到抽象出的业务层。
+- `this.service`：应用定义的 [Service](./service.md)，通过它我们可以访问到抽象出的业务层，等价于 `this.ctx.service` 。
 - `this.config`：应用运行时的[配置项](./config.md)。
 
 #### 自定义 Controller 基类

docs/source/zh-cn/basics/extend.md

@@ -75,7 +75,8 @@ Context 指的是 Koa 的请求上下文，这是 **请求级别** 的对象，
 
 ### 访问方式
 
-- controller，middleware 中 `this` 就是 ctx，例如 `this.cookies.get('foo')`。
+- middleware 中 `this` 就是 ctx，例如 `this.cookies.get('foo')`。
+- controller 有两种写法，类的写法通过 `this.ctx`，方法的写法直接通过 `ctx` 入参。
 - helper，service 中的 this 指向 helper，service 对象本身，使用 `this.ctx` 访问 context 对象，例如 `this.ctx.cookies.get('foo')`。
 
 ### 扩展方式

docs/source/zh-cn/basics/service.md

@@ -33,9 +33,9 @@ title: Service
 - Service 文件必须放在 `app/service` 目录，可以支持多级目录，访问的时候可以通过目录名级联访问。
 
   ```js
-  app/service/biz/user.js => this.service.biz.user
-  app/service/sync_user.js => this.service.syncUser
-  app/service/HackerNews.js => this.service.hackerNews
+  app/service/biz/user.js => ctx.service.biz.user
+  app/service/sync_user.js => ctx.service.syncUser
+  app/service/HackerNews.js => ctx.service.hackerNews
   ```
 
 - 一个 Service 文件只能包含一个类， 这个类需要通过 `module.exports` 的方式返回。
@@ -62,10 +62,10 @@ module.exports = app => {
 };
 
 // app/controller/user.js
-exports.info = function* () {
-  const userId = this.params.id;
-  const userInfo = yield this.service.user.find(userId);
-  this.body = userInfo;
+exports.info = function* (ctx) {
+  const userId = ctx.params.id;
+  const userInfo = yield ctx.service.user.find(userId);
+  ctx.body = userInfo;
 };
 
 // app/service/user.js

docs/source/zh-cn/core/error-handling.md

@@ -21,27 +21,30 @@ try {
 
 ```js
 // app/controller/jump.js
-const request = {};
-const config = yield this.service.trade.buy(request);
-// 下单后需要进行一次核对，且不阻塞当前请求
-setImmediate(() => {
-  this.service.trade.check(request)
-  .catch(err => this.logger.error(err));
-});
+exports.buy = function* (ctx) {
+  const request = {};
+  const config = yield ctx.service.trade.buy(request);
+  // 下单后需要进行一次核对，且不阻塞当前请求
+  setImmediate(() => {
+    ctx.service.trade.check(request).catch(err => ctx.logger.error(err));
+  });
+}
 ```
 
 在这个场景中，如果 `service.trade.check` 方法中代码有问题，导致执行时抛出了异常，尽管框架会在最外层通过 `try catch` 统一捕获错误，但是由于 `setImmediate` 中的代码『跳出』了异步链，它里面的错误就无法被捕捉到了。因此在编写类似代码的时候一定要注意。
 
 当然，框架也考虑到了这类场景，提供了 `ctx.runInBackground(scope)` 辅助方法，通过它又包装了一个异步链，所有在这个 scope 里面的错误都会统一捕获。
 
 ```js
-const request = {};
-const config = yield this.service.trade.buy(request);
-// 下单后需要进行一次核对，且不阻塞当前请求
-this.runInBackground(function* () {
-  // 这里面的异常都会统统被 Backgroud 捕获掉，并打印错误日志
-  yield this.service.trade.check(request);
-});
+exports.buy = function* (ctx) {
+  const request = {};
+  const config = yield ctx.service.trade.buy(request);
+  // 下单后需要进行一次核对，且不阻塞当前请求
+  ctx.runInBackground(function* () {
+    // 这里面的异常都会统统被 Backgroud 捕获掉，并打印错误日志
+    yield ctx.service.trade.check(request);
+  });
+}
 ```
 
 **为了保证异常可追踪，必须保证所有抛出的异常都是 Error 类型，因为只有 Error 类型才会带上堆栈信息，定位到问题。**

docs/source/zh-cn/core/security.md

@@ -116,15 +116,15 @@ console.log(`var foo = "${this.helper.sjs(foo)}";`);
 ```
 
 还有一种情况，有时候我们需要在 JavaScript 中输出 json ，若未做转义，易被利用为 XSS 漏洞。框架提供了 `helper.sjson()` 宏做 json encode，会遍历 json 中的 key ，将 value 的值中，所有非白名单字符转义为 `\x` 形式，防止 XSS 攻击。同时保持 json 结构不变。
-若存在模板中输出一个 JSON 字符串给 JavaScript 使用的场景，请使用 `${this.helper.sjson(变量名)}` 进行转义。
+若存在模板中输出一个 JSON 字符串给 JavaScript 使用的场景，请使用 `{{ helper.sjson(变量名) }}` 进行转义。
 
 **处理过程较复杂，性能损耗较大，请仅在必要时使用。**
 
 实例:
 
 ```html
   <script>
-    window.locals = ${this.helper.sjson(locals)};
+    window.locals = {{ helper.sjson(locals) }};
   </script>
 ```
 
@@ -154,7 +154,7 @@ const value = `<a href="http://www.domain.com">google</a><script>evilcode…</sc
 // 模板
 <html>
 <body>
-  ${helper.shtml($value)}
+  {{ helper.shtml(value) }}
 </body>
 </html>
 // => <a href="http://www.domain.com">google</a>&lt;script&gt;evilcode…&lt;/script&gt;
@@ -181,7 +181,7 @@ options:
 const html = '<html></html>';
 
 // html
-${helper.shtml($html)}
+{{ helper.shtml(html) }}
 
 // 输出空
 ```

docs/source/zh-cn/tutorials/mysql.md

@@ -161,9 +161,9 @@ module.exports = app => {
 
 ```js
 // app/controller/user.js
-exports.info = function* () {
+exports.info = function* (ctx) {
   const userId = this.params.id;
-  const user = yield this.service.user.find(userId);
+  const user = yield ctx.service.user.find(userId);
   this.body = user;
 };
 ```

docs/source/zh-cn/tutorials/restful.md

@@ -148,17 +148,17 @@ const createRule = {
   tab: { type: 'enum', values: [ 'ask', 'share', 'job' ], required: false },
   content: 'string',
 };
-exports.create = function* () {
-  // 校验 `this.request.body` 是否符合我们预期的格式
+exports.create = function* (ctx) {
+  // 校验 `ctx.request.body` 是否符合我们预期的格式
   // 如果参数校验未通过，将会抛出一个 status = 422 的异常
-  this.validate(createRule);
+  ctx.validate(createRule);
   // 调用 service 创建一个 topic
-  const id = yield this.service.topic.create(this.request.body);
+  const id = yield ctx.service.topic.create(ctx.request.body);
   // 设置响应体和状态码
   this.body = {
     topic_id: id,
   };
-  this.status = 201;
+  ctx.status = 201;
 };
 ```