SpringBoot RestFul風格API接口開發

時間 2019-11-17

標籤 springboot restful 風格 api 接口開發欄目 Spring 简体版

原文原文鏈接

本文介紹在使用springBoot如何進行Restful Api接口的開發及相關注解已經參數傳遞如何處理。前端

1、概念：

　　REST全稱是Representational State Transfer，中文意思是表述（編者注：一般譯爲表徵）性狀態轉移。它首次出如今2000年Roy Fielding的博士論文中，Roy Fielding是HTTP規範的主要編寫者之一。他在論文中提到："我這篇文章的寫做目的，就是想在符合架構原理的前提下，理解和評估以網絡爲基礎的應用軟件的架構設計，獲得一個功能強、性能好、適宜通訊的架構。REST指的是一組架構約束條件和原則。" 若是一個架構符合REST的約束條件和原則，咱們就稱它爲RESTful架構。
　　REST自己並無創造新的技術、組件或服務，而隱藏在RESTful背後的理念就是使用Web的現有特徵和能力，更好地使用現有Web標準中的一些準則和約束。雖然REST自己受Web技術的影響很深，可是理論上REST架構風格並非綁定在HTTP上，只不過目前HTTP是惟一與REST相關的實例。因此咱們這裏描述的REST也是經過HTTP實現的REST。spring

2、註解說明：

1.Rest控制器json

@RestController註釋用於定義RESTful Web服務。它提供JSON，XML和自定義響應。其語法以下所示 api

@RestController
public class UserRestController{


}

有了該註解，在響應返回的是json格式的數據，咱們就不要寫@ResponseBody註解了安全

2.Java請求映射服務器

@RequestMapping註釋用於定義訪問REST端點的Request URI。能夠定義Request方法來使用和生成對象。默認請求方法是:GET。restful

@RequestMapping(value = "/products")
public List<ApiUser> getAllUsers(){

}

該註解還能夠有幾個屬性：method制定請求容許的request方法，produces返回的數據類型，例如如下寫法：網絡

@RequestMapping(value = "/user/roleCode/{roleCode}", method = RequestMethod.GET,produces=MediaType.APPLICATION_JSON_UTF8_VALUE)

固然咱們也能夠在全局類前指定返回的數據類型。例如：架構

