@fxjs/webx


fibjs webx 应用程序 api/视图和扩展资源框架

Install

``sh
npm install @fxjs/webx [--save]
`

Test

`sh
npm test
`

建立基础脚本

`JavaScript
const http = require('http');
const util = require('util')
const Session = require('@fxjs/session')
const App = require('../');

var app = new App('sqlite:test.db', {
uuid: true
});
app.db.use(require('./defs/person'));

var session = new Session(new util.LruCache(20000), {
timeout: 60 * 1000
});

var svr = new http.Server(8080, [
session.cookie_filter,
{
'/1.0': app
}
]);
svr.run();
`
其中 person 是 Model 定义模块，内容如下：
`JavaScript
module.exports = db => {
db.define('person', {
name: String,
sex: ["male", "female"],
age: Number
});
};
`
这是一个标准的 orm 定义，同样可以使用 orm 的其它功能，比如类型检查，事件等。

API 数据格式

对于 POST 和 PUT 请求，请求的主体必须是 JSON 格式，而且 HTTP header 的 Content-Type 需要设置为 application/json。

`sh
curl -X PUT \
-H "Content-Type: application/json" \
-d '{"name": "tom","sex":"male","age":23}' \
http://localhost/1.0/person/57fbbdb0a2400000
`
对于所有的请求，响应格式都是一个 JSON 对象。

一个请求是否成功是由 HTTP 状态码标明的。一个 2XX 的状态码表示成功，而一个 4XX 表示请求失败。当一个请求失败时响应的主体仍然是一个 JSON 对象，但是总是会包含 code 和 message 这两个字段，你可以用它们来进行调试。举个例子，如果一个请求权限认证失败，会返回以下信息：
`JavaScript
{
"code": 4030501,
"message": "The operation isn’t allowed for clients due to class-level permissions."
}
`
code 编码分为三个部分，前三位 403 表示错误类型，05 表示数据表编号，01 表示详细错误编码。

对于 GET 请求，通常会返回对象数据，根据 GET 请求的地址不同，可能会返回一个对象，也可能会返回一个数组。比如：
`JavaScript
{
"name": "tom",
"sex": "male",
"age": 23
}
`
或者：
`JavaScript
[
{
"name": "tom",
"sex": "male",
"age": 23
},
{
"name": "lily",
"sex": "female",
"age": 22
}
]
`


特殊字段


对象数据中，有四个特殊含义的字段，是不允许通过 API 更改的。分别是 id, updatedAt, createdAt, createdBy.

其中 id, updatedAt, createdAt 单个字段会自动创建和修改。createdBy 则需要自行指定类型。

基础对象访问 API

完成这样的数据定义，便直接拥有了一整套符合 REST api 规范的接口调用：

| url | method | action |
|---------------------|--------|------------|
| /1.0/:className | POST | 创建新对象 |
| /1.0/:className/:id | GET | 读取对象 |
| /1.0/:className/:id | PUT | 修改对象 |
| /1.0/:className/:id | DELETE | 删除对象 |
| /1.0/:className | GET | 查询对象列表 |

$3

为了创建一个新的对象，应该向 class 的 URL 发送一个 POST 请求，其中应该包含对象本身。例如，要创建如上所说的对象：
`sh
curl -X POST \
-H "Content-Type: application/json" \
-d '{"name": "tom","sex":"male","age":23}' \
http://localhost/1.0/person
`
当创建成功时，HTTP 的返回是 201 Created，响应的主体是一个 JSON 对象，包含新的对象的 objectId 和 createdAt 时间戳：
`JavaScript
{
"createdAt": "2017-11-25T01:39:35.931Z",
"id": "57fbbdb0a2400000"
}
`

$3

当你创建了一个对象时，你可以通过发送一个 GET 请求到返回的 header 的 Location 以获取它的内容。例如，为了得到我们上面创建的对象：
`sh
curl -X GET http://localhost/1.0/person/57fbbdb0a2400000
`
返回的主体是一个 JSON 对象包含所有用户提供的 field 加上 createdAt、updatedAt 和 id 字段：
`JavaScript
{
"name": "tom",
"sex": "male",
"age": 23,
"createdAt": "2017-11-25T01:39:35.931Z",
"updatedAt": "2017-11-25T01:39:35.931Z",
"id": "57fbbdb0a2400000"
}
`
通过设置返回字段 keys，可以定制返回的内容，keys 的内容是一个以 , 分割的字段名称字符串，：
`sh
curl -X GET http://localhost/1.0/person/57fbbdb0a2400000?keys=name%2Csex
`
将返回：
`JavaScript
{
"name": "tom",
"sex": "male"
}
`

$3

为了更改一个对象已经有的数据，你可以发送一个 PUT 请求到对象相应的 URL 上，任何你未指定的 key 都不会更改，所以你可以只更新对象数据的一个子集。例如，我们来更改我们对象的一个 age 字段：
`sh
curl -X PUT \
-H "Content-Type: application/json" \
-d '{"age": 25}' \
http://localhost/1.0/person/57fbbdb0a2400000
`
返回的 JSON 对象会包含 updatedAt 和 id 字段，表明更新发生的时间：
`JavaScript
{
"updatedAt": "2017-11-25T01:39:35.931Z",
"id": "57fbbdb0a2400000"
}
`

$3

为了删除一个对象，可以发送一个 DELETE 请求到指定的对象的 URL，比如：
`sh
curl -X DELETE http://localhost/1.0/person/57fbbdb0a2400000
`

$3

通过发送一个 GET 请求到类的 URL 上，不需要任何 URL 参数，你就可以一次获取多个对象。下面就是简单地获取所有用户：
`sh
curl -X GET http://localhost/1.0/person
`
返回的值就是一个 JSON 对象包含了 results 字段，它的值就是对象的列表：
`JavaScript
[
{
"name": "tom",
"sex": "male",
"age": 23,
"createdAt": "2017-11-25T01:39:35.931Z",
"updatedAt": "2017-11-25T01:39:35.931Z",
"id": "57fbbdb0a2400000"
},
{
"name": "lily",
"sex": "female",
"age": 22,
"createdAt": "2017-11-25T01:39:35.931Z",
"updatedAt": "2017-11-25T01:39:35.931Z",
"id": "57fbbdb0a2400001"
}
]
`
#### keys 字段定制
与对象查询一样，查询列表时可以通过设定 keys 来定制返回结果所包含的字段。keys 的内容是一个以 , 分割的字段名称字符串，例如：
`sh
curl -X GET http://localhost/1.0/person?keys=name%2Cage
`
将指定只返回 name 和 age 两个字段。

#### where 过滤条件
通过 where 参数的形式可以对查询对象做出约束。

where 参数的值应该是 JSON 编码过的。就是说，如果你查看真正被发出的 URL 请求，它应该是先被 JSON 编码过，然后又被 URL 编码过。最简单的使用 where 参数的方式就是包含应有的 key 和 value。例如，如果我们想要搜索名字为 tom 的用户，我们应该这样构造查询:
`sh
curl -X GET http://localhost/1.0/person?where=%7B%22name%22%3A%22tom%22%7D
`
where 的值为一个 urlencode 后的 JSON 字符串，内容为：{"name":"tom"}

除了完全匹配一个给定的值以外，where 也支持比较的方式，比如包含。where 参数支持如下选项：

| key | operation | sample |
|--------------|-----------|-----------------------|
| eq | 等于 | {"name":{"eq":"tom"}} 或者 {"name":"tom"} |
| ne | 不等于 | {"name":{"ne":"tom"}} |
| gt | 大于 | {"age":{"gt":"24"}} |
| gte | 大于等于 | {"age":{"gte":"24"}} |
| lt | 小于 | {"age":{"lt":"24"}} |
| lte | 小于等于 | {"age":{"lte":"24"}} |
| like | 模糊查询 | {"name":{"like":"%m"}} |
| not\_like | 模糊查询 | {"name":{"not_like":"%m"}} |
| between | 区间比较 | {"age":{"between":[22,25]}} |
| not\_between | 区间比较 | {"age":{"not_between":[22,25]}} |
| in | 枚举 | {"name":{"in":["tom","lily"]}} |
| not\_in | 枚举 | {"name":{"not_in":["tom","lily"]}} |
| or | 或运算 | {"or":[{"name":"tom"},{"age":24}]} |

#### skip 跳过记录
通过 skip 选项，可以跳过指定的记录数，达到翻页的效果。
`sh
curl -X GET http://localhost/1.0/person?skip=100
`
#### limit 返回记录限制
通过 limit 选项，可以限制返回记录数，limit 的有效数字为 1-1000，缺省为 100。
`sh
curl -X GET http://localhost/1.0/person?limit=100
`
#### order 指定排序方式
通过 order 选项，设定返回结果集的排序方式，字段名前包含 - 时为倒序。
`sh
curl -X GET http://localhost/1.0/person?order=-id
`
#### count 返回结果总数
在请求时增加 count 可以在返回指定内容的同时返回结果集的总数。
`sh
curl -X GET http://localhost/1.0/person?count=1&limit=1
`
此时返回结果将包含 count 和 results 两个字段，分别包含总数和结果：
`JavaScript
{
"count": 2,
"results": [
{
"name": "tom",
"sex": "male",
"age": 23,
"createdAt": "2017-11-25T01:39:35.931Z",
"updatedAt": "2017-11-25T01:39:35.931Z",
"id": "57fbbdb0a2400000"
}
]
}
`


建立扩展对象

通过 orm 定义 hasOne 和 hasMany，可以定义对象之间的关联关系，并在 API 上体现出来，例如：

`JavaScript
module.exports = db => {
var Person = db.models.person;

var Pet = db.define('pet', {
name: String
});

Person.hasMany('pets', Pet);
};
`


扩展对象访问 API

下面是扩展对象的 API 定义：

| url | method | action |
|--------------------------------------|--------|---------------|
| /1.0/:className/:id/:extendName | PUT | 设置扩展对象 |
| /1.0/:className/:id/:extendName | POST | 创建扩展对象 |
| /1.0/:className/:id/:extendName/:rid | GET | 读取扩展对象 |
| /1.0/:className/:id/:extendName/:rid | PUT | 修改扩展对象 |
| /1.0/:className/:id/:extendName/:rid | DELETE | 删除扩展对象 |
| /1.0/:className/:id/:extendName | GET | 查询扩展对象列表 |

$3

设置扩展对象是将两个独立的对象建立联系。比如 tom 领养了一只叫 cat 的宠物，可以用下面的操作实现：
`sh
curl -X PUT \
-H "Content-Type: application/json" \
-d '{"id": "57fbbdb0a2400007"}' \
http://localhost/1.0/person/57fbbdb0a2400000/pets
`
在调用里需要在 body 内指定 cat 的 id。

$3

直接创建扩展对象，可以在创建对象的同时，建立对象之间的联系。比如：
`sh
curl -X POST \
-H "Content-Type: application/json" \
-d '{"name": "cat"}' \
http://localhost/1.0/person/57fbbdb0a2400000/pets
`
将创建一只名叫 cat 的宠物，并建立与 tom 的关联关系。

$3

读取扩展对象与读取基础对象很相似，也同样支持 keys 选项：
`sh
curl -X GET http://localhost/1.0/person/57fbbdb0a2400000/pets/57fbbdb0a2400007
`

$3

读取扩展对象与读取基础对象很相似：
`sh
curl -X PUT \
-H "Content-Type: application/json" \
-d '{"name": "cat 1"}' \
http://localhost/1.0/person/57fbbdb0a2400000/pets/57fbbdb0a2400007
`

$3

删除扩展对象不会删除对象本身，只会解除对象之间的关系：
`sh
curl -X DETELE http://localhost/1.0/person/57fbbdb0a2400000/pets/57fbbdb0a2400007
`

注意 在设定了 reverse 名的 hasOne 关系中, revesed 的一方无法对发起方做删除操作, @fxjs/orm 底层认为该操作不合理. 尽管 @fxjs/webx 的 ACL/OACL 机制在此场景下可以正确计算出用户预期的 ACL 值, 但限于 @fxjs/orm 的支持不足, 我们无法进行这样的操作.

$3


查询扩展对象列表与查询基础对象列表很相似，也同样支持 keys 以及条件过滤等选项：
`sh
curl -X GET http://localhost/1.0/person/57fbbdb0a2400000/pets
`

ACL

可以通过定义 Model 的 ACL 控制数据权限。比如:
`JavaScript
const orm = require('@fxjs/orm');

