RESTful Web Services -- JAX-RS中的注解

RESTful Web Services -- JAX-RS中的注解

1）javax.ws.rs包下的注解：

javax.ws.rs.GET、javax.ws.rs.Post、javax.ws.rs.Consumes、javax.ws.rs.Produces、javax.ws.rs.Path

	[@GET](https://my.oschina.net/get)	表示(被@GET注解修饰的)方法将处理(响应)来自HTTP的GET请求
	[@POST](https://my.oschina.net/u/210428)
	[@PUT](https://my.oschina.net/u/3692237)
	[@DELETE](https://my.oschina.net/u/160154)
	@HEAD

	@Consumes：表示一个资源类或方法可以接受的MIME类型。
		说明：MIME类型可以有多个。
		举例：@Consumes({MediaType.MULTIPART_FORM_DATA, MediaType.APPLICATION_OCTET_STREAM, MediaType.TEXT_PLAIN})
		注意：MediaType的类型为javax.ws.rs.core.MediaType
		
	@Produces：表示一个资源类或方法可以返回的MIME类型。
		说明：可以同时返回多种类型，但具体生成结果时使用哪种格式取决于ContentType。CXF默认返回的是JSON字符串。

	@Path：用来标注资源类或方法的相对路径
		说明：value值可以包含文本字符、变量或具有定制正则表达式的变量。
		举例：@Path("/helloworld/{username}") 
		
javax.ws.rs.PathParam、javax.ws.rs.QueryParam、javax.ws.rs.FormParam、javax.ws.rs.BeanParam、javax.ws.rs.core.Context
		
	@PathParam：标注方法的参数来自于请求的URL路径，参数的名称和@Path注解中定义的变量名对应
		举例：
			接口URL：/helloworld/xiaoning
			
			@POST
			@Path("/helloworld/{username}")
			public String hello((@PathParam("username")String username);
	
	@QueryParam：标注方法的参数来自于请求的URL的查询参数，即用来获取URL中的查询参数。
		举例：
			接口URL：/downloadExcel?fileId=77&username=xiaoning
			
			@GET
			@Path("/downloadExcel")
			@Consumes({"application/octet-stream"})
			@Produces("application/vnd.ms-excel")
			public Response downloadExcel(@QueryParam("fileId")Integer fileId ,@QueryParam("username")String username);
	
	@FormParam：用来获取POST请求中的表单参数，请求的MIME类型为"application/x-www-form-urlencoded"
		举例：
			接口URL：/getAccountInfo
			
			@POST
			@Path("/getAccountInfo")
			@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
			@Produces(MediaType.APPLICATION_JSON)
			public String getAccountInfo((@FormParam("username")String username);
	
	@BeanParam：自定义参数组合，BeanParam使得REST方法可以使用简洁的参数形式完成复杂的接口设计。
		说明：
			1>@BeanParam注解修饰的类是用来封装请求中的多个参数
			2>通过在@BeanParam注解修饰的类的属性上添加@FormParam、@QueryParam、@PathParam等注解来获取请求参数的值
		举例：
			接口URL：/getUserInfo

			@POST
			@Path("/getUserInfo")
			@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
			@Produces(MediaType.APPLICATION_JSON)
			public String getUserInfo(@BeanParam ReqGetUserInfoDTO req); 

			public class ReqGetAccountInfoByIdDTO {
				@FormParam("username")
				private String username;
				
				@FormParam("password")
				private String password;
			}

	@Context：用来获取上下文参数
		举例：
			接口URL：/uploadFile
		
			import javax.servlet.http.HttpServletRequest;
			import javax.ws.rs.core.UriInfo;
			import javax.ws.rs.core.HttpHeaders;
			
			@POST
			@Path("/uploadFile")
			@Consumes({MediaType.MULTIPART_FORM_DATA, MediaType.APPLICATION_OCTET_STREAM, MediaType.TEXT_PLAIN})
			@Produces(MediaType.APPLICATION_JSON)
			public String uploadFile(@Context final HttpServletRequest servletRequest, @Context final UriInfo uriInfo, @Context final HttpHeaders httpHeaders);
					
					
			接口URL：/exportPlanData 
			
			@GET
			@Path("/exportPlanData")
			public Response exportPlanData(@BeanParam ReqGetPlanRtDataDTO reqGetPlanRtDataDTO, @Context HttpServletResponse response);
			
			// 实现以流的方式导出数据：
			//	SXSSFWorkbook wb = new SXSSFWorkbook();
			//  SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd");
			//  String fileName = format.format(new Date()) + "_计划报表.xlsx";
			//  ServletOutputStream outputStream = response.getOutputStream();
			//  wb.write(outputStream);
			//  response.setHeader("content-disposition", "attachment;filename=" + URLEncoder.encode(fileName, "UTF-8"));
			//  response.setContentType("application/vnd.ms-excel");
			//  outputStream.close();
			//  return Response.status(Response.Status.OK).entity(null).build();

			
			
	@HeaderParam：用来获取HTTP请求的头信息
	
	@CookieParam：用来获取HTTP请求的Cookie信息

	@MatrixParam：用来从路径段中获取参数信息

	@PathVariable：是用来获得请求url中的动态参数

说明：多个注解同时存在时，按照优先级来确定从哪里获取参数的值。	


例子：

	前端REST接口测试request：
		company		"google"
		userList	{name:"jack",age:17}
		userList	{name:"jack2",age:18}
		userList	{name:"jack3",age:19}

		
	后端接口：
		@POST
		@Path("/getUserInfo")
		public Result getUserInfo(@BeanParam UserInfo req);
		

		import java.util.List;
		import javax.ws.rs.FormParam;
		
		public class UserInfo {

			@FormParam("company")
			private String company;

			@FormParam("userList")
			private List<User> userList;

			// setter and getter
		}

		public class User {

			private String name;
			private Long age;
			
			public User() {
			}
			
			/**
			 * 需要一个构造方法来实现json串到javaBean的转换，该构造方法的参数是一个字符串。
			 * @param paramStr
			 */
			public User(String paramStr) {
				// 将json串转换为javaBean
				JSONObject jsonObject = JSONObject.fromObject(paramStr);
				this.name = jsonObject.getString("name");
				this.age = Long.parseLong(jsonObject.getString("age"));
			}
			// setter and getter
		}

2）CFX中的注解：

org.apache.cxf.jaxrs.ext.multipart.Multipart

	@Multipart：Annotate a JAX-RS function parameter to receive data from a multipart 'part'
	说明：
		import org.apache.cxf.jaxrs.ext.multipart.Attachment;
		
		@Consumes(MediaType.MULTIPART_FORM_DATA)
		public String uploadExcel(@Multipart(value="file")Attachment uploadFile, @Multipart(value="userId")Integer userId);