Best-practices-for-a-pragmatic-restful-api

先閱讀文檔：http://www.oschina.net/translate/best-practices-for-a-pragmatic-restful-api 理解restful api設計理念

我們公司的所有微服務接口都放在 "api.998jk.com/微服務名"?下

微服務內部api設計規范為：業務域/訪問級別, 與best-practices-for-a-pragmatic-restful-api的區別是加入了一級訪問級別，例如：

簡單列表接口 /chatMessage/pb GET方式，提交參數page,pageSize,total

復雜查詢接口 /chatMessage/pb/search POST方式，提交參數為json RequestBody，根據各個接口不同自行定義

查詢單條接口 /chatMessage/pb/123 GET方式，123為id

刪除單條接口 /chatMessage/pt/123 DELETE方式，123為id

更新單條接口 /chatMessage/pt/123 PUT方式，提交參數為json RequestBody，根據各個接口不同自行定義

上述示例 完整路徑為：api.998jk.com/微服務名/chatMessage/xxx

訪問級別：

? ? pb(public) 公開，對外對內沒有任何限制；

? ? pt(protected)?受保護，對外受保護，對內沒有任何限制。需要header中含有authorization 值為"Bearer token令牌"。在api gateway會獲取該token, 并且在header中設置uid 值為該令牌的用戶id。

? ? df(default) 默認，對外加密，對內沒有任何限制。繼承protected限制。并且在api gateway會對返回結果加密，客戶端需要對結果解密后使用。加密后json如下：

{"encrypted":"返回結果加密后的字符串"}

? ? pv(private) 私有的，對外無法訪問，對內沒有任何限制。繼承default限制。

?

暴露的restful服務需采用JAX-RS標準注解，無需springMVC controller 直接暴露service，需要使用swagger注解以便自動產生restful api文檔。示例如下

package?charles.sc.provider.service;import?charles.sc.provider.entity.ChatMessage; import?com.jztey.framework.mvc.Paging; import?com.jztey.framework.mvc.RestfulPagingResult; import?com.jztey.framework.mvc.RestfulResult; import?io.swagger.annotations.Api; import?io.swagger.annotations.ApiOperation; import?io.swagger.annotations.ApiParam; import?org.springframework.cloud.netflix.feign.FeignClient;import?javax.validation.Valid; import?javax.ws.rs.*; import?javax.ws.rs.core.MediaType;/***?Created?by?Charles?on?2016/8/15.*/ @FeignClient(value?=?"provider-service") @Path("/chatMessage") @Produces(MediaType.APPLICATION_JSON) @Api(tags?=?{"聊天消息接口"}) public?interface?ChatMessageService?{@Path("/pb")@GET@ApiOperation(value?=?"聊天記錄列表",?response?=?RestfulPagingResultChatMessage.class)RestfulPagingResult<ChatMessage>?findPage(@QueryParam("id")?int?page,?@QueryParam("pageSize")?int?pageSize,?@QueryParam("total")?int?total);@Path("/pt/{id:\\d+}")@GET@ApiOperation(value?=?"按id查詢聊天記錄",?response?=?RestfulResultChatMessage.class)RestfulResult<ChatMessage>?find(@PathParam("id")?Long?id);@Path("/pb/search")@POST@ApiOperation(value?=?"搜索聊天記錄",?response?=?RestfulPagingResultChatMessage.class)RestfulPagingResult<ChatMessage>?search(Paging<ChatMessage>?paging);@Path("/pt")@POST@ApiOperation(value?=?"添加聊天記錄",?response?=?RestfulResultChatMessage.class)RestfulResult<ChatMessage>?insert(@HeaderParam("uid")?Long?uid,?@ApiParam?@Valid?ChatMessage?chatMessage);@Path("/pt/{id:\\d+}")@DELETE@ApiOperation(value?=?"按id刪除聊天記錄",?response?=?RestfulResultChatMessage.class)RestfulResult<ChatMessage>?delete(@HeaderParam("uid")?Long?uid,?@PathParam("id")?Long?id);@Path("/pt/{id:\\d+}")@PUT@ApiOperation(value?=?"修改聊天記錄",?response?=?RestfulResultChatMessage.class)RestfulResult<ChatMessage>?update(@HeaderParam("uid")?Long?uid,?@PathParam("id")?Long?id,?@ApiParam?@Valid?ChatMessage?chatMessage);class?RestfulResultChatMessage?extends?RestfulResult<ChatMessage>?{}class?RestfulPagingResultChatMessage?extends?RestfulPagingResult<ChatMessage>?{} }