module.exports = db => {
db.define('blog', {
title: String,
detail: String，
note: String
}, {
ACL: function(session) {
return {
"*": {
"*": false
},
"57fbbdb0a2400000": {
"*": true
},
"roles": {
"user": {
"read": true
}
}
};
}
});
};
`
如果定义 Model 时未指定 ACL，则等同于设定了缺省权限：
`JavaScript
{
"*": {
"*": true
}
}
`


$3


ACL 主体描述有三种，用户 id，用户 role 和 , id 表示一个具体的用户，role 表示具有某个角色的用户， 表示所有用户：

| 主体 | 描述 | 优先级 |
|-------|-------------|-------|
| id | 具体用户的 id | 1 |
| role | 用户组名 | 2 |
| * | 全体 | 3 |

在检查权限时，首先会匹配 id 对应的权限，如果未指定，则匹配用户 role 对应的权限，如果仍为指定，则查看是否指定了 的权限，如果 也未指定，则没有权限。

比如上面的权限配置，指定了 user 用户组可以阅读，用户 57fbbdb0a2400000 拥有全部权限，而其它用户没有任何权限。

$3

ACL 根据 API 行为将权限分类五种：

| 权限 | 描述 | 允许类型 |
|--------|------------|----------------------|
| create | 创建对象 | true / false / array |
| read | 读取对象 | true / false / array |
| write | 修改对象 | true / false / array |
| delete | 删除对象 | true / false |
| find | 查询对象列表 | true / false |
| * | 匹配所有权限 | true / false / array |

权限制定 true 为允许访问，为 false 为禁止访问，为 array 为只允许指定的字段的访问。delete 和 find 不接受 array，如果设置了 array 则视同为 true。如果指定的权限不存在，则匹配同主体下的 * 权限。若都不存在，再一次查询下一优先级的主体。

比如以上例子，如果需要设定 user 只允许读取 title 和 detail，其他人可以读取 title，则可以这样设定：

`JavaScript
{
"*": {
"*": false,
"read": ['title']
},
"57fbbdb0a2400000": {
"*": true
},
"roles": {
"user": {
"read": ['title', 'detail']
}
}
}
`

$3


在 Model 上设定的是整个类的权限，如果需要对具体的对象设定权限，可以通过设置 OACL 来实现：
`JavaScript
module.exports = db => {
db.define('person', {
name: String,
sex: ["male", "female"],
age: Number
}, {
ACL: function(session) {
return {
"*": {
"*": false
}
}
},
OACL: function(session) {
var _acl = {};
if(this.id === session.id)
_acl[session.id] = {
"*": true
};

return _acl;
}
});
};
`
在这个例子中，当访问者是对象本人时，将被允许全部操作，否则禁止一切访问。会按照以下步骤检查权限：
* person[57fbbdb0a2400000] => OACL
* person => ACL

$3


扩展对象的访问权限控制和基础对象权限相似，唯一不同的是在 ACL 需要单独指定：
`JavaScript
module.exports = db => {
var Person = db.define('person', {
name: String,
sex: ["male", "female"],
age: Number
},{
ACL: function(session) {
return {
"*": {
"read": ['name', 'sex'],
"extends": {
"pets": {
"read": true,
"find": true
}
}
}
}
},
OACL: function(session) {
var _acl = {};
if(this.id === session.id)
_acl[session.id] = {
"*": true,
"extends": {
"pets": {
"*": true
}
}
};

return _acl;
}
});

var Pet = db.define('pet', {
name: String
});

Person.hasMany('pets', Pet);
};
`
这个定义中，任何人都可以查阅个人信息的 name 和 sex，并自由查阅和搜索他的 pets，用户本人可以操作自己的所有数据，以及拥有自己宠物信息的全部权限。

在检查扩展对象的访问权限时，会分别检查对象权限和扩展对象权限。比如以下请求：
`sh
curl -X GET http://localhost/1.0/person/57fbbdb0a2400000/pets/57fbbdb0a2400007
`
会按照以下步骤检查权限：
* pets[57fbbdb0a2400007] => OACL
* person[57fbbdb0a2400000] => OACL => extends => pets
* person => ACL => extends => pets
* pets => ACL

Utils

$3

如果要使用 @fxjs/webx 的高级特性, 你需要了解至少以下类型. 更多的类型可参见 [@types/app.d.ts]

`typescript
interface FibAppORMModelFunction {
(req: FibAppReq, data: FibAppReqData): FibAppModelFunctionResponse
}

