Web API接口設(shè)計(jì)經(jīng)驗(yàn)總結(jié)

　　1、在接口定義中確定MVC的GET或者POST方式

　　由于我們整個(gè)Web API平臺是基于MVC的基礎(chǔ)上進(jìn)行的API開發(fā)，因此整個(gè)Web API的接口，在定義的時(shí)候，一般需要顯示來聲明接口是［HttpGet］或者［HttpPost］，雖然有些接口也可以不用聲明，但是避免出現(xiàn)類似下面的錯(cuò)誤信息，顯式聲明還是有好處的。

　　請求的資源不支持 http 方法“POST

　　例如在基類定義的查找對象接口如下所示。

　　/// 《summary》

　　/// 查詢數(shù)據(jù)庫，檢查是否存在指定ID的對象

　　/// 《/summary》

　　/// 《param name=“id”》對象的ID值《/param》

　　/// 《returns》存在則返回指定的對象，否則返回Null《/returns》

　　［HttpGet］

　　public virtual T FindByID（string id， string token）

　　如果是增刪改的接口，一般需要聲明為POST方式提交數(shù)據(jù)，而且基于安全性的考慮，需要攜帶更多的參數(shù)。

　　/// 《summary》

　　/// 插入指定對象到數(shù)據(jù)庫中

　　/// 《/summary》

　　/// 《param name=“info”》指定的對象《/param》

　　/// 《returns》執(zhí)行操作是否成功。《/returns》

　　［HttpPost］

　　public virtual CommonResult Insert（T info， string token， string signature， string timestamp， string nonce， string appid）

　　2、動(dòng)態(tài)對象的接口定義

　　在一般的Web API接口里面，我們可能都會碰到很多簡單類型的參數(shù)，但是又想讓它們以POST方式提交數(shù)據(jù)，那么我們就可以有兩種方法來處理，一種是定義一個(gè)類來放置這些參數(shù)，一種是采用動(dòng)態(tài)的JObject參數(shù)，前者有很多不方便的地方，因?yàn)槲覀儾豢赡転槊總€(gè)接口參數(shù)定義多一個(gè)實(shí)體類，這樣可能會有很多難以管理的類定義。如下面是微信API的調(diào)用接口案例，我們也需要設(shè)置這樣的處理規(guī)則。

　　接口調(diào)用請求說明

　　http請求方式： POST（請使用https協(xié)議）

　　https://api.weixin.qq.com/cgi-bin/groups/update？access_token=ACCESS_TOKEN

　　POST數(shù)據(jù)格式：json

　　POST數(shù)據(jù)例子：{“group”：{“id”：108，“name”：“test2_modify2”}}

　　那么我們采用JObject是這么樣的呢，我們來看接口的定義和處理代碼。JObject是Newtonsoft.Json.Linq命名空間下的一個(gè)對象。

　　/// 《summary》

　　/// 修改用戶密碼

　　/// 《/summary》

　　/// 《param name=“param”》包含userName和userPassword的復(fù)合對象《/param》

　　/// 《param name=“token”》用戶訪問令牌《/param》

　　/// 《returns》《/returns》

　　［HttpPost］

　　public CommonResult ModifyPassword（JObject param， string token）

　　{

　　//令牌檢查，不通過則拋出異常

　　CheckResult checkResult = CheckToken（token）;

　　dynamic obj = param;

　　if （obj ！= null）

　　{

　　string userName = obj.userName;

　　string userPassword = obj.userPassword;

　　bool success = BLLFactory《User》.Instance.ModifyPassword（userName， userPassword）;

　　return new CommonResult（success）;

　　}

　　else

　　{

　　throw new MyApiException（“傳遞參數(shù)出現(xiàn)錯(cuò)誤”）;

　　}

　　}

　　其中我們把JObject對象轉(zhuǎn)換為我們所需要的對象的時(shí)候，因?yàn)槲覀儧]有定義具體的實(shí)體類，因此采用了dynamic語法，聲明這是一個(gè)動(dòng)態(tài)對象，由運(yùn)行時(shí)獲取對應(yīng)的屬性。

　　dynamic obj = param;

　　這樣我們就可以在調(diào)用的時(shí)候，動(dòng)態(tài)POST對應(yīng)的JSON對象給Web API接口，而不需要預(yù)先定義各種接口參數(shù)的類了。

　　/// 《summary》

　　/// 調(diào)用Web API接口，修改用戶密碼

　　/// 《/summary》

　　/// 《param name=“userName”》用戶名稱《/param》

　　/// 《param name=“userPassword”》修改的密碼《/param》

　　/// 《returns》如果修改成功返回true，否則返回false《/returns》

　　public bool ModifyPassword（string userName， string userPassword）

　　{

　　var action = “ModifyPassword”;

　　var postData = new

　　{

　　userName = userName，

　　userPassword = userPassword

　　}.ToJson（）;

　　string url = GetTokenUrl（action）;

　　CommonResult result = JsonHelper《CommonResult》.ConvertJson（url， postData）;

　　return （result ！= null） ？ result.Success ： false;

　　}

　　其中GetTokenUrl是根據(jù)token和API的地址等參數(shù)，構(gòu)建一個(gè)完整的提交地址。我們在上面代碼通過

　　var postData = new

　　{

　　userName = userName，

　　userPassword = userPassword

　　}.ToJson（）;

　　就可以動(dòng)態(tài)創(chuàng)建一個(gè)對象，并生成它的JSON字符串，把數(shù)據(jù)POST提交到對應(yīng)的API接口里面即可，然后對結(jié)果進(jìn)行對象的轉(zhuǎn)換就算完成了。
#e#

