在現(xiàn)在大型的項目或者軟件開發(fā)中，一般都會有很多種終端， PC端比如Winform、WebForm，移動端，比如各種Native客戶端(iOS, Android, WP)，Html5等，我們要滿足以上所有這些客戶端的需求，實現(xiàn)前后端的分離，一種最常見的做法是，編寫WebService API來為以上客戶端提供數(shù)據(jù)。近年來越來越多的企業(yè)或者網(wǎng)站支持Restfull方式的WebServiceAPI，比如當當網(wǎng)開源Dubbox，擴展Dubbo服務(wù)框架支持REST風格遠程調(diào)用，這個是Java版本的，在.NET中ServiceStack天生支持Restfull風格的WebService。本文主要以ServiceStack為基礎(chǔ)探討，淺談WebService的兼容性設(shè)計。

1．軟件的兼容性

在軟件持續(xù)更新升級的過程中，API 也是需要不斷更新，這時就需要考慮客戶端升級以及兼容性的問題。當前有很多用戶可能由于多種原因，尤其是Native用戶，不可能及時升級到***版，所以需要提供對老版本的API的向后兼容。在API設(shè)計之初，我們需要考慮一些問題以及解決方法。

后向兼容性(Backward_compatibility)，或者向下兼容，是指對于給定的輸入，較老版本的產(chǎn)品或者技術(shù)，也能夠輸出相同的結(jié)果。如果一個產(chǎn)品或者API在設(shè)計之初就能夠為新的標準考慮，能夠滿足接收，讀取，查看舊的標準或者格式，那么這個產(chǎn)品就稱之為后向兼容，比如一些數(shù)據(jù)格式或者通訊協(xié)議，在新版本推出時都會充分考慮后向兼容問題。如果對一個產(chǎn)品的改進破壞了后向兼容性，則稱之為破壞性的改動(breaking change)，相信大家都遇到過這種情況。

• App長久沒更新，落后很多個版本之后，再次打開改App會提示升級到***版，或者直接幫你強制升級。
• 使用新版的TortoiseSVN打開老版本TortoiseSVN創(chuàng)建的工程的時候，會提示需要升級項目工程才能打開。

這種情況一般發(fā)生在版本的改動比較大，或者對較老版本的支持成本比較大，在這種情況下，一般還需要為客戶提供從老版本遷移到新版本的工具或者解決方案。

兼容性有很多種類型比如 API 的兼容， 二進制dll的兼容性，以及數(shù)據(jù)文檔的兼容。

關(guān)于API的兼容性其實涉及到API的設(shè)計。相關(guān)文檔和書籍有很多，關(guān)于API設(shè)計的書可以參考Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries (2nd Edition) 和 How to Design a Good API and Why it Matters

本文主要探討WebService開發(fā)的API的向后兼容性。

#p#

2. WebService 的后向兼容性

在關(guān)于開發(fā)WebService框架上，這里不免又要談一下WCF和ServiceStack的設(shè)計理念和區(qū)別。

在ServiceStack中，鼓勵使用Message-based 式的設(shè)計，因為遠程服務(wù)調(diào)用是很耗時，我們應(yīng)該盡量一次多傳輸需要處理的數(shù)據(jù)，而避免來回多次調(diào)用。在WCF中，通過一些工具，使得開發(fā)者能夠像調(diào)用本地方法一樣調(diào)用遠程方法，這樣會使人產(chǎn)生誤解，實際上調(diào)用遠程方法會比調(diào)用遠程方法慢上成千上萬倍。ServiceStack在設(shè)計之初就受Martine Flowler 的 Data Transfer Object 模式的啟發(fā)：

在API的設(shè)計上WCF鼓勵將WebService作為普通的C#方法調(diào)用，這是一種基于普通的基于PRC 方式的調(diào)用。比如：

public interface IWcfCustomerService 
{ 
    Customer GetCustomerById(int id); 
    List<Customer> GetCustomerByIds(int[] id); 
    Customer GetCustomerByUserName(string userName); 
    List<Customer> GetCustomerByUserNames(string[] userNames); 
    Customer GetCustomerByEmail(string email); 
    List<Customer> GetCustomerByEmails(string[] emails); 
} 

以上WebService方法就是通過id，username或者email獲取用戶或者用戶列表。如果使用ServiceStack的基于Message-base風格的API設(shè)計，接口就是：

public class Customers : IReturn<List<Customer>> 
{ 
    public int[] Ids { get; set; } 
    public string[] UserNames { get; set; } 
    public string[] Emails { get; set; } 
} 

在ServiceStack中，所有的請求信息都包裝在這個Customers的DTO中，他并不依賴于服務(wù)端方法的簽名。最簡單的好處在于使用message-base的設(shè)計在于wcf中的任意RPC組合都可以使用一個ServiceStack中的遠程消息組合，并且只需要服務(wù)端的一次實現(xiàn)。

