A typeScript httpServer support annotation
npm install jweb
* 1. Usage
* 2. Javascript和TypeScript基础学习
* 3. 1. Controller方法注解
* 3.1. 1.1 注解的调用顺序
* 3.2. 1.2 注解中的错误处理
* 3.2.1. 如何抛出错误？
* 3.2.2. 如何处理错误？
* 3.3. 1.3 如何编写自定义函数注解？
* 3.3.1. 注解示例
* 3.3.2. 示例的依赖说明
* 3.3.3. 注解的编写步骤
* 3.4. 1.4 使用注解实现完整业务功能的示例
* 4. 2. Entity校验注解
* 4.1. 2.1 使用示例
* 4.2. 2.2 注解的调用顺序
* 4.3. 2.4 jweb内置注解和说明
* 4.3.1. Min
* 4.3.2. Max
* 4.3.3. Size
* 4.3.4. Required
* 4.3.5. Type
* 4.4. 2.5 编写自己的验证器
* 4.4.1. 自定义验证器示例
* 4.4.2. 示例关键代码说明
* 4.4.3. 自定义验证器必须遵循的规则
``
npm install
npm run build
npm run start
TypeScript基础学习：https://www.tslang.cn/docs/home.html
ejs模版引擎学习：https://ejs.co | https://ejs.bootcss.com/
先看一个样例（下面的方法都是某一个Controller类中的方法），process方法会在请求到来时被调用：
`typescript
private preAround (ret) {
console.log('preAround', ret)
}
private postAround (ret) {
console.log('postAround', ret)
}
private beforeCall (ret) {
console.log('beforeCall' , ret)
return ret
}
public afterCall (ret) {
console.log('afterCall', ret)
if (ret.err) {
return {
status: -1,
err: ret.err
}
} else {
return ret.data
}
}
@Get('/process/{uid0}')
@Auth
@ResponseBody('json')
@Validation(UserEntity)
@Transactional
public async process (req: Request, res: Response, { uid0 }) {
const user: UserEntity = req.entity
console.log('inside call', user)
let u = await this.userService.hello(user)
let data = {
a: 1,
b: [2, 3, 4],
uid: uid0,
u: u
}
return data
}
`
在样例函数中，定义了preAround、postAround、beforeCall和afterCall，使用了5个注解，每个注解都有一个preCall和postCall的属性，这两个属性的值是一个函数，如下：
`typescript
Auth.preCall = function authPreCall(ret: any, param: string, req: Request, res: Response) {
if (param === 'ignore') {
return {
err: "ignore",
data: null,
from: Auth.name
}
}
return ret
}
Auth.postCall = function authPostCall(ret: any) {
return ret
}
`
注解的调用基于上述两处代码，调用的原则是：
* 首先调用beforeCall
* 然后按照注解使用从上向下的顺序调用preCall
* 然后调用Controller类中的preAround
* 然后调用被注解的方法，在上例中调用process方法
* 然后调用Controller类中的postAround
* 最后按照注解使用从下到上的顺序调用postCall
在上面的示例中，调用链是（Get方法只会在初始化的时候调用，用于注册路由，不会参与到此处的调用链中）：
beforeCall => Auth.preCall => ResponseBody.preCall => ... => preAround=> process => postAround => Transanctionl.postCall => ... => Auth.postCall => afterCall
当然，没有为注解定义postCall或者preCall，那么跳过相关调用。
每一个注解的统一返回格式是：
`js`
{
err,
data
}
前一个注解调用的返回结果会传递给后一个注解调用，例如：
`js`
Auth.preCall = function authPreCall(ret: any, param: string, req: Request, res: Response) {
if (param === 'ignore') {
return {
err: "ignore",
data: null
}
}
return ret
}
上述preCall函数中的参数ret，是上一个调用的返回值，Auth.preCall的返回值也会传给下一个调用。如果没有return，会使用之前在调用链上传递的ret传给下一个调用
如果注解调用中发生了错误，有两种错误抛出方式：
* 如果需要继续执行调用链：在返回值中设置err属性，该属性可以是字符串，也可以是对象，只要不为null，就表明错误发生。这意味着你可以定义自己的错误结构，方便后面的错误捕获和处理。
* 如果需要中断调用链：直接在preCall或者postCall中return null，当检测到调用链中某一个调用的返回值是null时，不会继续执行调用链。注意：这时框架不会响应请求，如果你希望中断调用链，那么你必须使用函数参数中的Request和Response自定义HTTP响应，如设置状态码，设置响应头，设置响应体。例如，在Auth中如果验证失败，你可能会返回401状态码
如果路由函数中要抛出错误，需要throw BusinessException，BusinessException位于jbean包中。例如：
`typescript
@Get('/process/{uid0}')
@Auth
@ResponseBody('json')
@Validation(UserEntity)
@Transactional
public async process (req: Request, res: Response, { uid0 }) {
const user: UserEntity = req.entity
let u = await this.userService.hello(user)
throw new BusinessException('test Exception') // 在路由函数中抛出错误
let data = {
a: 1,
b: [2, 3, 4],
uid: uid0,
u: u
}
return data
}
`
如果是设置err的错误抛出方式，自定义的注解需要自行定义错误处理方式。通过参数中的上一个函数的返回值中的err属性，可以监听到前面的调用链中是否发生了错误。发生与未发生错误时如何处理完全由注解自行决定。如果调用链上的错误始终未被处理，则服务器会返回500错误
关于自定义注解的编写请参阅: 1.3 如何编写自定义注解？
注意：jweb提供的内置注解，比如Validation，如果检测到错误，会直接return ret
如果中断调用链，必须自行处理响应。
先看一个自定义注解的例子：
`typescript
import { AnnotationType, annotationHelper, BeanFactory } from 'jbean'
import { Request, Response } from 'jweb'
import { jsonEncode, xmlEncode } from '../../lib/utils'
export default function ResponseBody (component?: any, type?: any) {
return annotationHelper(arguments, callback)
}
const callback = function (annoType: AnnotationType, ctor: object | Function) {
if (annoType === AnnotationType.clz) {
BeanFactory.addBeanMeta(AnnotationType.clz, ctor, null, ResponseBody, [arguments[2]])
} else if (annoType === AnnotationType.method) {
BeanFactory.addBeanMeta(AnnotationType.method, ctor, arguments[2], ResponseBody, [arguments[4]])
}
}
ResponseBody.preCall = function rbdPreCall(ret: any, type: string, req: Request, res: Response) {
switch (type) {
case 'json':
res.type('application/json')
break
case 'xml':
res.type('application/xml')
break
default:
break
}
console.log("response body precall", ret)
return ret
}
ResponseBody.postCall = function rbdPostCall(ret: any, type: string, req: Request, res: Response) {
console.log("jsonbody line 31", ret)
switch (type) {
case 'json':
if (typeof ret === 'object') {
ret.data = jsonEncode(ret.data)
}
break
case 'xml':
ret.data = xmlEncode(ret.data)
break
default:
break
}
return ret
}
`
上述代码定义了一个名为ResponseBody的注解，该注解的主要功能是，根据@ResponseBody('{type}')来决定返回的数据格式类型，type可选值是json或者xml。接下来我们讨论该注解的详细定义过程。
* 首先，注解相关的处理都在jbean包中，这里我们从JBean中引入了AnnotationType、annotationHelper、BeanFactory。其中：
* AnnotationType：用于定义注解的类型，jweb中支持的注解类型有三种，类、方法、域。分别对应AnnotationType.clz，AnnotationType.method，AnnotationType.field
* annotationHelper：jbean提供的分析注解参数的函数，该函数接收两个参数，args和callback，args是参数；callback是回调函数，在annotationHelper执行完毕后调用。annotationHelper会根据args参数计算出注解类型，以及能够从typescript注解获取对应的构造函数/原型对象、键名、descriptor对象等，细节请参阅typescript注解。拿到这些数据后，annotationHelper会将其作为参数传入给callback。callback的详细参数列表请参阅callback参数列表
annotationHelper统一处理TypeScript装饰器工厂和装饰器直接使用，比如Auth('ignore')和@Auth分别对应工厂调用和直接调用
* BeanFactory：管理Bean、BeanMeta等信息的工厂类。如果我们希望我们定义的注解的preCall和postCall在请求到来时调用，需要将对应的BeanMeta注册到BeanFactory中
##### 1. 导入依赖：
`js`
import { AnnotationType, annotationHelper, BeanFactory } from 'jbean'
import { Request, Response } from 'jweb'
import { jsonEncode, xmlEncode } from '../../lib/utils'
注意：jsonEncode，xmlEncode是自行编写格式处理工具，与jweb和jbean无关。
##### 2. 定义注解：
`typescript`
export default function ResponseBody (component?: any, type?: any) {
return annotationHelper(arguments, callback)
}
其中ResponseBody是我们定义的注解名，当作为工厂调用时，即以@ResponseBody('参数1', '参数2')形式调用时，ResponseBody函数的参数就是工厂调用时传入的参数。否则其参数是typescript装饰器传入的参数。
我们使用时，可直接传arguments，annotationHelper会帮助我们处理所有细节，并将统一的参数形式传到callback中。接下来我们详细解释callback的使用。
##### 3. 定义callback方法：
`typescript`
const callback = function (annoType: AnnotationType, ctor: object | Function) {
if (annoType === AnnotationType.clz) {
BeanFactory.addBeanMeta(AnnotationType.clz, ctor, null, ResponseBody, [arguments[2]])
} else if (annoType === AnnotationType.method) {
BeanFactory.addBeanMeta(AnnotationType.method, ctor, arguments[2], ResponseBody, [arguments[4]])
}
}
###### callback参数列表
`js`
const callback = function(annoType: AnnotationType, ctor: Function|object, field: string, descriptor: PropertyDescriptor, ...args)
参数说明：
* annoType：注解的类型，取值为AnnotationType.clz，AnnotationType.method，AnnotationType.field，分别代表类，方法，域
* ctor：构造函数或者原型对象
* field：如果被注解的是方法或者域，则该值存在且为键名
* descriptor：如果被注解的是方法，则该值存在且为该方法对应的描述符对象
* ...args：注解工厂调用时传入的参数，例如@ResponseBody('json')中传入的‘json'
注意，如果你希望你的注解在被注解的函数调用时调用，请确保将其添加到BeanFactory的BeanMeta中，并定义响应的preCall、postCall函数。因为callback仅会在初始化时调用。
注册BeanMeta请参考下面的代码：
`typescript`
BeanFactory.addBeanMeta(AnnotationType.method, ctor, arguments[2], ResponseBody, [arguments[4]])
##### 4. 定义preCall、postCall函数
preCall可以在路由函数被调用前调用，可以起到拦截作用，如果你的业务中需要拦截器功能的话，定义preCall就可以实现。postCall在路由函数被调用后调用，可以对数据进行加工。preCall、postCall的使用、参数请参考上述示例。
一个完整的Controller示例代码如下：
`typescript
import { Autowired } from 'jbean'
import { BaseController, Controller, Get, Post, Request, Response, Transactional, Validation } from 'jweb'
import UserService from '../lib/account/UserService'
import PayService from '../lib/account/PayService'
import Auth from '../annos/Auth'
import ResponseBody from '../annos/response_body'
import UserEntity from '../lib/account/entity/user'
@Controller('/user')
@Transactional
export default class User extends BaseController {
@Autowired('userService0')
private userService: UserService
@Autowired
private payService: PayService
constructor () {
super()
}
private beforeCall (ret) {
return ret
}
public afterCall (ret) {
console.log('afterCall', ret)
if (ret.err) {
return {
status: -1,
err: ret.err
}
} else {
return ret.data
}
}
@Get('/process/{uid0}')
@Auth
@ResponseBody('json')
@Validation(UserEntity)
@Transactional
public async process (req: Request, res: Response, { uid0 }) {
const user: UserEntity = req.entity
console.log('inside call', user)
let u = await this.userService.hello(user)
let data = {
a: 1,
b: [2, 3, 4],
uid: uid0,
u: u
}
return data
}
}
`
这里我们只关注和process方法有关的部分，Get('/process/{uid0}')注册了一个动态路由，其路由参数是uid0。然后会一次依据1.1 注解的调用顺序调用注解和方法。注意，注解调用链的参数传递与process方法无关，process方法只关注自身的业务处理，所以这里没有返回{err,data,from}这种结构，也不会被传入ret，process方法直接返回data
在这个示例中，我们将错误的统一拦截放到了afterCall中：
`typescript`
public afterCall (ret) {
console.log('afterCall', ret)
if (ret.err) {
return {
status: -1,
errmessage: ret.err
}
} else {
return {
status: 1
data: ret.data
}
}
}
我们获取前面传过来的ret，判断是否发生了错误，如果发生了错误，将业务定义的错误码以及错误信息返回。
如果成功，将成功码和获取到的数据返回。
user.ts
`typescript
import { Entity, Type } from 'jweb'
import {Required, Min, Max, Size} from 'jweb'
@Entity
export default class User {
@Type('string')
@Required("uid是必填的参数")
public uid = undefined
@Required
@Size(20, 30, 'name的长度应该位于20-30之间')
public name = undefined
@Type('number', true)
@Required("age is required")
@Min(18)
@Max(100)
public age = undefined
}
`
代码中定义了一个User类，类上有@Entity注解，@Entity表明这是一个实体类，与某一张数据库表相对应，会自动根据类名生成表名，如上例中，对应user表。默认的表名规则是下划线分割驼峰式命名，例如：PersonLikeBeer会对应表person_like_beer。
可以通过给@Entity传参数可以自定义表名，例如：@Entity('user_log')表名当前的类对应user_log表。
注意到每一个字段都给了一个默认值undefined，这是因为如果不给默认值，typescript编译后不会生成对应的属性
可以通过给表中的字段添加验证注解，来进行参数的校验，在上例中：
`typescript`
@Type('number', true)
@Required("age is required")
@Min(18)
@Max(100)
public age = undefined
* @Type('number', true) 表明这个字段必须是数字，true表示运行进行转换以期望得到正确的类型。注意，一般情况下请将其设置成true，因为获取到的参数默认都是字符串，例如：可能表单提交的是21，但是获取的参数会是'21'，这时候会导致验证不通过。但如果你不想其他类型转为字符串，可以不写或者传false。
* @Required("age is required")表明这个字段是必须的，括号里面的是验证不正确时的提示信息，如果不给定，会使用默认的提示信息
* @Min(18)最小值18
* @Max(100)最大值100
注解会按照使用顺序，从上到下调用，如果一个字段有多个验证规则，中间有一个规则不通过时，不会继续验证后面的规则，直接使用该注解的错误信息。
每一个注解验证后会返回一个值，这个值会传给下一个验证注解，最后的验证注解返回的值会赋值给对应的字段。
所有注解的最后一个参数都是验证出错时提供的消息，如果没有提供该参数，将会使用默认值。
使用：@Min(minval:number，mes?: string)
规则：对应字段的值是否比@Min指定的值大
使用：@Max(minval:number，mes?: string)
规则：对应字段的值是否比@Max指定的值小
使用：@Size(minval:number，maxval?:number, mes?: string)
规则：对应字段的值是否在指定的区间中
使用：@Requred(mes?: string)
规则：必须的字段
使用：@Type(type?: string)
规则：字段的数据类型，可选值string、number、integer
`typescript
import { AnnotationType, annotationHelper, BeanFactory } from 'jbean'
export default function Max(maxVal: number, mes?: string) {
return annotationHelper([maxVal, mes], callback)
}
function validate(maxVal: number) {
return (val):{valid: boolean, val: any} => {
if (val <= maxVal) {
return {valid: true, val: val}
} else {
return { valid: false, val: null}
}
}
}
function message(field: string, maxVal:number, mes?: string) {
if (mes) {
return () => mes
} else {
return () => the value of ${field} must smaller than ${maxVal}
}
}
Max['validate'] = {}
const callback = function(annoType: AnnotationType, ctor: Function, field: string, maxVal:number, mes?: string) {
// add descriptor info into BeanFactory, using it in Validation
Max['validate'][field] = {
validate: validate(maxVal),
message: message(field, maxVal, mes)
}
BeanFactory.addBeanMeta(annoType, ctor, field, Max)
}
每一个验证器需要两个方法，一个是validate，用于验证是否满足规则，另一个是message，用于返回验证失败时的消息。请确保传给Max\['validate'\]\[field\]的validate和message属性的值均是函数。validate和message返回的函数都会被传入一个参数——被验证的字段的值
我们将这两个方法与挂在到对应注解方法的validate属性上，在示例中是Max['validate']，然后:
`typescript`
Max['validate'][field] = {
validate: validate(maxVal),
message: message(field, maxVal, mes)
}
使用field是因为不同的域上可能有相同的注解，而验证规则可能是闭包相关的，所以这里为每一个域都绑定validate和message方法。
最后需要把注解注册到BeanFactory中，采用让其validate和message函数在验证时被调用。
1. 确保验证器函数有如下属性，且validate和message必须是函数。
`typescript`
Max['validate'][field] = {
validate: validate(maxVal),
message: message(field, maxVal, mes)
}
2. 在{ validate: validate(maxVal), message: message(field, maxVal, mes) }中，validate返回值的结构必须是下面的形式：
`typescript`
{
valid: boolean, // 表示验证是否成功，如果成功，其值为true，否则为false
val: any // 验证之后应该返回的值，这个值会传给下一个验证器
}
val的值会传给下一个验证器，最后一个验证器的val值会赋值给实体，注意验证成功或者失败时返回的val值
message返回值必须是一个字符串，用作验证失败时的提示信息。
3. 确保验证器被注册到BeanFactory中，调用如下API注册
`typescript``
BeanFactory.addBeanMeta(annoType, ctor, field, Max)