Skip to content

wanglihui/ts-restful

Repository files navigation

restful

CircleCI

File % Stmts % Branch % Funcs % Lines Uncovered Line #s
All files 86.98 76.92 84.62 86.91
ts-restful 100 100 100 100
index.ts 100 100 100 100
ts-restful/core 87.93 68.12 82.05 87.57
AbstractController.ts 100 100 100 100
constant.ts 100 100 100 100
decorator.ts 92.44 80.43 90.63 92.17 ... ,38,70,143,175
swagger.ts 66.67 43.48 33.33 66.67 ... 05,207,215,216
ts-restful/core/router 86.03 81.29 88.46 86.12
index.ts 86.03 81.29 88.46 86.12 ... 68,371,373,374

快速使用

  • 支持express和KOA
  • 为了简化ts-express-restful 模块使用,实现了一个restful-started 模块,使用默认配置,一句启动项目.

这个模块主要做那些事情

  • 根据约定自动扫描controller生成路由
  • 依赖注入
  • 函数参数自动注入
  • 综上:减少模板代码,使项目代码更易读
    当我们使用 nodejs express开发web项目时,是否写了很多 路由和 controller 映射的代码?我们的路由规则是否是按照restful规范去实现的呢?
    ts-express-restful帮你去简化路由与controller映射的样板代码,如果按照restfu规范,你只需要关注资源提供方式,剩下的交给ts-express-restful.
    当然如果你想自定义路由也很简单,只需要简单一句注解就好,感谢spring mvc 给了我很大的参考。

Router与Controller自动映射逻辑


此处ctrl为controller类名 去掉 Controller后缀.如类名为 UserController, ctrl为 user;

Controller函数名 映射的Http Method 映射的路由地址
find /ctrl/ GET
get /ctrl/:id GET
update /ctrl/:id PUT
add /ctrl/ POST
delete /ctrl/:id DELETE
@Router("/other", "GET") /ctrl/other GET

主要函数\注解说明


  • @Restful @Restful(mountUrl)

    • 将一个Controller转为一个RestfulController, 此装饰器可以接受一个URL函数,标示此Controller想要挂载的URL,如果没有挂载的URL为Controller名字去掉Controller后缀
  • @Router(url, method?: string, options: any)

    • 将Controller中的函数转为一个可供外部访问的Http Api, 此装饰器可以自定义Controller中函数对外的URL地址
  • @RequestMapping @PostMapping @GetMapping

    • 类似于Router
  • scannerDecorator

    • 此函数会需要扫描注解的路径
  • registerControllerToRouter

    • 此函数会把所有调用了@Restful的controller注册到路由上
  • (controller instance).$isValidId

    • 主要是用于验证此controller 的ID风格,如果此函数返回false,则不是ID
  • (controller instance).$before

    • 调用Controller的每个函数之前会先调用$before函数,此函数中可以做一些权限校验或者数据统一
  • @ResponseBody() 直接在函数中return默认将结果输出

    • 直接将函数返回内容作为response相应内容
  • @SchemaFilter(schema: any, checkType: boolean)

    • 按照schema指定的格式过滤返回结果, checkType 如果不指定或者未true,将严格检查响应的类型是否和指定的schema类型匹配
  • @Autowire

    • 自动注入Service
  • @Service

    • 将一个class标记为service
  • @RequestBody @RequestBodyParam @RequestParam @HttpRequest @HttpResponse @QueryStringParam @Header @Cookie

    • 自动注入函数参数
    • @RequestBody 注入 req.body,
    • @RequestBodyParam 注入 req.body.[参数名]
    • @RequestParam 注入 req.param.[参数名]
    • @QueryStringParam 注入 req.query.[参数名]
    • @HttpRequest 注入 req
    • @HttpResponse 注入 response
    • @NextFunction 注入 next
    • @Cookie 注入cookie中的值 req.cookies[参数名]
    • @Header 注入header中的值 req.headers[参数名]

使用


tsconfig.json 中开启 emitDecorateMetadata
  • 注意: 5.0 后不推荐直接使用 req, res 等,推荐使用 @RequestBody @RequestParam 等获取参数,方便生成文档
// router/index.ts 

import http = require("http");

import {scannerControllers, registerControllerToRouter} from "ts-express-restful";

import path = require("path");
import express = require("express");
var router = express.Router();

scannerControllers(path.join(__dirname, 'controller'));
//挂载到express
registerControllerToRouter(router);


export async function initHttp(app) {
    app.use('/api/v1', router);
}

//或者挂载到koa
// import * as Router from 'koa-router';
// var app = new Koa();
// var route = new Router();
//registerControllerToKoaRouter(router);
// app.use(route.routes());
// controller/city.ts
import {AbstractController, Restful, Router} from "ts-express-restful";

//此处可以是 @Restful('/test')
@Restful()
export class TestController extends AbstractController {
    constructor() {
        super();
    }

    $isValidId(id: string) {
        //只有ID是数字是才认为是ID 如 /test/1 可以请求到get  /test/xx 为返回404  /test/other 为映射到 other函数
        return /^\d+$/.test(id);
    }


    // 调用地址为 /test/:id
    async get(@RequestParam id: number) {
        return {
            id
        }
    }
    
    // 调用地址为 /test/other
    @Router("/other")
    async other(@RequestParam other: string) {
        return {
            other,
        }
    }
}

service自动注入

    @Service()
    export class TestService {

        sayHello() {
            return 'hello world';
        }
    }

    @Restful
    export class TestController {

        @Autowire
        test: TestService;

        @GetMapping("/helloword")
        sayHello() {
            return this.test.sayHello();
        }
    }

@RequestBody @RequestBodyParam @QueryStringParam @HttpRequest @HttpRepsonse

@Restful()
export class TestController {

    @PostMapping("/test")
    async test(@RequestBody test: Test) {
        return test;
    }

    @GetMapping("/test2")
    async test2(@QueryStringParam keyword: string, @QueryString password: string) {
        return {keyword, password};
    }

    @PostMapping("/test3")
    async test3(@HttpRequest req: Request) {
        let body = req.body;
        return body;
    }
    
}
     swagger 文档默认挂在在 /swagger 路径下

changelog

  • V 3.0 支持 @SchemaFilter 直接支持按照指定的schema过滤返回给客户端的结果,schema 参考 https://www.npmjs.com/package/json-filter2
  • v 4.0 使用 reflect-metadata 重新实现metadata信息
  • v 4.0 重新实现 @Service @Autowire
  • v 5.0 支持 @RequestBody @RequestBodyParam @RequestParam @QueryStringParam @HttpRequest @HttpResponse 自动注入到controller函数的参数
  • v 6.0 支持KOA, 支持@Header , @Cookie