Nestfy 框架
一个基于 Nestjs 的 Restful 后台框架。
本框架旨在帮助开发人员快速搭建一套成型的企业后台 REST 应用。
使用本框架之前需要先了解 Nestjs 框架
[TOC]
如何安装
npm:
npm install --save nestfy
yarn:
yarn add nestfy
使用方法
日志
本框架集成了 log4js 日志模块，开启日志功能需要在配置文件中开启日志功能，并进行配置。
如下给出几种工程中常用的配置：
日志只输出到 console 控制台
"logging": {
"enable": true,
"configuration": {
"appenders": {
"console": { "type": "stdout" }
},
"categories": {
"default": { "appenders": ["console"], "level": "info" }
}
}
},
日志输出到控制台，并且还输出到 2 个文件，一个文件是记录所有日志，一个文件只记录错误日志
日志文件如果超过 maxLogSize 设置的容量，则会产生新文件
旧的日志文件会自动进行备份，备份文件会被压缩为 gz 格式
backups 设置保存日志文件的个数，多出的则被删除
"logging": {
"enable": true,
"configuration": {
"appenders": {
"txt": {
"type": "file",
"filename": "./logs/app.log",
"maxLogSize": 10485760,
"backups": 10,
"compress": true
},
"err": { "type": "file", "filename": "./logs/err.log", "maxLogSize": 10485760, "backups": 5, "compress": true },
"out": { "type": "stdout" }
},
"categories": {
"default": { "appenders": ["out", "txt"], "level": "debug" },
"error": { "appenders": ["err"], "level": "error" }
}
}
}
日志输出到控制台和一个文件中
每天会产生一个新的日志文件，备份的旧文件会以日期命名
"logging": {
"enable": true,
"configuration": {
"appenders": {
"txt": { "type": "dateFile", "filename": "./logs/nestfy.log" },
"out": { "type": "stdout" }
},
"categories": {
"default": { "appenders": ["out", "txt"], "level": "info" }
}
}
},
更详细的配置项，请参考 log4js 官方文档
跨域
允许所有请求 <推荐配置>
"cors": {
"enable": true,
"configuration": {}
}
只允许从 example.com 过来的请求
"cors": {
"enable": true,
"configuration": {
"origin": "http://example.com"
}
}
更详细的配置参数，请参考 CORS 官网 https://github.com/expressjs/cors
参数校验
web 请求的参数可以自动被校验。
本框架可以从全局来进行控制，是否启用 DTO 参数校验的功能。
"validation": {
"enable": true,
"configuration": {
"skipMissingProperties": true
}
}
具体的配置参数，可以参考class-validator 官网
只有校验参数成功后，才进入 Controller 层；如果校验失败，则框架会抛出 Validation 异常，自动返回 错误的 JSON 结果给客户端。
示例如下：
query-photo.dto.ts
import { ApiModelProperty } from '@nestjs/swagger';
import { Type } from 'class-transformer';
import { IsDefined, IsInt, IsNotEmpty, IsNumberString, IsString } from 'class-validator';
export class QueryPhotosDto {
@ApiModelProperty({ description: '查询偏移量', required: true })
@IsDefined()
@Type(() => Number)
@IsInt()
public offset: number;
@ApiModelProperty({ description: '查询个数', required: true })
@IsDefined()
@Type(() => Number)
@IsInt()
public limit: number;
@ApiModelProperty({ description: '名称', required: false })
@IsString()
@IsNotEmpty()
public readonly name: string;
}
错误请求(不符合如上 DTO 要求的请求)，被框架处理后的返回结果:
{
"success": false,
"status": 400,
"timestamp": "2019-01-24T09:57:44.261Z",
"message": "You have an error in your request's body. Check 'errors' field for more details!",
"errors": [
{
"target": {},
"property": "offset",
"children": [],
"constraints": {
"isDefined": "offset should not be null or undefined"
}
},
{
"target": {},
"property": "limit",
"children": [],
"constraints": {
"isDefined": "limit should not be null or undefined"
}
}
],
"path": "/api/rest/v1/photos"
}
自动记录 web 请求时间
项目开发的过程中，有时候需要在日志中打印出 web 请求到达的时间，后台处理消耗的时长，请求返回的时间等信息。
使用本框架，直接在nestfy.json配置文件中将如下开关开启即可。
"request": {
"traceRequestDuration": true
}
auth 模块
该模块适用于基于 token 认证的后台项目，如果使用 session 机制，请关闭此开关。
开关开启后，会在全局范围内启用 token 认证，每一个 web 请求，都会去解析 header 中是否包含 token 信息，解析后的结果会存放在 express.Request 对象的由 decodedTag 指定的属性中。如下配置，就是存放在 req.user 中。
"auth": {
"enable": false,
"headerTag": "x-access-token",
"secret": "i6r5LgMJdoa5trlM",
"expiresIn": "24h",
"decodedTag": "user"
}
有些接口，在用户未登录的时候，也需要能够访问，这时候可以使用 @Auth 注解
放在函数前面，用于禁止该路由的 token 验证
import { Auth } from 'nestfy';
...
@Auth(false)
@Get('/extends')
public async extends(@Query() query: any): Promise<any> {
return this._admAwardService.extends(query.date);
}
swagger 支持
开启功能可以使用swagger自动产生API文档，可用配置如下，swagger的使用方法请看这里
"swagger": {
"enable": true,
"title": "nestfy-starter",
"description": "The photo API description",
"schemas": "http",
"version": "1.0",
"email": "qinyang_1980@qq.com",
"path": "/doc"
}
AppUtil
一个工具类，
请将名为 nestfy.json 的配置文件放在工程的根目录，模板如下：
!> 请带注释一起 copy，nestfy 可以识别 jsonc 格式的配置文件。
nestfy.json
{
"app": {
"port": 3000,
"setUpMsg": "Nestfy server started",
"apiPrefix": {
"enable": true,
"prefix": "/api/rest"
}
},
"logging": {
"enable": true,
"configuration": {
"appenders": {
"txt": { "type": "dateFile", "filename": "./logs/nestfy.log" },
"out": { "type": "stdout" }
},
"categories": {
"default": { "appenders": ["out", "txt"], "level": "info" }
}
}
},
"request": {
"traceRequestDuration": true,
"cors": {
"enable": true,
"configuration": {}
},
"bodyParser": {
"enable": true,
"limit": "5mb"
},
"validation": {
"enable": true,
"skipMissingProperties": true
},
"auth": {
"enable": false,
"headerTag": "x-access-token",
"secret": "i6r5LgMJdoa5trlM",
"expiresIn": "24h",
"decodedTag": "user"
}
},
"response": {
"success": {
"defaultMessage": "执行成功!",
"successField": {
"enable": true,
"name": "success"
},
"statusField": {
"enable": true,
"name": "status"
}
},
"failure": {
"defaultMessage": "执行失败!",
"successField": {
"enable": true,
"name": "success"
},
"statusField": {
"enable": true,
"name": "status"
}
}
},
"swagger": {
"enable": true,
"title": "nestfy-starter",
"description": "The photo API description",
"schemas": "http",
"version": "1.0",
"email": "qinyang_1980@qq.com",
"path": "/doc"
}
}
然后在程序中导入 AppUtil 类，如下使用方式：
import { AppUtil } from 'nestfy';
import { ApplicationModule } from './modules/app.module';
AppUtil.bootstrap(ApplicationModule);
这样，一条语句即完成了应用类的创建，运行成功后，还会打印出 成功日志。
