node-framework/wiki/docs/config.md

node-framework

# config

config目录列出了node-framework所有的配置项，分成多个文件。

* [errorHandler.js](#errorHandler.js)
* [global.js](#global.js)
* [logger.js](#logger.js)
* [middlewares.js](#middlewares.js)
* [monitor.js](#monitor.js)
* [ral.js](#ral.js)
* [routes.js](#routes.js)
* [server.js](#server.js)
* [session.js](#session.js)
* [view.js](#view.js)

__请注意：__node-framework每个配置项都有默认值。如果用户编写了对应的配置文件和某个字段，则该字段以用户为准。如果用户并没有创建对应的配置文件或者配置文件中没有对某个字段进行定义，则以默认配置为准。因此在实际项目的config目录中并不要求所有配置文件都必须创建并正确配置。
您可以点击上面的链接快速定位到指定文件的详细说明。

## errorHandler.js

errorHandler用以更简便地配置应用出错时处理错误的控制器名称。  
配置可以以HTTP状态码为粒度，当出错类型无法匹配所有配置的状态码时，系统将使用全局错误处理控制器。
如果用户配置的控制器并不存在，系统将会发射(emit)一个名为`controller:404`的事件并记录到错误日志中。
示例错误处理配置文件如下：

```javascript
// 错误处理配置文件errorHandler.js
module.exports = {
    // 全局错误处理控制器和响应方法，如果用户没有配置对应状态码的错误处理，则使用全局配置
    controller: 'errorHandler',
    action: 'handle',

    // 以状态码为粒度的配置
    statusCode: {
        404: {
            controller: 'errorHandler',
            action: 'handle404'
        }
    }
};
```

默认情况下并没有对应的错误处理配置文件，但系统会处理两种错误情况。

1. 在找不到路由规则对应的控制器(404)时，系统会将状态码直接写入到响应体中。
2. 在其他错误(500)时，如果处于debug状态下(`global.js`中的`debug`选项)，则会将错误及其堆栈调用信息全部写入到响应体中；否则直接将状态码写入并返回。

## global.js

global用以配置应用最核心最全局的配置项。包含以下字段：

字段名 | 类型 | 默认值 | 说明 
-------|------|--------|------
debug | boolean(@CLASS=type type-boolean) | `false` | 是否处于debug模式。如果是，则会打印一些出错时的堆栈信息等。 
appname | string(@CLASS=type type-string) | `'default'` | app默认名称，会在启动时的console以及log中使用 
appdir | string(@CLASS=type type-string) | `process.cwd()` | 指定代码根目录，默认为启动`$ node index.js`时的目录位置 
version | string(@CLASS=type type-string) | `'0.0.0.0'` | 项目版本号，会在启动时的console中使用 
author | array(@CLASS=type type-array) | `['ecrd-fe']` | 项目开发人员，会在启动时的console中使用 
staticDir | string(@CLASS=type type-string) | `'./public'` | 静态文件根目录。如果输入为相对路径，则根据`appdir`字段进行计算。详见[public](/wiki/public) 
controllerDir | string(@CLASS=type type-string) | `'./controllers'` | 控制器根目录。如果输入为相对路径，则根据`appdir`字段进行计算。详见[controllers](/wiki/controllers) 
middlewareDir | string(@CLASS=type type-string) | `'./controllers'` | 中间件根目录。如果输入为相对路径，则根据`appdir`字段进行计算。详见[middlewares](/wiki/middlewares) 
templateDir | string(@CLASS=type type-string) | `'./views'` | 前端页面模板根目录。如果输入为相对路径，则根据`appdir`字段进行计算。详见[views](/wiki/views) 
pluginDir | string(@CLASS=type type-string) | `'./plugins'` | 模板plugin根目录。如果输入为相对路径，则根据`appdir`字段进行计算。详见[plugins](/wiki/plugins) 
appid | number(@CLASS=type type-number) | - | 用以区分app的唯一标示，在监控模块会使用。详见[监控功能](/wiki/monitor) 
appkey | string(@CLASS=type type-string) | - | 用以验证是否为合法app，在监控模块会使用。详见[监控功能](/wiki/monitor) 

示例全局配置文件如下：

```javascript
module.exports = {
    // 当前的运行模式
    debug: true,

    // 指定app的名字
    appname: 'demo',
    // 指定代码根目录
    appdir: './',

    // 版本号
    version: '0.0.0.1',

    // 作者
    author: ['sekiyika'],

    appid: '1',

    appkey: '9d27ebb4-cc4d-488e-91d0-43359d4b31fb'

};
```

## logger.js

node-framework内部使用[winston](https://github.com/flatiron/winston)进行日志管理。logger.js是对日志记录进行配置，字段如下：

字段名 | 类型 | 默认值 | 说明 
-------|------|--------|------
dir | string(@CLASS=type type-string) | `'./log'` | 生成日志文件的根目录 
level | string(@CLASS=type type-string) | 线上：`'info'`(@BR)线下：`'silly'` | 记录日志等级。详见[logging-levels](https://github.com/flatiron/winston#logging-levels) 
maxsize | number(@CLASS=type type-number) | `4 * 1024 * 1024 * 1024 * 1024` (4T) | 单个日志文件的最大容量，单位字节。如果超过最大限制，则会新建一个日志文件。 
dailyRotatePattern | string(@CLASS=type type-string) | `'.yyyy-MM-dd'` | 如果设置了这个字段，则使用`winston.transports.DailyRotateFile`。在默认模式下使用按日期分割文件，因此日志文件名称形如appname.log(.wf).2014-09-28。(@BR)(@BR)    如果没有设置此字段，则使用`winston.transports.File`。这样会把所有日志都记录在同一个文件中。 
transports | array(@CLASS=type type-array) | `[]` | 记录普通日志(对应等级为`silly`，`debug`，`verbose`，`info`)使用的transports。(@BR)如果设置了这个字段，则使用用户提供的类名作为transports。否则参见字段`dailyRotatePattern`的说明使用`DailyRotateFile`或者`File`。在debug模式下也会在console中打印日志。(@BR)    有关transports的说明请[点击这里](https://github.com/flatiron/winston/blob/master/docs/transports.md) 
wfTransports | array(@CLASS=type type-array) | `[]` | 记录错误日志(对应等级为`warn`, `error`, `fatal`)使用的transports。(@BR)如果设置了这个字段，则使用用户提供的类名作为transports。否则参见字段`dailyRotatePattern`的说明使用`DailyRotateFile`或者`File`。在debug模式下也会在console中打印日志。(@BR)有关transports的说明请[点击这里](https://github.com/flatiron/winston/blob/master/docs/transports.md) 

示例日志配置文件如下：
```javascript
module.exports = {

    // appdir目录下的log目录
    dir: './myLog',

    // 线上线下都使用level = info
    level: 'info'

    // 指定单个文件最大大小为4G
    maxsize: 4 * 1024 * 1024 * 1024,

    // 设为空表示使用winston.transports.File
    dailyRotatePattern: ''

};
```

## middlewares.js

配置的middleware将会应用到每个请求上。
middlewares的配置是一个数组，数组中的元素可以是String, Function或者是Object

### String
当middleware为string的时候，分为两种情况，如下：

* connect.\* => node-framework会应用connect中对应的middleware
* \* =>字符串不能包含`.`，会查找在config中的middlewareDir中配置的middleware

### Function
    
如下所示：
```javascript
function (app) {
    return function (req, resp, next) {
        app.logger.silly('I am a middleware.');
        next();
    }
}
```

### Object
Object的方式最为灵活

字段名 | 类型 | 默认值 | 说明 
-------|------|--------|------
name (optional) | string(@CLASS=type type-string) | `''` | 表示该middleware的名字，该字段为可选字段，但是name和fn必存在其中之一 
fn (optional) | function(@CLASS=type type-function) | - | middleware的方法，该字段为可选字段，但是name和fn必存在其中之一 
args (optional) | array(@CLASS=type type-array) | - | 给middleware的参数 

middleware的方法被执行的时候，参数的最后一个总是`app`

```javascript
module.exports = {

    middlewares: [
        'connect.timeout',
        function (app) {
            return function (req, resp, next) {
                app.logger.silly('I am a middleware.');
                next();
            }
        },
        {
            name: 'firstArg',
            fn: function (firstArg, app) {
                var arg = firstArg;

                return function (req, resp, next) {
                    app.logger.silly(arg);
                    next();
                };
            },
            args: [ 'first_arg' ]
        }
    ]

};
```

## monitor.js

node-framework内置监控模块，可以帮助开发者快速全面地掌握应用的各类信息，方便及时调整集群规模和修复问题等等。更多关于监控的信息[请点这里](/%E6%89%A9%E5%B1%95%E5%8A%9F%E8%83%BD/monitor)。monitor.js是用以配置监控模块的，其字段如下：

字段名 | 类型 | 默认值 | 说明 
-------|------|--------|------
enable | boolean(@CLASS=type type-boolean) | `false` | 是否打开监控服务 
host | string(@CLASS=type type-string) | `'cq01-rdqa-pool028.cq01.baidu.com'` | 监控信息发往的监控服务器域名 
port | number(@CLASS=type type-number) | `8888` | 监控信息发往的监控服务器端口 
frequency | object(@CLASS=type type-object) | 见下方子字段详细描述 | 见下方子字段详细描述 
frequency.status | number(@CLASS=type type-number) | `1000` | 瞬时信息的发送频率，单位ms。(@BR)瞬时信息是指实时的请求数，内存使用情况等，监控模块会根据收集的信息画出实时更新的趋势图，因此不建议间隔过长。 
frequency.stats | number(@CLASS=type type-number) | `5000` | 累积信息的发送频率，单位ms。(@BR)累积信息是指服务器运行开始至今的总请求数，响应数，物理机信息（包括内存，CPU个数等）。这些信息对于实时要求并不高。(@BR)__建议设置成`frequency.status`的整数倍__ 
responseWarningThreshold | number(@CLASS=type type-number) | `500` | 长时间响应阈值，单位ms。(@BR)从收到请求到发送响应的总处理时间如果超过这个时间会被记录为长时间响应，和普通响应区分统计。 
path | object(@CLASS=type type-object) | 见下方子字段详细描述 | 见下方子字段详细描述 
path.status | string(@CLASS=type type-string) | `'/api/status'` | 瞬时信息发往的监控服务器路径，一般情况下不需要另外配置。 
path.stats | string(@CLASS=type type-string) | `'/api/stats'` | 累积信息发往的监控服务器路径，一般情况下不需要另外配置。 
path.crash | string(@CLASS=type type-string) | `'/api/crash'` | 出错信息发往的监控服务器路径，一般情况下不需要另外配置。 

示例监控配置文件如下：

```javascript
module.exports = {
    /**
     * 是否打开监控信息推送
     * @type {Boolean}
     */
    enable: true,

    /**
     * 统计信息推送地址，不用加http://
     * @type {String}
     */
    host: 'monitor.node.baidu.com',
    /**
     * 统计信息推送端口
     * @type {Number}
     */
    port: 80,

    /**
     * 监控信息推送频率，单位ms。
     * 时间触发的推送，是以status为基准，因此其他时间间隔必须大于status并推荐是其倍数。
     * @type {Object}
     */
    frequency: {
        /**
         * 瞬时信息，包括请求数，内存使用情况。monitor有实时更新的趋势图，因此建议不要过长。
         * @type {Number}
         */
        status: 2000, 

        /**
         * 累积信息，包括总请求数，响应数，机器信息等。这些对于实时要求不高。
         * @type {Number}
         */
        stats: 10000
    },

    /**
     * 长时间响应阈值
     * @type {Number}
     */
    responseWarningThreshold: 300
};
```

## ral.js

node-framework内部使用[node-ral](https://github.com/fex-team/node-ral)作为获取数据的方式，目前支持http协议。ral.js是针对node-ral进行配置，字段如下：

字段名 | 类型 | 默认值 | 说明 
-------|------|--------|------
adapter | string(@CLASS=type type-string) | `'node-ral'` | 适配器类型。这里也可以选择yog-ral，支持mcpack和nshead等功能。 
timeout | number(@CLASS=type type-number) | `3000` | 数据请求超时时间，单位ms。 
retry | number(@CLASS=type type-number) | `2` | 数据请求失败重试次数。 
service | object(@CLASS=type type-object) | {} | 提供给ral使用的service，可以在ral.js中配置service对象，service的规则可以参见[https://github.com/fex-team/node-ral#config-file](https://github.com/fex-team/node-ral#config-file)

示例数据获取配置文件如下：

```javascript
module.exports = {
    
    adapter: 'yog-ral',

    // 请求超时
    timeout: 5000,

    // 请求重试次数
    retry: 10

};
```

另外，配置service有两种方式，其一在ral.js文件中配置，其二在config目录中新建service目录，在目录中添加各个service配置文件，如下面的代码所示：
```javascript
// WEIGOU.JS
module.exports = {
    "unpack": "json",
    "method": "GET",
    "encoding": "utf-8",
    "balance": "random",
    "protocol": "http",
    "server": [{ 
        "host": "weigouapp.baidu.com",
        "port": 80
    }]
};
```

## routes.js

routes.js用以配置URL路由规则，包括静态请求和动态请求。配置文件以object的形式存在，key为路由规则，value为处理对象。
路由规则的设置方式多样，灵活多变。支持使用通配符、添加HTTP方法名称等等。
__请注意__路由匹配规则的顺序从上至下，即如果某个URL能够匹配多个规则，按第一个匹配到的为准。下面列举几种常用的方式：
```javascript
// 几种常用路由规则配置示例
module.exports = {

    // 欢迎页面
    '/' : {},

    // 为URL分段命名，controller, action, id等变量可以在处理对象中以{var-name}的形式使用。
    // 内部采用pillarjs/path-to-regexp模块，可以访问https://github.com/pillarjs/path-to-regexp获取更多信息
    '/:controller/:action/:id' : {},

    // 可以使用通配符，可以通过request.param('0')来获取括号匹配的内容
    '/assets/(.*)' : {},

    // 可以添加http method。
    // 可选值为'get', 'head', 'post', 'put', 'delete', 'trace', 'options', 'connect', 'patch'
    // 不写默认为'all'，表示上述方法均支持。
    'get /logger.js' : {},

    // 正则表达式的方式，例子中的target匹配正则中的小括号中的内容
    'r|redirect-url/(.*)|target' : {}
};
```

处理对象可以有三种类型：

1. 字符串(string)。表示直接重定向到该URL。该字符串可以是相对路径(以`/`开头)，也可以是绝对路径(以`http://`或者`https://`开头)。如果不符合以上两者，则被认为是非法路由规则而被废弃
2. 方法(function)。该方法会当做中间件(middlewares)被执行
3. 对象(object)。对象可以对路由规则进行多种配置，下面列出几种常用方式

a. 静态请求配置方式

字段名 | 类型 | 示例取值 | 说明 
-------|------|--------|------
type | string(@CLASS=type type-string) | `'static'` | 指定当前请求为静态请求。可选值目前__只有__`'static'`。(@BR)为了配置一个合理的静态规则还__必须__设置`app.config.global.staticDir` 
target | string(@CLASS=type type-string) | `'/assets/{0}'` | 静态请求的URL映射的实际文件路径规则。此值中{0},{1}等对应映射规则中的括号顺序。(@BR)(@BR)举例来说，假设映射规则为`'/assets/(.*)'`(@BR)如果不设置target，访问当用户访问URL`host:port/assets/js/sample.js`时，请求将会被定位到`app.config.global.staticDir/assets/js/sample.js`(@BR)如果设置target为`'/myFolder/{0}'`，那么用户访问同样的URL，将会被定位到`app.config.global.staticDir/myFolder/js/sample.js` 
etag | boolean(@CLASS=type type-boolean) | `true` | 是否使用etag，默认为`true`(@BR)详情请见[此处](https://github.com/visionmedia/send#options) 
maxAge | number(@CLASS=type type-number) | `365 * 24 * 3600 * 1000` | 设置http请求缓存的最长时限，单位ms。默认为0，表示不缓存(@BR)详情请见[此处](https://github.com/visionmedia/send#options) 
dotfiles | string(@CLASS=type type-string) | `'deny'` | 文件或路径以`.`开头的文件的访问策略，可选策略为`'allow'`，`'deny'`，`'ignore'`。默认为`'ignore'`。(@BR)详情请见[此处](https://github.com/visionmedia/send#options) 
extensions | array(@CLASS=type type-array) | `['html', 'htm']` | 当请求的文件不存在时按数组序追加后缀并重试。默认为`false`表示不重试。如果请求的文件已经带有后缀则不重试(@BR)详情请见[此处](https://github.com/visionmedia/send#options) 
index | boolean(@CLASS=type type-boolean) | `false` | 当用户输入URL为目录时，是否查找默认的欢迎HTML文件。如果设置为字符串或者数组，会根据数组提供的名字逐个查找；如果设置为false，则禁用此功能直接返回404。(@BR)详情请见[此处](https://github.com/visionmedia/send#options) 

b. 重定向配置方式

字段名 | 类型 | 示例取值 | 说明 
-------|------|--------|------
redirect | string(@CLASS=type type-string) | `'{target}'` | 配置重定向的另一种方式 


c. 动态请求配置方式

字段名 | 类型 | 示例取值 | 说明 
-------|------|--------|------
controller | string(@CLASS=type type-string) | `'{controller}'` | 处理该请求的控制器名字。用{}包裹表示动态变量。例如映射规则配置为`'/:controller/:action/(.*)'`，那么`'{controller}'`表示URL中:controller部分的内容。 
action | string(@CLASS=type type-string) | `'{action}'` | 处理该请求的动作名字。用{}包裹表示动态变量。例如映射规则配置为`'/:controller/:action/(.*)'`，那么`'{action}'`表示URL中:action部分的内容。 
middlewares | array(@CLASS=type type-array) | `[]` | 匹配于该规则的所有请求都会应用数组中的middleware 

除了用户配置，node-framework默认提供了三条映射规则（但并未以默认配置文件的形式给出），如下：

```javascript
// 默认路由配置规则
'/:controller/:action/:id((\\d+))': {
    controller: '{controller}',
    action: '{action}'
},
'/:controller/:action': {
    controller: '{controller}',
    action: '{action}'
},
'/:controller': {
    controller: '{controller}'
}
```
__请注意：__如果对同一条规则进行重复配置，以前面的配置为准。默认配置是先于用户配置载入的，因此如果用户配置和默认配置相同，这条规则将不会生效。
结合上述提到的路由规则和处理对象，一个示例路由规则配置文件如下：
```javascript
// 示例路由配置规则
module.exports = {

    // 配置首页
    '/' : {
        controller: 'welcome',
        action: 'index'
    },

    // 配置静态规则。此处配置了target，当用户访问/static/js/sample.js，系统会实际返回/assets/js/sample.js。
    '/static/(.*)': {
        // 指定当前请求是否为静态文件请求
        type: 'static',
        // 如果指定了target，则会用target的作为响应文件的name
        target: '/assets/{0}',
        // 以下配置参考 https://github.com/visionmedia/send#options
        // 是否需要使用etag
        etag: true,
        // max age
        maxAge: 1 * 365 * 24 * 3600 * 1000,
        // 类似于.bashrc这类的文件配置访问许可 deny allow ignore
        dotfiles: 'deny',
        extensions: false,
        index: false
    },

    // 配置中间件，且只应用于get方法
    'get /logger.js': {
        middlewares: [
            function (req, resp, next) {
                resp.send('Hello Logger.js');
                next();
            }
        ]
    },

    // 配置转发规则
    'r|/redirect-url/(.*)|target': {
        // server通过redirect来跳转
        redirect: '{target}'
    },

    // 配置动态规则。实际上这条规则和默认规则是相同的，因此不写也可以。
    '/:controller/:action/(.*)': {
        controller: '{controller}',
        action: '{action}',
        middlewares: [
        ]

        // 添加中间件，在action之前执行
        /*
         middlewares: [
             function (req, resp, next) {
                 console.log('hello world');
                 next();
             }
         ]
         */
    }

};
```

## server.js

server.js用以对启动的WEB服务器进行配置，包括启动端口，全局超时时间等等。详情如下：

字段名 | 类型 | 默认值 | 说明 
-------|------|--------|------
port | number(@CLASS=type type-number) | `8048` | 服务器启动的端口号 
trustProxy | boolean(@CLASS=type type-boolean) | `true` | 设置为true时，server如果发现request headers中存在X-Forwarded-For字段，则作为client的ip，否则使用req.connection.remoteAddress 
etag | boolean(@CLASS=type type-boolean) | `true` | 全局设置etag。如果在config/routes.js设置了具体规则的etag值，则以routes为准。(@BR)关于etag详情请见[此处](https://github.com/visionmedia/send#etag) 
jsonpCallback | string(@CLASS=type type-string) | `'callback'` | 指定jsonp的回调函数的参数名 
timeout | number(@CLASS=type type-number) | `5000` | 全局超时时间，单位ms。 
cluster | object(@CLASS=type type-object) | 见下方子字段详细描述 | 见下方子字段详细描述 
cluster.enable | boolean(@CLASS=type type-boolean) | `true` | 是否启用集群功能。如果启用，系统将会启动一个父进程和多个子进程。子进程负责启动server并处理请求。如果子进程出错，系统会kill该子进程并重新启动一个新子进程用以替换之。 
cluster.max | number(@CLASS=type type-number) | `os.cpus().length` | 启动子进程个数，默认与机器CPU个数相等。 

示例服务器配置文件如下：
```javascript
// 示例服务器配置文件

module.exports = {
    // server运行端口
    port: 8058,

    // 设置为true时，server如果发现request headers中存在X-Forwarded-For字段，则作为client的ip，
    // 否则使用req.connection.remoteAddress
    trustProxy: false,

    // 全局设置etag，此etag的效果会被route中指定的etag覆盖
    etag: false,

    // 指定jsonp的回调函数的参数名
    jsonpCallback: 'callback',

    // 默认超时时间
    timeout: 10000,

    // cluster
    cluster: {
        enable: false
    }
};
```

## session.js

session.js用以配置session

字段名 | 类型 | 默认值 | 说明
-------|------|--------|-----
adapter | object(@CLASS=type type-object) string(@CLASS=type type-string) | 由adapter决定 | 用于存储session的store对象，默认值等同于memory，线上不允许使用memory
options | object(@CLASS=type type-object) | {} | adapater的参数，比如说应用redis的时候，配置redis的ip等等 
session | object(@CLASS=type type-object) | {} | `connect-session`的参数，如secret等 

```javascript
module.exports = {

    // memory为内置的，可以通过引用connect-redis或者connect-mongo等
    adapter: 'memory',

    // 用于adapter
    options: {

    },

    // express.session的配置
    session: {
        secret: '',
        key: 'NODE_SESSION_ID'
    }

};
```



## view.js

view.js用以配置前端模板相关的信息，包括模板引擎类型，后缀名等等，具体如下：

字段名 | 类型 | 默认值 | 说明 
-------|------|--------|------
engine | string(@CLASS=type type-string) | `'ejs'` | 前端模板引擎类型，内部使用consolidate模块统一管理，详见[此处](https://github.com/visionmedia/consolidate.js">此处</a>。(@BR)此外系统还默认支持etpl，详见[此处](https://github.com/ecomfe/etpl) 
ext | string(@CLASS=type type-string) | `'tpl'` | 模板文件的后缀名。在调用`res.render`时传递的第一个参数如果没有扩展名，则默认使用此扩展名 
cache | boolean(@CLASS=type type-boolean) | `false` | 是否使用模板缓存 
options | object(@CLASS=type type-object) | {} | 指定的模板引擎所需的额外参数，随所用模板引擎不同而不同，详见各模板引擎的说明 
plugins | array(@CLASS=type type-array) | [] | 需要使用的模板插件名字的数组。根据`app.config.global.pluginDir`配置的位置查找对应js文件。(@BR)如果选择的模板引擎不支持plugins，则系统会忽略该配置。(@BR)如果plugins支持并能够在对应位置找到，则在生成模板文件之前会调用plugin先进行处理。(@BR)如果plugins支持但无法在对应位置找到，则系统打出一条`'warn'`级别的日志并忽略该plugin 

示例模板配置文件如下：
```javascript
// 一个使用etpl的模板配置文件
module.exports = {

    // 指定使用什么模板
    engine: 'etpl',

    // 指定文件的后缀
    ext: 'tpl',

    // 是否需要缓存
    cache: false,

    // etpl所需配置参数
    options: {
        // etpl标签开关符号
        commandOpen: '{{',
        commandClose: '}}',
        // etpl引入模板目录。内部采用glob，详见https://github.com/isaacs/node-glob
        // 支持单个文件或者目录，但是目录最后必须加/*
        includedFiles: [ 'common/*' ]
    },

    plugins: [
        'testPlugin'
    ]

};
```