功能介绍
BasicRESTCmdlet主要为了化简REST接口设计实现,使用方式模仿SpringMVC,整合ucore之前AbstractRESTCmdlet的模式使用
针对之前的编程模式,主要增加如下的特点:
- REST参数通过注解注入实现,可以在注解中配置对应的字段名、数据来源(Header或者RequestParam)、验证参数等。
- 自动输出参数日志、参数验证错误日志等。
- 返回值可以用之前的AbstractRESTResult,也可以直接返回一个对象,系统自动封装JSONRESTResult对象。
使用范例
基本使用模式如下:
03 | @RESTAnnotate (URL = "/dev/test" , Methods = HttpMethod.GET) |
04 | public class BasicRestTestHandler extends BasicRESTCmdlet { |
06 | private static transient Logger logger = LoggerFactory.getLogger(BasicRestTestHandler. class ); |
10 | public Student doTestRequest( |
11 | @StringParam (value = "name" , required = false , validated = true , maxLength = 2 ) |
13 | @IntParam (value = "age" , source = RequestSource.RequestParam,required = false , min = 0 , max = 25 ) |
15 | @TypedParam (value = "student" , required = false , type = Student. class ) |
17 | @DateParam (value = "start" ) |
22 | HashMap myMap = new HashMap(); |
23 | myMap.put( "name" , name); |
24 | myMap.put( "age" , age); |
27 | logger.info( "----> Student is empty" ); |
31 | logger.info( "----> Student.name: {}, Student.age: {}" , student.getName(), |
使用方法与约定
- 将REST实现类继承自BasicRESTCmdlet,增加RESTAnnotate、Controller等基本注解
- 任意实现一个方法,增加REST API注解(在一个类中目前只支持一个RESTAPI注解)
- 方法的参数中,增加IntParam、StringParam、TypedParam等注解,并配置基本参数
注解使用说明
IntParam
注解声明
01 | @Target ({ElementType.PARAMETER}) |
03 | @Retention (RetentionPolicy.RUNTIME) |
04 | public @interface IntParam { |
06 | RequestSource source() default RequestSource.HeaderParam; |
07 | RequestParamType paramType() default RequestParamType.Integer; |
08 | boolean required() default true ; |
09 | boolean validated() default false ; |
10 | int min() default Integer.MIN_VALUE; |
11 | int max() default Integer.MAX_VALUE; |
常用配置参数说明
value: 绑定到REST请求中的参数名
ResourceSource:选择参数取值的来源,默认为Header,可以配置成RequestParameter
required:配置是否为必选参数。如果为false,并且该参数没有传值,则默认为0
validated:配置是否验证,必须在required为true才能生效。当前验证规则只有一个:最大值和最小值之间的范围,在min和max中配置。
StringParam
注解声明
02 | @Target ({ElementType.PARAMETER}) |
04 | @Retention (RetentionPolicy.RUNTIME) |
05 | public @interface StringParam { |
07 | RequestSource source() default RequestSource.HeaderParam; |
08 | RequestParamType paramType() default RequestParamType.String; |
09 | boolean required() default true ; |
10 | boolean validated() default false ; |
11 | int maxLength() default Integer.MAX_VALUE; |
常用配置参数说明
value: 绑定到REST请求中的参数名
ResourceSource:选择参数取值的来源,默认为Header,可以配置成HeaderParam、RequestParam
required:配置是否为必选参数。如果为false,并且该参数没有传值,则默认为空字符串。
validated:配置是否验证,必须在required为true才能生效。当前验证规则只有一个:字符串的最大长度
TypedParam
注解声明
@Target({ElementType.PARAMETER})
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface TypedParam {
String value();
RequestSource source() default RequestSource.RequestParam;
RequestParamType paramType() default RequestParamType.Object;
boolean required() default true;
boolean validated() default false;
Class type() default Object.class;
}
常用配置参数说明
value: 绑定到REST请求中的参数名
ResourceSource:选择参数取值的来源,默认为RequestParameter,即主要通过Post传输。
required:配置是否为必选参数。如果为false,并且该参数没有传值,则改参数默认为空。
validated:目前暂无效。
type:配置要转换的目标对象的类型。
DateParam
作用
绑定并转换DateTime,来源为Long的数字类型或者日期类型字符串
注解声明
@Target({ElementType.PARAMETER})
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface DateParam {
String value();
RequestSource source() default RequestSource.HeaderParam;
RequestParamType paramType() default RequestParamType.Date;
boolean required() default true;
boolean validated() default false;
RequestDateFormat format() default RequestDateFormat.LongFormat;
}
常用配置参数说明
value: 绑定到REST请求中的参数名
ResourceSource:选择参数取值的来源,默认为Header,可以配置成RequestParameter
required:配置是否为必选参数。如果为false,并且该参数没有传值,则改参数默认为空。
validated:目前暂无效。
format: 用于参数转换的带格式化字符串类型,可以配置为LongFormat或者StringFormat