閑話說了這么多，現(xiàn)在來看看如何設(shè)計WebService的后向兼容性。談到WebService，大家都會想到WCF，關(guān)于WCF的后向兼容，在Codeproject上，有人寫了三篇文章WCF Backwards Compatibility and Versioning Strategies(part1,part2,part3)，由于ServiceStack僅支持Poco方式的請求參數(shù)，并且寫在Poco中的字段都是必須的，沒有WCF 中的對字段的 [DataMember(IsRequired = true)] 和 [DataMember(IsRequired = false)] 來標識字段是否可選，所以WCF支持的RPC方式的參數(shù)(Part1文章中的后向兼容算法)ServiceStack中無法做測試，這里對比做Part2文章中的測試。并且測試的時候，測試添加和移除字段對Service調(diào)用的影響。

建立測試之前，我們先建立一個基本的ServiceStack程序。 這個程序和前文中介紹一樣，是一個簡單的 ServiceStack序。

#p#

3. 基礎(chǔ)

使用ServiceStack創(chuàng)建服務(wù)，基本的工程結(jié)構(gòu)有三個。

ServiceModel這一層主要是定義 WebService中的請求參數(shù)和返回參數(shù)DTO, Employ中的代碼如下：

namespace WebApplication1.ServiceModel 
{ 
    [Route("/Employ/{EmpId}/{EmpName}")] 
    public class Employ : IReturn<EmployResponse> 
    { 
        public string EmpId { get; set; } 
        public string EmpName { get; set; } 
 
    } 
 
    public class EmployResponse 
    { 
        public string EmpId { get; set; } 
        public string EmpName { get; set; } 
    } 
} 

代碼定義了請求參數(shù)DTO Employ對象，約定了其返回類型為 EmployResponse，這里繼承IReturn< EmployResponse >是為了方便測試。 這里面指定了這個WebService的請求對象是Employ，返回對象是EmployResponse，并且通過’ /Employ/{EmpId}/{EmpName}’這樣的方式來調(diào)用服務(wù)為Employ對象賦值。

ServiceInterface這一層是服務(wù)實現(xiàn)層。里面的EmployServices直接繼承自ServiceStack中的Service對象。

namespace WebApplication1.ServiceInterface 
{ 
    public class EmployServices : Service 
    { 
        public EmployResponse Any(Employ request) 
        { 
            return new EmployResponse { EmpId = request.EmpId, EmpName = request.EmpName}; 
        } 
    } 
} 

這里Any表示這個Restfull請求支持Post和Get兩種方式,請求參數(shù)類型Hello和返回值類型EmployResponse在Model中已經(jīng)定義。我們不關(guān)心這個方法的名稱，因為可以通過Rest路由來進行訪問。

WebApplication和ConsoleApplicaiton是ServiceInterface的服務(wù)宿主層，我們可以使用ASP.NET 將服務(wù)部署到IIS上，也可以通過控制臺程序進行部署以方便測試。

Web宿主很簡單，我們定義一個類繼承自AppHostbase，并提供包含有服務(wù)的程序集即可：

namespace WebApplication1 
{ 
    public class AppHost : AppHostBase 
    { 
        /// <summary> 
        /// Default constructor. 
        /// Base constructor requires a name and assembly to locate web service classes.  
        /// </summary> 
        public AppHost() 
            : base("WebApplication1", typeof(EmployServices).Assembly) 
        { 
 
        } 
 
        /// <summary> 
        /// Application specific configuration 
        /// This method should initialize any IoC resources utilized by your web service classes. 
        /// </summary> 
        /// <param name="container"></param> 
        public override void Configure(Container container) 
        { 
            //Config examples 
            //this.AddPlugin(new PostmanFeature()); 
            //this.AddPlugin(new CorsFeature()); 
        } 
    } 
} 

然后，在網(wǎng)站啟動的時候，在Application_Start方法中初始化即可：

namespace WebApplication1 
{ 
    public class Global : System.Web.HttpApplication 
    { 
        protected void Application_Start(object sender, EventArgs e) 
        { 
            new AppHost().Init(); 
        } 
    } 
} 

現(xiàn)在我們就可以通過Web的方式來查看我們創(chuàng)建的service服務(wù)：

可以通過Post Http的方式采用Json格式調(diào)用WebService服務(wù)，比如我們可以構(gòu)造Json格式，將內(nèi)容Post到 地址，http://localhost:28553/json/reply/ Employ：

{"EmpId":"p1","EmpName":"zhangsan"} 

返回值為：

{"EmpId":"p1","EmpName":"zhangsan"} 

或者直接在地址欄里輸入：http://localhost:28553/Employ/p1/zhangshan