interface FibAppSetupChainFn {
(origReq: FibAppHttpRequest, classname: string, func: FibAppORMModelFunction): void;
}

interface FibAppReq {
session: FibAppSession
query: FibAppReqQuery
request?: FibAppHttpRequest
error?: APPError
}

interface FibAppReqData {
[key: string]: any;
}
`

Model Function
---------------------

可以为 Model 定义 api，对于复杂数据操作, 可以通过自定义 Function 来完成,

绝大多数权限可以通过 ACL 控制完成，不需要通过 Function 来完成基于对象的权限. Function 可用于完成一些复杂的操作,
- 基于数据的权限, 比如根据审批状态，赋予不同用户组权限
- 多项修改, 比如需要修改多条数据库记录
- 基础 Rest 操作的组合
- 其它任何你认为需要的操作

Model Function 都是 FibAppORMModelFunction 类型, 需通过 POST /:classname/:func 的方式进行调用, 在调用到 func 之前, request 已通过 app.filterRequest 进行过滤.

* app.diagram

绘制数据模型
---------------------

在完成数据定义以后，可以使用 app.diagram() 绘制数据模型的 svg 格式类图，保存至文件会得到类似下面的图像：
!diagram

* app.dbPool

app.db 是 app.dbPool 的别名, 它本质上是一个 [fib-pool] 对象

* app.api

使用 app.api 定制高级操作
---------------------

通过内部方法, 直接进行 rest 风格的操作, 详情可参考 [@types/app.d.ts] 中的 FibAppInternalApis.

- app.api.post: FibAppIneternalApiFunction__Post
- app.api.get: FibAppIneternalApiFunction__Get
- app.api.find: FibAppIneternalApiFunction__Find
- app.api.put: FibAppIneternalApiFunction__Put
- app.api.del: FibAppIneternalApiFunction__Del
- app.api.eget: FibAppIneternalApiFunction__Eget
- app.api.efind: FibAppIneternalApiFunction__Efind
- app.api.epost: FibAppIneternalApiFunction__Epost
- app.api.eput: FibAppIneternalApiFunction__Eput
- app.api.edel: FibAppIneternalApiFunction__Edel
- app.api.elink: FibAppIneternalApiFunction__Elink

如果你对它们的实现感兴趣, 可以参考 [src/classes] 目录下中的实现, 其中单实体的操作(post, get, find, put, del)在 [src/classes/base.ts] 中; 对实体的扩展示例的操作(eget, efind, epost, eput, edel, elink)的实现在 [src/classes/extend.ts]

你可以在 Model Function 中调用 app.api 上的 rest 风格函数, 来定制属于你的函数, 比如

`JavaScript
module.exports = db => {
var Person = db.define('person', {
name: String,
sex: ["male", "female"],
age: Number
}, {
functions: {
/**
* getUserByNicknames 为 FibAppORMModelFunction 类型
*
* @param fibAppReq
* fibAppReq 包含了
* - session
* - query object
* - 原生的 request 信息
* - 如果 request 在传给 @fxjs/webx 之前经过过滤被挂载了别的属性, 这些属性也有效, 比如 @fxjs/session 对 request 添加的字段
* - request.session, 与上一层的 session 为同一对象
* - request.sessionid
*
* @param fibAppReqData
* 来自 POST 请求, request.json(), 默认为 {}
*/
getUserByNicknames (fibAppReq, fibAppReqData) {
// rest get 操作
var data = app.api.get(fibAppReq, db, Person, fibAppReqData.id)
// rest post 操作
var postRes = app.api.post(fibAppReq, db, Person, fibAppReqData.id, {
name: 'test',
sex: 'male',
age: 18
})

if (postRes.error)
throw postRes.error

// 方法的返回值必须为 FibAppModelFunctionResponse 类型
return {
success: postRes.success
}
}
}
});
};
`

FibAppInternalApis 中的所有所有 rest 操作函数, 内部都经过了 app.filterRequest 过滤.

* app.filterRequest: FibAppSetupChainFn

注意该函数无返回值, 而是以最后一个参数作为回调函数. 更多详情可参考 @types/app.d.ts

使用 app.filterRequest 为 app 定制个性化的路由
------------

app.filterRequest 是上述所有的实体相关的操作函数(所有的 rest 操作函数, 和可定制的 Model Function)的前置条件, 它主要做了两件事情:

1. 过滤原生的 HttpRequest 对象 request 为 FibAppReq 对象, 并传给 func 作为第一个参数;
1. 将 request.json() 的结果作为 FibAppReqData 类型对象, 并传给 func 作为最后一个参数;

由于 @fxjs/webx 本质上是一个 [mq.Routing] 对象, 你可以用其 API 定制更多的个性化的路由, 比如

`javascript
// 挂载一个静态目录
app.get('/static', http.fileHandler(path.resolve(__dirname, './static'), {}, true))
// 定制特别的 API
app.post('/__with_cls', (request) => {
/**
* 第二个参数传模型名, 表示寻找内置 model
*/
app.filterRequest(request, 'person',
/**
* @param req: FibAppReq
* @param db: FibAppDb
* @param __internal_model__: FxOrmNS.FibOrmFixedModel
* @param data: FibAppData
*/
(req, db, __internal_model__, data) => {
// Do what you want to do
}
)
})
// 定制无关内置模型的 API
app.get('/__null_cls', (request) => {
/**
* 第二个参数传 '', 表示不寻找内置 model, 此时, 回调函数类型为 FibAppFilterableApiFunction__NullModel, 即第三个参数 __null_cls__ 为 null;
*/
app.filterRequest(request, '',
/**
* @param req: FibAppReq
* @param db: FibAppDb
* @param __null_cls__: null
* @param data: FibAppData
*/
(req, db, __null_cls__, data) => {
// Do what you want to do
}
)
})
`

实际上, Model Function 正是通过 app.filterRequest 实现的, 详情可参考 [src/classes/index.ts] 中关于 app.post(':classname/:func', ...) 的实现.

View Functions

通过在 orm 的 opts 中添加 viewFunctions , 可以定义该模型相关的视图处理函数; 基于此, 你可以使得 webx 具有直接输出 html 的能力: 当来自客户端的 http 请求头是 Accept: text/html 时, webx 会尝试使用 viewFunctions 定义的函数处理视图. 参考下例:

`javascript
const fpug = require('fib-pug')
const ejs = require('ejs')

