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);