不過在開發(fā)的時候，我們通常采用***種方式，將參數(shù)序列化為json字符串，然后post到我們部署的地址上。

以上是服務(wù)端代碼，部署好了之后，客戶端需要進行調(diào)用，調(diào)用的時候，我們需要引用ServiceModel這里面的請求和返回值實體類型。在部署了WebService之后，我們也可以通過引用WebService的方式來進行引用字段。

新建一個控制臺應(yīng)用程序，將上面的ServiceModel編譯為dll之后，拷貝到新建的控制臺程序下面，然后引用這個dll，客戶端調(diào)用代碼如下，我們采用了Json的方式傳送數(shù)據(jù)，當然您可以選擇其他的數(shù)據(jù)格式進行傳輸。代碼如下：

class Program 
{ 
    static void Main(string[] args) 
    { 
        Console.Title = "ServiceStack Console Client"; 
 
        using (var client = new JsonServiceClient("http://localhost:28553/")) 
        { 
            EmployResponse employResponse = client.Send<EmployResponse>(new Employ { EmpId="1", EmpName="zhangshan"}); 
            if (employResponse != null) 
            { 
                Console.WriteLine(string.Format("EmoplyId:{0},EmployName:{1}",employResponse.EmpId,employResponse.EmpName)); 
            } 
        } 
 
        Console.ReadKey(); 
    } 
} 

把服務(wù)端代碼運行起來之后，然后運行上面的控制臺程序，輸出如下：

EmoplyId:p1,EmployName:zhangshan 

namespace WebApplication1.ServiceModel 
{ 
    [Route("/Employ/{EmpId}/{EmpName}")] 
    public class Employ : IReturn<EmployResponse> 
    { 
        public string EmpId { get; set; } 
        public string EmpName { get; set; } 
        public string Address { get; set; } 
 
    } 
 
    public class EmployResponse 
    { 
        public string EmpId { get; set; } 
        public string EmpName { get; set; } 
        public string Address { get; set; } 
    } 
} 
namespace WebApplication1.ServiceInterface 
{ 
    public class EmployServices : Service 
    { 
        public EmployResponse Any(Employ request) 
        { 
            return new EmployResponse { EmpId = request.EmpId, EmpName = request.EmpName, Address = request.Address }; 
        } 
    } 
} 

EmoplyId:0,EmployName:zhangshan 

EmoplyId:0,EmployName:zhangshan 

static void Main(string[] args) 
    { 
        Console.Title = "ServiceStack Console Client"; 
 
        using (var client = new JsonServiceClient("http://localhost:28553/")) 
        { 
            EmployResponse employResponse = client.Send<EmployResponse>(new Employ { EmpId="p1", EmpName="zhangshan",Address="sh"}); 
            if (employResponse != null) 
            { 
                Console.WriteLine(string.Format("EmoplyId:{0},EmployName:{1},Work at:{2}",employResponse.EmpId,employResponse.EmpName,employResponse.Address)); 
            } 
        } 
 
        Console.ReadKey(); 
    } 

EmoplyId:1,EmployName:zhangshan,Work at:sh 

EmoplyId:1,EmployName:zhangshan,Work at: 

class Employ   
{ 
    string Name { get; set; } 
} 

class Employ   
{ 
    Employ() 
    { 
        Version = 1; 
    } 
    int Version; 
    string Name; 
    string DisplayName; 
    int Age; 
} 

class Employ 
{ 
    Employ() 
    { 
        Version = 2; 
    } 
    int Version; 
    string Name; 
    string DisplayName; 
    string FirstName; 
    string LastName; 
    DateTime? DateOfBirth; 
} 

client.Send<EmployResponse>(new Employ { Name = "zhangshan" }); 

client.Send<EmployResponse>(new Employ { Name = "zhangshan" DisplayName="Ms Zhang", Age=22 }); 

client.Send<EmployResponse>(new Employ { FirstName = "zhang" LastName="shan", DateOfBirth=new DateTime(1992,01,01) }); 

public class EmployServices : Service 
{ 
    public EmployResponse Any(Employ request) 
    { 
        //V1: 
        request.Version == 0; 
        request.Name = "zhangshan"; 
        request.DisplayName == null; 
        request.Age = 0; 
        request.DateOfBirth = null; 
 
        //v2: 
        request.Version == 2; 
        request.Name == null; 
        request.DisplayName == "Foo Bar"; 
        request.Age = 18; 
        request.DateOfBirth = null; 
 
        //v3: 
        request.Version == 3; 
        request.Name == null; 
        request.DisplayName == null; 
        request.FirstName == "Foo"; 
        request.LastName == "Bar"; 
        request.Age = 0; 
        request.DateOfBirth = new DateTime(1994, 01, 01); 
        //..... 
    } 
}