Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
228 lines (182 sloc) 7.22 KB

IWinter 一个路由转控制器的 Nodejs 库

npm version NPM downloads

A restful router -> controller library for node.

IWinter 为了让使用者以更优雅的姿势进行路由的编写。名称的由来:

The winter is coming !

以前需要这样编写路由 :(

//app.js
...
let users = require('./routes/users');
let orders = require('./routes/orders');

app.use('/api/users', users);
app.use('/api/orders', orders);
...

//routers/orders.js
...
router.route('/')
    .get(function (req, res, next) {
        let {page, timeRange, customerId, orderNumber} = req.query;
        let limit = constants.PAGE_SIZE;
        let skip = (page - 1) * limit;
        let currentUser = global[Symbol.for('currentUser')];
		let queryCondition = {
			userId: currentUser['_id']
		};
        ...

使用 iwinter 之后可以更优雅的编写路由 :)

import {Controller, Path, GET, POST, PathParam, BodyParam} from 'iwinter';

@Path('/api/orders')
class OrdersController extends Controller {

    @GET
    @Path('/:name/:id', (ctx, next)=> ~~ctx.params.id > 20)
    getAllOrders(@PathParam('id') id: number, @PathParam('name') name: string){
        return [{
            id: id, name, content: 'test', author: 'test', comments: []
        }];
    }

    @POST
    @Path('/add')
    addPost(@BodyParam('order') order: object){
        return order;
    }
}

export default OrdersController;

谁适合使用 IWinter:

* Nodejs 用户
* Typescript 用户
* Express / Koa 用户

========================================== ============================================== ==========================================

IWinter 安装:

npm install --save iwinter

IWinter 引入:

import IWinter from 'iwinter';
OR
const IWinter = require('iwinter');

Koa 中如何使用:

import * as Router from 'koa-router';
...
app.use(new IWinter({
    engine: 'koa',
    router: new Router(),
    dir: path.join(__dirname, 'controller')
}).controller());
...

Express 中如何使用:

1. 路由挂载到app上

import * as express from 'express';
let app = express();
let router = express.Router();
...
new IWinter({
    engine: 'express',
    router: app,
    dir: path.join(__dirname, 'controller'),
    prefix: ''
}).controller();

2. 以中间件的形式使用

app.use(new IWinter({
    engine: 'express',
    router: router,
    dir: path.join(__dirname, 'controller'),
    prefix: ''
}).controller());

构造函数参数配置说明(options: {})

new IWinter({
    engine: 'express',
    router: router,
    dir: path.join(__dirname, 'controller'),
    prefix: ''
})

1. engine 使用的环境类型,可选项 'express | koa', 必需
2. router 路由对象,配置参照 (Koa 中如何使用 | Express 中如何使用),必需
3. dir 控制器文件路径,必需
4. 网关统一前缀,例如 '/api',非必需

API

1. 支持路径装饰器 Path
Path 是一个装饰器工厂函数,接收两个参数: @Path(path: string, permission?: Function),
permission 为权限拦截函数,其参数为原始请求参数 Express: (req, req, next) | Koa: (ctx, next),用于权限验证,返回值: true->验证成功;false->验证失败。
可以进行控制器级别及路径级别的权限验证。

2. 支持 GET POST PUT DELETE 方法,可使用装饰器 @GET @POST @PUT @DELETE

3. 支持获取路径参数、查询参数、post请求体及原始请求对象 PathParam, QueryParam, BodyParam, ReqParam, ResParam, CtxParam, NextParam, OriginParam

Express | Koa 中使用 @PathParam 获取路径参数, @QueryParam 获取查询参数, @BodyParam 获取请求体数据 ;

Express 环境中使用 @ReqParam, @ResParam, @NextParam 可以用于分别获取原始参数,也可通过 @OriginParam 获取原始参数对象 {req, res, next};

Koa 环境中使用 @CtxParam, @NextParam 可以分别用于获取原始参数,也可通过 @OriginParam 获取原始参数对象 {ctx, next}. 之所以暴露原始请求对象是为了方便进行一些自由度更大的操作,例如重定向等。

4. 支持 Before, After 方法,可以对路由处理函数进行切面编程,其参数为原始请求参数 Express: (req, req, next) | Koa: (ctx, next),可在请求处理的前置和后置进行业务逻辑处理。

Changelog

当前最新版本为 1.1.0

1.1.0

增加可以对路由处理函数进行切面编程的钩子函数 Before、After
可以在路由处理的前后进行相应的业务处理操作。

1.0.2

重大改变,增加 Controller 基类,所有的控制器类都需要继承该类:
增加 Controller 基类是为了更加严谨的对控制器类进行判断。

0.5.2

修复 IWinterController(控制器类) 方法内 this 指向的问题:
在 0.5.1 版本中, IWinterController 内的方法的 this 指向 path.ts 文件的 exports 对象,在 0.5.2 版本对该问题进行了修复,IWinterController 方法的 this 指向 IWinterController 实例对象。

0.5.1

修复了 IWinterController(控制器类) 根路径的bug:
在0.5.0版本中,如果 IWinterController 没有装饰器 @Path(path: string) 会导致路由装载错误, 0.5.1版本中修复该问题。

0.5.0

iwinter 第一个发布版本。

从 0.5.2 升级到 1.0.2

从 0.5.2 升级到 1.0.2 版本,只需要做以下改变:

import {Controller} from 'iwinter';
class PostController extends Controller {

}

恭喜你!升级完成 :)

示例项目

recatch-service recatch 项目的后端服务,全面使用 iwinter

使用示例

import {Controller, Path, GET, POST, PathParam, BodyParam, CtxParam, NextParam, OriginParam, Before, After} from 'iwinter';
import {PostModel} from '../models/PostModel';
import {auth} from '../auth';

@Path('/api/posts', auth)
class PostController extends Controller {

    @GET
    @Path('/:name/:id', (ctx, next)=> ~~ctx.params.id > 20)	//Path(path:string, permission: Function)
    @Before((ctx, next) => ctx.beforeHook = 'before')
    @After((ctx, next) => console.log('done'))
    getAllPosts(@PathParam('id') id: number, @PathParam('name') name: string, @CtxParam('ctx') ctx: any){
        //ctx.response.redirect('/users');
        return [{
            id: id, name, content: 'test', author: 'test', comments: []
        }];
    }

    @POST
    @Path('/add')
    async addPost(@BodyParam('post') post: object){
    	let newPost = new Post(post);
        let result = await newPost.save();
        return result;
    }
}

export default PostController;

在 Express 中 getAllPosts 方法需要返回一个立即值 或 Promise 对象;
在 Koa 中 getAllPosts 方法可以使用 async/await

Express 示例
Koa 示例

项目会不断完善,如果有问题欢迎提 Issues

欢迎Star :)