在Winform混合式框架中整合外部API接口的調用

在我們常規的業務處理中，一般內部處理的接口多數都是以數據庫相關的，基於混合式開發的Winform開發框架，雖然在客戶端調用的時候，一般選擇也是基於Web API的調用，不過后端我們可能不僅僅是針對我們業務數據庫的處理，也可以能是調用其他外部接口，如物流、供應商接口等接口，本隨筆就是主要介紹基於混合式開發框架如何整合外部API接口的調用。

1、混合式框架的結構介紹

 我們知道，混合式的框架是可以在客戶端訪問Web API服務、WCF服務或者直接連接數據庫幾種方式的綜合，而尤以Web API為最廣泛的應用，它的整個框架的結構如下所示。

在客戶端中，通過統一的工廠類CallerFactory<T>對相應的接口進行訪問，這里主要就是服務器端Web API服務接口的處理，以及客戶端對Web API接口的封裝，兩部分通過一些基類進行簡化處理，可以極大提高開發效率。

對於外部第三方的Web API接口，我們也可以在自己的Web API接口中進行包裝，使得客戶端通過相應的接口進行交互即可，不需要理會內部還是外部的接口，從而實現透明的接口調用。

 2、RFID外部接口的整合處理

 在一個客戶的應用案例中，需要整合服務商RFID接口實現相應的數據交互，本篇隨筆也是基於這個案例進行整個過程的分析和操作，使得我們了解在混合框架中如何整合第三方Web API接口為我們內部框架所用。

一般來說，Web API接口，需要明確API的URL、數據提交方式（POST/GET）、提交參數、返回集合，以及一些特殊的數據等，而一般接口的操作，也是需要一個訪問令牌的，這些都是Web API接口調用的關鍵。

基本上我們有了上面Web API的1/2/3步驟的信息就可以進行接口編程了，這些是Web API開發非常重要的信息。

我們需要特別主要到，步驟1中的信息

這里面的token是額外的接口信息，是需要設置Http Request請求的頭部信息里面的，是用戶身份的重要信息，所以我們一般需要先通過指定的授權接口獲取這個token信息。

在這個外部的接口集合里面，我們找到統一登錄驗證的接口定義如下所示。

 通過上面的分析，我們首先需要需要處理好登錄驗證接口，然后通過接口傳遞令牌token給其他接口進行數據處理的。

結合我們的混合框架結構，這里我以測試項目TestProject項目為例進行介紹，我們調整WHC.TestProject.Caller項目的對應類，如下所示。

其中Facade層接口類IRFIDService.cs代碼如下所示。

    /// <summary>
    /// RFID服務外部接口
    /// </summary>
    [ServiceContract]
    public interface IRFIDService 
    {

        /// <summary>
        /// 終端用戶統一登錄驗證
        /// </summary>
        [OperationContract]
        CheckinResult CheckIn(string username, string password, string device_uuid, string device_type, string last_app_version, string app_id);

        /// <summary>
        /// 獲取標簽發貨通知單批量
        /// </summary>
        [OperationContract]
        TagOrderAsnResult TagOrderAsn(int brand_id, string factcode, string start_time, string end_time, PagerInfo pagerInfo, string token);

        /// <summary>
        /// 標簽訂單出庫物流信息回寫
        /// </summary>
        [OperationContract]
        CommonResult TagOutPost(string docno_asn, string factcode, string dest_factcode, List<FreightInfo> freight, string token);
    }

這里面的接口定義，我們是根據輸入參數、輸出參數進行定義的，另外token是額外增加的令牌參數，用於請求頭部寫入信息的。

這個接口的定義其實和我們常規的Web API接口定義沒有太多的不同，如下是一個內部客戶信息接口定義。

    /// <summary>
    /// 客戶信息的服務接口
    /// </summary>
    [ServiceContract]
    public interface ICustomerService : IBaseService<CustomerInfo>
    {               
        /// <summary>
        /// 根據客戶名稱獲取客戶列表
        /// </summary>
        /// <param name="name">客戶名稱</param>
        /// <returns></returns>
        [OperationContract]
        List<CustomerInfo> FindByName(string name);
    }

差別就是它們接口繼承類有所不同，外部接口由於不需要和數據庫打交道，我們不需要繼承IBaseService接口