db.define('user', {
name: String,
sex: ["male", "female"],
age: Number,
password: String,
salt: String
}, {
...
viewFunctions: {
/**
* @ctx Accept: text/html
*
* 当客户端发起 GET /user/1 时, 会调用此函数;
*
* 如果 id=1 的 user 存在, 则 result = {sucess: ...}; 否则 result = {error: ...}
*/
get (apiResult) {
let tpl = fpug.compile(
fs.readTextFile(path.resolve(__dirname, './tpl.get.pug'))
)
return {
success: tpl(apiResult && {user: apiResult.success} || {})
}
},
/**
* @ctx Accept: text/html
*
* 当客户端发起 GET /user 时, 会调用此函数
*
* apiResult = {sucess: ...};
*/
find (apiResult) {
let tpl = ejs.compile(
fs.readTextFile(path.resolve(__dirname, './tpl.find.ejs'))
)
return {
success: tpl(apiResult && {users: apiResult.success} || {})
}
},
/**
* @ctx Accept: text/html
*
* 当客户端发起 GET /user/profile 时, 会调用此函数.
*
* 由于 static: true, 此时 handler 的第一个参数 _ 恒为 null
*
* @note 注意该路由与 /user/1 同属于 /:classname/:id 格式, 但 webx
* 会优先尝试调用该方法.
*
*/
profile: {
static: true,
/* _ is null /
handler (_) {
let tpl = ejs.compile(
fs.readTextFile(path.resolve(__dirname, './tpl.profile.ejs'))
)
return {
success: tpl()
}
}
}
}
});
`

#### 调用优先级
当客户端发起 Accept: text/html 的 http 请求时, viewFunctions 的调用优先级是这样的:

- /:classname/:idOrFunc ==> viewFunctions.idOrFunc > viewFunctions.get
- /:classname ==> viewFunctions.function

#### 定义选项

`javascript
viewFunctions: {
get: {
// {boolean}, default false
static: true,
// static === true, apiResult 为 null; 否则, apiResult 为 {success: ...} 或 {error: ...}
handler (apiResult) {
return {
success: ...
}
}
},
/**
* 此时 等价于
* {
* static: true,
* handler: func2
* }
*/
func2 () {
return {
success: ...
}
}
}
`

1. 如果 viewFunction 的 static 为 true, viewFunction 函数的第一个参数为 null;
1. 如果 viewFunctions 没有 viewFunction.get, viewFunction.find, viewFunction.eget, viewFunction.efind 定义时, 所有该导向这些viweFunction的请求都等价于直接请求对应的 webx 内部 API 方法.
1. 如果 viewFunction 的 static 不为 true, 如果存在对应的 webx 内部 API 方法 , 则 viewFunction 函数的第一个参数是该对应方法的返回值;

关于第 2 点, 比如 Model user 有如下定义

`javascript
viewFunctions: {
}
`

此时发起 {Accept: text/html, GET /user/1} 请求, 不会通过 viewFunctions 处理, 该请求等价于 {Accept: applicaton/json, GET /user/1} 请求的结果. 同理, 此时发起 {Accept: text/html, GET /user} 请求等价于发起 {Accept: applicaton/json, GET /user} 请求.

关于第 3 点, 比如 Model user 有如下定义
`javascript
viewFunctions: {
func1: {
static: false,
handler (apiResult) {

}
}
}
`

此时发起 {Accept: text/html, GET /user/func1} 请求, 由于它可以被认为是请求 id=fun1 的 user 的信息, 因此, 如果 id=func1 的 user 真的存在且可以被请求道, 则此时 handler 的第一个参数 apiResult 就是 { success: [userInfo] }; 若 id=fun1 的 user 不存在或者因ACL 权限无法被用户访问到, 则 apiResult 为 { error: ... }

这个特性意味着你可以对某些 Model 的特定对象做特殊处理, 比如, 对 id=888 的 User 设定为 Lucky Dog, 返回特别的 html 给客户端 :)

$3

#### 共同点
viewFunction 与 function 很相似

1. 都要返回符合 FibAppResponse 格式 的对象
1. 都是 ORM Model 的定义选项

#### 区别
1. function 处理 webx 中的 POST /:classname/:func 请求; viewFunctions 处理 webx 中的 GET /:classname/:func 且 Accept 头包含 text/html 的请求
1. function 函数的返回值, webx 会尝试以 json 的方式写入 HttpResponse; viewFunction 函数的返回值, webx 会尝试以文本的方式写入 HttpResponse`

[fib-pool]:https://github.com/fibjs/fib-pool
[@types/app.d.ts]:@types/app.d.ts
[src/classes]:src/classes
[src/classes/index.ts]:src/classes/index.ts
[src/classes/base.ts]:src/classes/base.ts
[src/classes/extend.ts]:src/classes/extend.ts
[mq.Routing]:http://fibjs.org/docs/manual/object/ifs/routing.md.html