From 35149af490abb9ee0c0a6cc720755131f0ee0f1e Mon Sep 17 00:00:00 2001
From: yutent <yutent.io@gmail.com>
Date: Thu, 2 Nov 2023 12:08:09 +0800
Subject: [PATCH] Update Controller

---
 Controller.md | 115 ++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 83 insertions(+), 32 deletions(-)

diff --git a/Controller.md b/Controller.md
index 22918fd..b6fec2b 100644
--- a/Controller.md
+++ b/Controller.md
@@ -1,17 +1,18 @@
-
 ## 控制器基类
 
-> 框架内置有一个控制器基类。所有的业务应用入口文件, 都必须继承这个基类, 以获取跟框架实例通讯的能力。
+> 框架内置有一个控制器基类, 提供了session/jwt/view的进一步封装, 简化调用。
+>> 2.0版之后, 这个基类为 `非必须` 的。
 
-如脚手架默认的index.js里, 
+
+使用示例:
 
 ```js
 import Controller from '@gm5/controller'
 
 
-// 所有的应用, 都要继承Controller
+// 1.x版时 所有的应用, 都要继承Controller
 // 以获取跟框架交互的能力
-export default class Index extends Controller  {
+export default class extends Controller  {
   
   // 这个main方法是可选的, 如果有定义, 会自动先被调用
   // 可以在这里做任何需要预处理的事, 支持async/await
@@ -21,70 +22,120 @@ export default class Index extends Controller  {
 
   async indexAction() {
     this.response.end('Hello world!')
+    
+    // 2.0版之后调整为body属性
+    this.response.body = 'Hello world!'
   }
 
   async otherAction() {
-    this.response.end('Hello other!')
+    // todo...
   }
 }
 ```
 
+---
 
-继承基类, 除了能获得跟框架通讯的能力之外, 还有一些常用的额外的方法。
+### 属性
 
-+ `this.name` 当前文件(路由)的名字。
+#### `.name`
+> 当前控制器(一级路由)的名字。
+
+#### `.context`
+> 上下文对象, 即为 createApp()的app对象。
 
-+ `this.context` 上下文对象, 即为 框架实例化后的对象。
- > 这里可以调用 .get(key) 方法, 获取事先配置好的内容。
 
 ```js
-var regexp = this.context.get('regexp') // 读取内置的常用的正则
+let regexp = this.context.get('regexp') // 读取内置的常用的正则
 
 console.log(this.context.$$xxx) // 假设之前安装了一个叫 xxx 的拓展包
 ```
 
-#### `this.request` 本次请求体对象。
-> 客户端请求里的所有的信息, 都能从这个对象中读取, 具体请查看[Request](https://github.com/bytedo/gmf.core/wiki/Request)。
+#### `.request`
+> 框架的Request对象实例。
+>> 客户端请求里的所有的信息, 都能从这个对象中读取, 具体请查看[Request](/gm5/core/wiki/Request)。
 
-#### `this.response` 本次响应体对象。
-> 所有将要发送给客户端的操作, 都是通过该对象实现, 具体请查看[Response](https://github.com/bytedo/gmf.core/wiki/Response)。
+#### `.response`
+> 框架的Response对象实例。
+>> 所有将要发送给客户端的操作, 都是通过该对象实现, 具体请查看[Response](/gm5/core/wiki/Response)。
 
 
-#### `this.assign(key<String>, val<Any>)` 模板引擎的变量注册方法.
-> 功能同php smarty的assign()。注册后的变量, 可以在模板中使用。
+#### `.method`
+> 当前请求的类型, 如 GET/POST/PUT等。
 
-#### `this.render(filePath<String>, noParse<Boolean>)`  模板渲染方法, 需要在配置中开启模板引擎开关。
-> 传入要渲染的模板的相对路径(相对于初始化时配置的模板目录);  第2个方法是"是否不解析模板", 默认为false。 对于需要渲染模板, 但又不需要填充数据的页面, 可以传入true, 提高性能。
+v2.0版新增
+
+#### `.host`
+> 当前请求所使用的域名(含端口号,如不是80和443时)。
+
+v2.0版新增
+
+#### `.hostname`
+> 当前请求所使用的域名(不含端口号)。
+
+v2.0版新增
+
+#### `.ua`
+> 当前请求的客户端的user-agent.
+
+v2.0版新增
 
 
-#### `this.jwt(data<Object>)`  json web token的操作,  需要在配置中开启jwt。
+#### `.jwt`
+> 该属性仅在安装并使用`@gm5/jwt`模块时可用。该属性为一个对象 `{result: <Any>, sign: <Function>, verify: <Function>}`
+
+v2.0版新增
+
+---
+
+
+### 方法
+
+#### `.assign(key<String>, val<Any>)`
+> 模板引擎的变量注册方法.
+>> 功能同php smarty的assign()。注册后的变量, 可以在模板中使用。
+
+仅在安装`@gm5/views`模块时可用。
+
+
+#### `.render(filePath<String>, noParse<Boolean>)`
+> 模板渲染方法, 需要在配置中开启模板引擎开关。
+>> 传入要渲染的模板的相对路径(相对于初始化时配置的模板目录);  第2个方法是"是否不解析模板", 默认为false。 对于需要渲染模板, 但又不需要填充数据的页面, 可以传入true, 提高性能。
+
+仅在安装`@gm5/views`模块时可用。
+
+
+#### `.jwt(data<Object>)` 
+> json web token的操作,  需要在配置中开启jwt。
 > 如果有传参, 则是对参数进行签名, 返回签名后的token, 这个token可直接传给客户端。
 
 > 如果不传参, 则是校验客户端发送上来的token, 如果校验成功, 则可以得到之前签名的数据, 如果返回false, 则表示校验失败。如果返回undefined, 则为没有要校验的token。
 > 校验的操作, 建议放在 `__main__()` 方法中执行, 避免多次调用导致重复校验, 浪费性能。
 
+仅在安装`@gm5/jwt`模块时可用。
+
+v2.0版时, 废弃, 改为`.jwt`属性。
 
 
-#### `this.cookie(key<String>, val<String>, opt<Object>)` cookie的读写操作。
-> 只传key为读取, 传val为写入, opt字段, 提供一些额外的配置, 如有效期, 域等。 跟jq的cookie()方法使用一致。这里不再重复说明。
+
+#### `.cookie(key<String>, val<String>, opt<Object>)`
+> cookie的读写操作。
+>> 只传key为读取, 传val为写入, opt字段, 提供一些额外的配置, 如有效期, 域等。 跟jq的cookie()方法使用一致。这里不再重复说明。
 
 
-#### `this.session(key<String>, val<String>)` session的读写操作, 需要在配置中开启session。
-> 只传key为读取, 传val为写入。 
+#### `.session(key<String>, val<String>)`
+> session的读写操作。
+>> 只传key为读取, 传val为写入。 
 
 > 要注意的是, 读取返回的是一个Promise对象。写入不返回值。
 
+仅在安装`@gm5/session`模块时可用。
 
-#### `this.xdebug(err<String>)` cookie的读写操作。
+
+#### `.xdebug(err<String>)`
+> 输出调试信息。
 > 往响应头中写入x-debug字段, 输出一些debug的信息, 支持多次调用, 会追加输出。
 
+v2.0版中已废弃。
 
 
 
----- 
-
-上一节: [⟪跨域配置⟫](https://github.com/bytedo/gmf.core/wiki/Cors)
-
-下一节: [⟪Request⟫](https://github.com/bytedo/gmf.core/wiki/Request)
-
-