根據這些接口的定義，我們還需要實現我們具體的Web API 服務，邏輯上它是對外部Web API接口的封裝，但是對於客戶端來說，並不需要知道是內部還是外部接口，客戶端只需要知道如果提交參數或者結果即可。

由於Web API涉及多個參數的數據提交，一般來說這種情況都是以POST方式處理的，數據參數則統一在Web API端通過定義一個JObject對象來傳遞即可，登錄認證的Web API接口定義如下所示。

    /// <summary>
    /// 基於RFID的應用接口
    /// </summary>
    public class RFIDController : BaseApiController
    {
        /// <summary>
        /// 終端用戶統一登錄驗證
        /// </summary>
        /// <param name="param">包含多個屬性的對象</param>
        /// <param name="token">訪問令牌</param>
        [HttpPost]
        public CheckinResult CheckIn(JObject param)
        {
            CheckinResult result = null;
            dynamic obj = param;
            if (obj != null)
            {
                //使用POST數據
                var postData = param.ToJson();
                //使用具體的URL
                var queryUrl = "https://***.***.***/api/v6/rfid/terminal/checkin/post";

                var helper = new HttpHelper();
                helper.ContentType = "application/json";
                var content = helper.GetHtml(queryUrl, postData, true);
                RFIDBaseData<CheckinResult> jsonResult = JsonConvert.DeserializeObject<RFIDBaseData<CheckinResult>>(content);
                if (jsonResult != null && jsonResult.code == 0)
                {
                    result = jsonResult.data;
                }
                return result;
            }
            else
            {
                throw new MyApiException("傳遞參數錯誤");
            }
        }

其中輸入的參數這里用了JObject param的參數，我們提交給外部Web API接口的時候，我們把這個參數再次序列號為JSON格式的字符串即可：

var postData = param.ToJson();

其中CheckinResult和RFIDBaseData是根據輸入參數、輸出結果進行的實體類定義，目的是序列化為強類型的實體類，方便數據處理操作。

在客戶端，我們只需要對接好和Web API服務端的接口，那么調用起來就非常方便，其中對應的Web API接口客戶端封裝類 RFIDCaller 如下所示。

    /// <summary>
    /// 對RFID控制的接口調用封裝
    /// </summary>
    public class RFIDCaller : NormalApiService, IRFIDService
    {
        public RFIDCaller()
        {
            this.ConfigurationPath = ApiConfig.ConfigFileName; //Web API配置文件
            this.configurationName = ApiConfig.RFID;
        }

        public CheckinResult CheckIn(string username, string password, string device_uuid, string device_type, string last_app_version, string app_id)
        {
            var action = System.Reflection.MethodBase.GetCurrentMethod().Name;
            string url = GetNormalUrl(action);
            var postData = new
            {
                username = username,
                password = password,
                device_uuid = device_uuid,
                device_type = device_type,
                last_app_version = last_app_version,
                app_id = app_id,
            }.ToJson();

            var result = JsonHelper<CheckinResult>.ConvertJson(url, postData);
            return result;
        }

有了這些，我們直接在客戶端的界面里面，就可以通過調用CallerFactory<T>進行處理操作了，如下是客戶端窗體獲取驗證身份令牌數據的代碼

        private string token = null;//訪問RFID接口的token
        /// <summary>
        /// 根據終端用戶統一登錄驗證獲取相關訪問token
        /// </summary>
        /// <returns></returns>
        private string GetRFIDToken()
        {
            string username = "wuhuacong";
            string password = "123456";
            string device_uuid = "aaaaaaa";
            string device_type = "iphone";
            string last_app_version = "xxxxxxx";
            string app_id = "ntdf5543581a2f066e74cf2fe456";
            
            var result = CallerFactory<IRFIDService>.Instance.CheckIn(username, password, device_uuid, device_type, last_app_version, app_id);
            if(result != null)
            {
                token = result.token;
            }
            return token;
        }

 

 上面是認證身份的接口，其他類型的接口類似的處理方式，如增加了一個

獲取標簽發貨通知單批量

操作后，對應的客戶端封裝類如下所示。

    /// <summary>
    /// 對RFID控制的接口調用封裝
    /// </summary>
    public class RFIDCaller : NormalApiService, IRFIDService
    {
        public RFIDCaller()
        {
            this.ConfigurationPath = ApiConfig.ConfigFileName; //Web API配置文件
            this.configurationName = ApiConfig.RFID;
        }

        public CheckinResult CheckIn(string username, string password, string device_uuid, string device_type, string last_app_version, string app_id)
        {
            var action = System.Reflection.MethodBase.GetCurrentMethod().Name;
            string url = GetNormalUrl(action);
            var postData = new
            {
                username = username,
                password = password,
                device_uuid = device_uuid,
                device_type = device_type,
                last_app_version = last_app_version,
                app_id = app_id,
            }.ToJson();

            var result = JsonHelper<CheckinResult>.ConvertJson(url, postData);
            return result;
        }

        public TagOrderAsnResult TagOrderAsn(int brand_id, string factcode, string start_time, string end_time, Pager.Entity.PagerInfo pagerInfo, string token)
        {
            var action = System.Reflection.MethodBase.GetCurrentMethod().Name;
            string url = GetNormalUrl(action) + string.Format("?token={0}", token);
            var postData = new
            {
                page = pagerInfo.CurrenetPageIndex,
                pagesize = pagerInfo.PageSize,
                brand_id = brand_id,
                factcode = factcode,
                start_time = start_time,
                end_time = end_time,
            }.ToJson();

            var result = JsonHelper<TagOrderAsnResult>.ConvertJson(url, postData);
            return result;
        }

獲取標簽發貨通知單批量

 的Web API接口如下代碼定義

 

        /// <summary>
        /// 獲取標簽發貨通知單批量
        /// </summary>
        /// <param name="param"></param>
        /// <param name="token"></param>
        /// <returns></returns>
        [HttpPost]
        public TagOrderAsnResult TagOrderAsn(JObject param, string token)
        {
            TagOrderAsnResult result = null;
            dynamic obj = param;
            if (obj != null)
            {
                //使用POST方式
                var postData = param.ToJson();
                var queryUrl = "https://***.***.***/api/v6/rfid/tag/tag_order_asn/get";
                                
                var helper = new HttpHelper();
                helper.ContentType = "application/json";
                helper.Header.Add("token", token); 
                var content = helper.GetHtml(queryUrl, postData, true);

                RFIDBaseData<TagOrderAsnResult> jsonResult = JsonConvert.DeserializeObject<RFIDBaseData<TagOrderAsnResult>>(content);
                if (jsonResult != null && jsonResult.code == 0)
                {
                    result = jsonResult.data;
                }

                return result;
            }
            else
            {
                throw new MyApiException("傳遞參數錯誤");
            }

其中表頭信息，我們通過下面的代碼指定，設置特殊的token表頭信息

                var helper = new HttpHelper();
                helper.ContentType = "application/json";
                helper.Header.Add("token", token); 

而在客戶端的調用窗體里面，我們調用對應的接口就可以獲取該接口的數據了。

        private TagOrderAsnResult asnResult;
        /// <summary>
        /// 根據參數獲取標簽生產訂單批量信息
        /// </summary>
        /// <returns></returns>
        private TagOrderAsnResult GetResult()
        {
            PagerInfo pagerInfo = new PagerInfo() { PageSize = 50, CurrenetPageIndex = 1 };//初始化一個分頁條件
            var brand_id = this.txtbrand_id.Text.ToInt32();
            var factcode = this.txtfactcode.Text;
            var start_time = this.txtstart_time.DateTime.ToString("yyyy-MM-dd HH:mm:ss");
            var end_time = this.txtend_time.DateTime.ToString("yyyy-MM-dd HH:mm:ss");

            asnResult = CallerFactory<IRFIDService>.Instance.TagOrderAsn(brand_id, factcode, start_time, end_time, pagerInfo, Token);
            return asnResult;
        }

通過上面的代碼演示，我們了解了在混合框架基礎上增加外部Web API接口的方法，通過增加Facade層接口，增加Web API接口，以及對應的客戶端封裝類，具體處理參數根據Web API接口的輸入參數、輸出數據等信息進行綜合處理即可。

最后我們來看看數據的展示界面。