@RestController
@RequestMapping(value = "/rest", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public class UserRestController{
        ....
}

3.Java請求主體app

@RequestBody註釋用於定義請求正文內容類型。

public List<ApiUser> getUserListByApiUser(@RequestBody ApiUser apiUser) {

}

4.Java路徑變量

@PathVariable批註用於定義自定義或動態請求URI。請求URI中的Path變量定義爲花括號{}，以下所示

public List<ApiUser> getUserByRoleCode(@PathVariable("roleCode") String roleCode){


}

5.Java請求參數

@RequestParam註釋用於從請求URL讀取請求參數。默認狀況下，它是必需參數。還能夠爲請求參數設置默認值，以下所示 -

public List<ApiUser> getUserByUserName(@RequestParam(value = "userName", required = false, defaultValue = "system") String userName) {


}

6.@RequestParam與@PathVariable的區別

在spring MVC中，二者的做用都是將request裏的參數的值綁定到contorl裏的方法參數裏的，區別在於，URL寫法不一樣。

使用@RequestParam時，URL是這樣的：http://host:port/path?參數名=參數值

使用@PathVariable時，URL是這樣的：http://host:port/path/參數值

例如

3、RestFul風格提交：

　　RESTful架構應該遵循統一接口原則，統一接口包含了一組受限的預約義的操做，不論什麼樣的資源，都是經過使用相同的接口進行資源的訪問。接口應該使用標準的HTTP方法如GET，PUT和POST，並遵循這些方法的語義。若是按照HTTP方法的語義來暴露資源，那麼接口將會擁有安全性和冪等性的特性，例如GET和HEAD請求都是安全的，不管請求多少次，都不會改變服務器狀態。而GET、HEAD、PUT和DELETE請求都是冪等的，不管對資源操做多少次，結果老是同樣的，後面的請求並不會產生比第一次更多的影響。

　　本文主要介紹，POST、PUT、DELETE、GET四種風格的restful請求。@RequestMapping(value="/") method 不寫的話，默認GET、POST都支持，根據前端方式自動適應。

3.1 GET主要用於資源的獲取

例如：好比根據用戶編碼獲取用戶。咱們就可使用Get，傳單個參數，根據參數去查詢用戶

@RequestMapping(value = "/user/userCode/{userCode}", method = RequestMethod.GET)
    public ApiUser getUserByUserCode(@PathVariable("userCode") String userCode) {
        AfaUser user = userService.getAfaUserByUserCode(userCode);
        ApiUser apiUser=BeanUtils.copyBean(user,ApiUser.class);    
        if(user!=null){
            List<OrgBean> orgs=this.getOrgParentListByOrgId(user.getMainOrgid());
            apiUser.setOrgs(orgs);
        }
        return apiUser;
    }

有人就問了，那要是我有多個參數，GET我怎麼操做了：

方法一：換成POST請求，將全部參數封裝成一個類，而後使用 @RequestBody註解將參數自動解析成該類的一個實例

@ApiOperation(value = "根據用戶對象獲取用戶列表")
    @RequestMapping(value = "/users", method = RequestMethod.POST)
    public List<ApiUser> getUserListByApiUser(@RequestBody ApiUser apiUser) {
        AfaUser afaUser = BeanUtils.copyBean(apiUser, AfaUser.class);
        List<ApiUser> apiUserList=BeanUtils.copyList(userService.getAfaUserList(afaUser), ApiUser.class);
        for(ApiUser _user:apiUserList){        
            if(StringUtils.isNotNullAndBlank(_user.getMainOrgid())){
                List<OrgBean> orgs=this.getOrgParentListByOrgId(_user.getMainOrgid());
                _user.setOrgs(orgs);    
            }
        }
        return apiUserList;
    }

有人說那你這樣就不符合規範了，不過，這個「規範」只是建議你們這麼來遵照，並非強制要求

方法二：仍是使用GET請求，可是將全部請求參數經過JSON格式來傳遞，controller拿到參數後，使用 JSON 相關的庫（如 gson），將該JSON轉化爲相應的對象

public List<String> getName(@RequestParam String queryDtoStr) {
        QueryDto queryDto = new Gson().fromJson(queryDtoStr, QueryDto .class);
        // ....
        return new ArrayList<>();
}

這樣請求的就要像這樣：

http://localhost:8080/app/names?queryDtoStr={"query1":12,"query2":2,"query3":2}

3.2 POST主要用於建立資源

HTTP POST請求用於建立資源。此方法包含請求正文。能夠發送請求參數和路徑變量來定義自定義或動態URL。例如：

@RequestMapping(value="/user", method = RequestMethod.POST)
    public void doInsert(@RequestBody ApiUser apiUser) {
        AfaUser user = BeanUtils.copyBean(apiUser, AfaUser.class);
        userService.addAfaUser(user);
    }

3.3 PUT主要用於更新資源

HTTP PUT請求用於更新現有資源，此方法包含請求正文。能夠發送請求參數和路徑變量來自定義或動態URL。例如：

    @RequestMapping(value = "/user", method = RequestMethod.PUT)
    public void doUpdate(@RequestBody ApiUser apiUser) {
        AfaUser user = BeanUtils.copyBean(apiUser, AfaUser.class);
        userService.updateAfaUser(user);
    }

3.4 DELETE主要用於刪除資源

HTTP DELETE請求用於刪除現有資源，此方法包含請求正文。能夠發送請求參數和路徑變量來自定義或動態URL。例如：

    @ApiOperation(value = "刪除用戶")
    @RequestMapping(value = "/user", method = RequestMethod.DELETE)
    public void doDelelte(@RequestBody ApiUser apiUser) {
        AfaUser user = BeanUtils.copyBean(apiUser, AfaUser.class);
        userService.delAfaUser(user);
    }

以上方法參數是接收一個對象，若是是單個屬性，能夠直接跟在url後面。

完整示例:

/**
 * 
 * @author Shaw
 *
 */
@RestController
@RequestMapping(value = "/rest", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@Api(value = "/rest", tags = "UserRestController", description = "用戶管理接口")
public class UserRestController{

    @Resource
    private AfaUserService userService;
    
    @Resource
    private AfaRoleService afaRoleService;
    
    @Resource
    private AfaOrgService orgService;
    
    @Resource
    private MenuHelper menuHelper;
    
    @Resource
    private AfaOrgService afaOrgService;
    
    @Resource
    private AfaAuthPartyService afaAuthPartyService;
    
    @ApiOperation(value = "新增用戶")
    @RequestMapping(value="/user", method = RequestMethod.POST)
    public void doInsert(@RequestBody ApiUser apiUser) {
        AfaUser user = BeanUtils.copyBean(apiUser, AfaUser.class);
        userService.addAfaUser(user);
    }    

    @ApiOperation(value = "更新用戶")
    @RequestMapping(value = "/user", method = RequestMethod.PUT)
    public void doUpdate(@RequestBody ApiUser apiUser) {
        AfaUser user = BeanUtils.copyBean(apiUser, AfaUser.class);
        userService.updateAfaUser(user);
    }

    @ApiOperation(value = "刪除用戶")
    @RequestMapping(value = "/user", method = RequestMethod.DELETE)
    public void doDelelte(@RequestBody ApiUser apiUser) {
        AfaUser user = BeanUtils.copyBean(apiUser, AfaUser.class);
        userService.delAfaUser(user);
    }    

    @ApiOperation(value = "修改密碼")
    @RequestMapping(value = "/user/password", method = RequestMethod.PUT)
    public void resetUserPassWord(@RequestBody ApiUser apiUser) {
        AfaUser afaUser = BeanUtils.copyBean(apiUser, AfaUser.class);
        userService.resetUserPassWord(afaUser);        
    }    

    @ApiOperation(value = "根據用戶編碼獲取用戶")
    @RequestMapping(value = "/user/userCode/{userCode}", method = RequestMethod.GET)
    public ApiUser getUserByUserCode(@PathVariable("userCode") String userCode) {
        AfaUser user = userService.getAfaUserByUserCode(userCode);
        ApiUser apiUser=BeanUtils.copyBean(user,ApiUser.class);    
        if(user!=null){
            List<OrgBean> orgs=this.getOrgParentListByOrgId(user.getMainOrgid());
            apiUser.setOrgs(orgs);
        }
        return apiUser;
    }    

    @ApiOperation(value = "根據用戶id獲取用戶")
    @RequestMapping(value = "/user/userId/{userId}", method = RequestMethod.GET)
    public ApiUser getUserByUserId(@PathVariable("userId") String userId) {
        if(StringUtils.isNotNullAndBlank(userId)){
            AfaUser user = userService.getAfaUserByUserId(userId);
            ApiUser apiUser=BeanUtils.copyBean(user,ApiUser.class);    
            if(user!=null){
                List<OrgBean> orgs=this.getOrgParentListByOrgId(user.getMainOrgid());
                apiUser.setOrgs(orgs);
            }
            return apiUser;
        }
        return null;
    }

    @ApiOperation(value = "根據角色編碼獲取用戶")
    @RequestMapping(value = "/user/roleCode/{roleCode}", method = RequestMethod.GET)
    public List<ApiUser> getUserByRoleCode(@PathVariable("roleCode") String roleCode) {
        List<AfaUser> user =  userService.getUserByRoleCode(roleCode);
        return BeanUtils.copyList(user, ApiUser.class);
    }

    @ApiOperation(value = "獲取全部用戶")
    @RequestMapping(value = "/users", method = RequestMethod.GET)
    public List<ApiUser> getAllUserList() {
        return BeanUtils.copyList(userService.getAfaUserList(),ApiUser.class);
    }

    @ApiOperation(value = "根據用戶對象獲取用戶列表")
    @RequestMapping(value = "/users", method = RequestMethod.POST)
    public List<ApiUser> getUserListByApiUser(@RequestBody ApiUser apiUser) {
        AfaUser afaUser = BeanUtils.copyBean(apiUser, AfaUser.class);
        List<ApiUser> apiUserList=BeanUtils.copyList(userService.getAfaUserList(afaUser), ApiUser.class);
        for(ApiUser _user:apiUserList){        
            if(StringUtils.isNotNullAndBlank(_user.getMainOrgid())){
                List<OrgBean> orgs=this.getOrgParentListByOrgId(_user.getMainOrgid());
                _user.setOrgs(orgs);    
            }
        }
        return apiUserList;
    }    

    @ApiOperation(value = "根據角色編碼獲取角色")
    @RequestMapping(value = "/users/roleCodes", method = RequestMethod.POST)
    public List<ApiUser> getUserByRoleCodes(@RequestBody List<String> roleList) {
        return BeanUtils.copyList(userService.getUserByRoleCodes(roleList),ApiUser.class);
    }
    
    @ApiOperation(value = "根據角色編碼獲取角色")
    @RequestMapping(value = "/users/page", method = RequestMethod.POST)
    public Page<ApiUserOrgPos> queryAfaUserPage(@RequestBody Searcher searcher,Page<ApiUserOrgPos> page) {
        Page<AfaUserOrgPos> apiUserOrgPos = BeanUtils.copyList(page, AfaUserOrgPos.class);
        return BeanUtils.copyList(userService.queryAfaUserPage(searcher, apiUserOrgPos,null), ApiUserOrgPos.class);
    }    

    @ApiOperation(value = "根據用戶對象獲取角色列表")
    @RequestMapping(value = "/role/user/", method = RequestMethod.POST)
    public List<ApiRole> getRolesByUser(@RequestBody ApiUser apiUser) {
        AfaUser afaUser = BeanUtils.copyBean(apiUser, AfaUser.class);
        String userCode=afaUser.getUserCode();
        return BeanUtils.copyList(menuHelper.findRoleByUserCode(userCode, null), ApiRole.class);
    }

    @ApiOperation(value = "根據用戶Id對象獲取角色列表")
    @RequestMapping(value = "/role/userId/{userId}", method = RequestMethod.GET)
    public List<ApiRole> getRolesByUserId(@PathVariable("userId") String userId) {
        AfaUser afaUser=userService.getAfaUserByUserId(userId);
        String userCode=afaUser.getUserCode();
        return BeanUtils.copyList(menuHelper.findRoleByUserCode(userCode, null), ApiRole.class);
    }

    @ApiOperation(value = "根據角色編碼、機構id獲取用戶列表")
    @RequestMapping(value = "/users/{roleCode}/{orgId}", method = RequestMethod.GET)
    public List<ApiUser> getUsersByRoleCodeAndOrgId(@PathVariable("roleCode") String roleCode, @PathVariable("orgId") String orgId) {
        List<AfaUser> afaUserList=new ArrayList<AfaUser>();
        //一、先獲取機構編碼
        AfaOrg afaOrg=null;
        if(StringUtils.isNotNullAndBlank(orgId)){
            afaOrg=afaOrgService.getAfaOrgByOrgId(orgId);
        }
        
        String orgCode=null;
        if(afaOrg!=null){
            orgCode=afaOrg.getOrgCode();
        }
        
        //二、根據機構編碼和角色獲取角色受權表
        List<AfaAuthParty> partyList=null;
        if(StringUtils.isNullOrBlank(roleCode)&&StringUtils.isNullOrBlank(orgId)){
            
        }else{
            partyList=afaAuthPartyService.getAfaAuthPartyByRoleCodeAndOrgCode(orgCode,roleCode);
        }
        

        //三、根據party_type類型獲取用戶。
        //當party_type爲org的時候，獲取該org下的全部用戶
        //當party_type爲user的時候，判斷該用戶的主機構是否是orgId下的
        if(partyList!=null&&partyList.size()!=0){
            for(AfaAuthParty _party:partyList){
                AfaUser afaUser=new AfaUser();
                if(StringUtils.isNotNullAndBlank(orgId)){
                    afaUser.setMainOrgid(orgId);
                }
                
                if("org".equals(_party.getPartyType())){                    
                    afaUserList.addAll(userService.getAfaUserList(afaUser));
                }
                
                if("user".equals(_party.getPartyType())){
                    afaUser.setUserCode(_party.getPartyCode());
                }
                afaUserList.addAll(userService.getAfaUserList(afaUser));
            }
        }
        if(afaUserList.size()!=0){
            for (int i = 0; i < afaUserList.size()-1; i++) {
                for (int j = afaUserList.size()-1; j > i; j--) {
                    if (afaUserList.get(j).getUserCode().equals(afaUserList.get(i).getUserCode())) {
                        afaUserList.remove(j);
                    }
                }
            }
        }

        return BeanUtils.copyList(afaUserList, ApiUser.class);
    }

    @ApiOperation(value = "更新某些機構下用戶的狀態")
    @RequestMapping(value = "/users/status", method = RequestMethod.POST)
    public void changeUserStatusByOrgIdList(@RequestBody UserRequestParam requestParamObject) {
        if(CollectionUtils.isNotEmpty(requestParamObject.getOrgIdList())){        
            userService.changeUserStatusByOrgIdList(requestParamObject.getOrgIdList(),requestParamObject.getStatus());
        }
    }

    @ApiOperation(value = "根據casn獲取用戶列表")
    @RequestMapping(value = "/users/casn/{caSn}", method = RequestMethod.GET)
    public List<ApiUser> getApiUserByCaSn(@PathVariable("caSn")String caSn) {
        List<AfaUser> afaUser=userService.getApiUserByCaSn(caSn);
        return BeanUtils.copyList(afaUser, ApiUser.class);
    } 
    
}