　　3、集合和分頁的處理

　　在很多接口里面，我們都需要用到分頁的處理，Web API也不例外，這樣可以提交數(shù)據(jù)檢索效率，減少服務(wù)器數(shù)據(jù)處理的壓力，同時(shí)也提交客戶端的數(shù)據(jù)顯示速度。

　　一般的集合接口定義如下所示（通用性基類接口）。

　　/// 《summary》

　　/// 返回?cái)?shù)據(jù)庫所有的對象集合

　　/// 《/summary》

　　/// 《returns》指定對象的集合《/returns》

　　［HttpGet］

　　public virtual List《T》 GetAll（string token）

　　{

　　//檢查用戶是否有權(quán)限，否則拋出MyDenyAccessException異常

　　base.CheckAuthorized（AuthorizeKey.ListKey， token）;

　　List《T》 list = baseBLL.GetAll（）;

　　return list;

　　}

　　但是這樣的返回記錄會比較多，一般情況下需要分頁，那么分頁的處理接口定義如下所示。

　　/// 《summary》

　　/// 根據(jù)條件查詢數(shù)據(jù)庫，并返回對象集合（用于分頁數(shù)據(jù)顯示）

　　/// 《/summary》

　　/// 《returns》指定對象的集合《/returns》

　　［HttpPost］

　　public virtual PagedList《T》 FindWithPager（string condition， PagerInfo pagerInfo， string token）

　　分頁接口，在這里返回的結(jié)果里面，用了一個(gè)PageList的泛型類，這個(gè)方便我們獲取當(dāng)前的記錄及總數(shù)，它的定義如下所示。

　　/// 《summary》

　　/// 分頁集合

　　/// 《/summary》

　　/// 《typeparam name=“T”》對象《/typeparam》

　　public class PagedList《T》

　　{

　　/// 《summary》

　　/// 返回記錄的總數(shù)

　　/// 《/summary》

　　public int total_count { get; set; }

　　/// 《summary》

　　/// 列表集合

　　/// 《/summary》

　　public List《T》 list { get; set; }

　　}

　　最后整個(gè)分頁的處理Web API接口實(shí)現(xiàn)如下所示。

　　/// 《summary》

　　/// 根據(jù)條件查詢數(shù)據(jù)庫，并返回對象集合（用于分頁數(shù)據(jù)顯示）

　　/// 《/summary》

　　/// 《returns》指定對象的集合《/returns》

　　［HttpPost］

　　public virtual PagedList《T》 FindWithPager（string condition， PagerInfo pagerInfo， string token）

　　{

　　//檢查用戶是否有權(quán)限，否則拋出MyDenyAccessException異常

　　base.CheckAuthorized（AuthorizeKey.ListKey， token）;

　　List《T》 list = baseBLL.FindWithPager（condition， pagerInfo）;

　　//構(gòu)造成Json的格式傳遞

　　var result = new PagedList《T》（） { total_count = pagerInfo.RecordCount， list = list };

　　return result;

　　}

　　最后客戶端調(diào)用分頁的Web API代碼如下所示。

　　/// 《summary》

　　/// 根據(jù)條件查詢數(shù)據(jù)庫，并返回對象集合（用于分頁數(shù)據(jù)顯示）

　　/// 《/summary》

　　/// 《param name=“condition”》查詢的條件《/param》

　　/// 《param name=“pagerInfo”》分頁實(shí)體《/param》

　　/// 《returns》指定對象的集合《/returns》

　　public virtual List《T》 FindWithPager（string condition， ref PagerInfo pagerInfo）

　　{

　　var action = “FindWithPager”;

　　string url = GetTokenUrl（action） + string.Format（“&condition={0}”， condition）;

　　var postData = pagerInfo.ToJson（）;

　　List《T》 result = new List《T》（）;

　　PagedList《T》 list = JsonHelper《PagedList《T》》.ConvertJson（url， postData）;

　　if （list ！= null）

　　{

　　pagerInfo.RecordCount = list.total_count;//修改總記錄數(shù)

　　result = list.list;

　　}

　　return result;

　　}

　　4、混合框架界面整合Web API接口

　　在整個(gè)Web API的平臺構(gòu)建以及在混合框架的整合過程中，我把各個(gè)模塊還是遵循相對獨(dú)立的方式進(jìn)行開發(fā)和整合，它們實(shí)現(xiàn)了從直接訪問數(shù)據(jù)庫、以WCF服務(wù)獲取數(shù)據(jù)，以及通過WebAPI調(diào)用方式獲取數(shù)據(jù)幾種方式的統(tǒng)一，從而實(shí)現(xiàn)了整個(gè)混合框架的高度整合。

　　整個(gè)混合框架的核心是以相對獨(dú)立的方式，整合各個(gè)可重用的模塊，我們可以遵循一定的基礎(chǔ)上，快速構(gòu)建統(tǒng)一的應(yīng)用平臺。
?

　　搭建完畢的整個(gè)WebAPI平臺，其中包括了服務(wù)端內(nèi)容，以API控制器的方式，發(fā)布了對應(yīng)的Web API接口。

　　在每個(gè)混合框架的獨(dú)立模塊里面，我們封裝了對應(yīng)的Web API客戶端調(diào)用處理，從而實(shí)現(xiàn)了Web API的調(diào)用方式。

　　在Win10下，使用Web API模式運(yùn)行混合框架，獲得的主體界面效果如下所示。

　　獨(dú)立模塊權(quán)限管理系統(tǒng)界面如下所示。