?

package?charles.sc.provider.service;import?charles.sc.provider.entity.ChatMessage; import?com.jztey.framework.mvc.Paging; import?com.jztey.framework.mvc.RestfulPagingResult; import?com.jztey.framework.mvc.RestfulResult; import?org.springframework.stereotype.Service;import?java.util.ArrayList; import?java.util.List;/***?Created?by?Charles?on?2016/8/16.*/ @com.alibaba.dubbo.config.annotation.Service @Service public?class?ChatMessageServiceImpl?extends?BaseService<ChatMessage>?implements?ChatMessageService?{@Overridepublic?RestfulPagingResult<ChatMessage>?findPage(int?page,?int?pageSize,?int?total)?{System.out.println("get");//?統一使用查詢接口Paging<ChatMessage>?paging?=?new?Paging<>(page,?pageSize);paging.setTotal(total);return?this.search(paging);}@Overridepublic?RestfulResult<ChatMessage>?find(Long?id)?{System.out.println("getById");return?new?RestfulResult(new?ChatMessage(id,?"fu",?"tu",?"msg",?"mi",?System.currentTimeMillis(),?System.currentTimeMillis(),?ChatMessage.STATUS_NO_PROCESS));}@Overridepublic?RestfulPagingResult<ChatMessage>?search(Paging<ChatMessage>?paging)?{System.out.println("search");List<ChatMessage>?entityList?=?new?ArrayList<>();entityList.add(new?ChatMessage(1L,?"fu",?"tu",?"msg",?"mi",?System.currentTimeMillis(),?System.currentTimeMillis(),?ChatMessage.STATUS_NO_PROCESS));entityList.add(new?ChatMessage(2L,?"fu2",?"tu2",?"msg2",?"mi2",?System.currentTimeMillis(),?System.currentTimeMillis(),?ChatMessage.STATUS_NO_PROCESS));if?(-1?==?paging.getTotal())?{????//?total沒有傳上來//?查詢totalpaging.setTotal(100);}return?new?RestfulPagingResult(entityList,?paging.getTotal());}@Overridepublic?RestfulResult<ChatMessage>?insert(Long?uid,?ChatMessage?chatMessage)?{System.out.println("insert?uid:"?+?uid);return?new?RestfulResult<>(chatMessage);}@Overridepublic?RestfulResult<ChatMessage>?delete(Long?uid,?Long?id)?{System.out.println("delete?uid:"?+?uid);return?new?RestfulResult(new?ChatMessage(id,?"fu",?"tu",?"msg",?"mi",?System.currentTimeMillis(),?System.currentTimeMillis(),?ChatMessage.STATUS_NO_PROCESS));}@Overridepublic?RestfulResult<ChatMessage>?update(Long?uid,?Long?id,?ChatMessage?chatMessage)?{System.out.println("update?uid:"?+?uid);return?new?RestfulResult<>(chatMessage);} }

完整代碼參考：http://gitlab.998jk.com/heying/spring-cloud

本文轉自yushiwh 51CTO博客，原文鏈接：http://blog.51cto.com/yushiwh/1942254，如需轉載請自行聯系原作者

總結

以上是生活随笔為你收集整理的restful-api最佳实践的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。