浅谈WebService的版本兼容性设计

在现在大型的项目或者软件开发中，一般都会有很多种终端， PC端比如Winform、WebForm，移动端，比如各种Native客户端(iOS, Android, WP)，Html5等，我们要满足以上所有这些客户端的需求，实现前后端的分离，一种最常见的做法是，编写WebService API来为以上客户端提供数据。近年来越来越多的企业或者网站支持Restfull方式的WebServiceAPI，比如当当网开源Dubbox，扩展Dubbo服务框架支持REST风格远程调用，这个是Java版本的，在.NET中ServiceStack天生支持Restfull风格的WebService。本文主要以ServiceStack为基础探讨，浅谈WebService的兼容性设计。

1．软件的兼容性

在软件持续更新升级的过程中，API 也是需要不断更新，这时就需要考虑客户端升级以及兼容性的问题。当前有很多用户可能由于多种原因，尤其是Native用户，不可能及时升级到***版，所以需要提供对老版本的API的向后兼容。在API设计之初，我们需要考虑一些问题以及解决方法。

后向兼容性(Backward_compatibility)，或者向下兼容，是指对于给定的输入，较老版本的产品或者技术，也能够输出相同的结果。如果一个产品或者API在设计之初就能够为新的标准考虑，能够满足接收，读取，查看旧的标准或者格式，那么这个产品就称之为后向兼容，比如一些数据格式或者通讯协议，在新版本推出时都会充分考虑后向兼容问题。如果对一个产品的改进破坏了后向兼容性，则称之为破坏性的改动(breaking change)，相信大家都遇到过这种情况。

• App长久没更新，落后很多个版本之后，再次打开改App会提示升级到***版，或者直接帮你强制升级。
• 使用新版的TortoiseSVN打开老版本TortoiseSVN创建的工程的时候，会提示需要升级项目工程才能打开。

这种情况一般发生在版本的改动比较大，或者对较老版本的支持成本比较大，在这种情况下，一般还需要为客户提供从老版本迁移到新版本的工具或者解决方案。

兼容性有很多种类型比如 API 的兼容， 二进制dll的兼容性，以及数据文档的兼容。

关于API的兼容性其实涉及到API的设计。相关文档和书籍有很多，关于API设计的书可以参考Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries (2nd Edition) 和 How to Design a Good API and Why it Matters

本文主要探讨WebService开发的API的向后兼容性。

#p#

2. WebService 的后向兼容性

在关于开发WebService框架上，这里不免又要谈一下WCF和ServiceStack的设计理念和区别。

在ServiceStack中，鼓励使用Message-based 式的设计，因为远程服务调用是很耗时，我们应该尽量一次多传输需要处理的数据，而避免来回多次调用。在WCF中，通过一些工具，使得开发者能够像调用本地方法一样调用远程方法，这样会使人产生误解，实际上调用远程方法会比调用远程方法慢上成千上万倍。ServiceStack在设计之初就受Martine Flowler 的 Data Transfer Object 模式的启发：

在API的设计上WCF鼓励将WebService作为普通的C#方法调用，这是一种基于普通的基于PRC 方式的调用。比如：

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设计，接口就是：

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

在ServiceStack中，所有的请求信息都包装在这个Customers的DTO中，他并不依赖于服务端方法的签名。最简单的好处在于使用message-base的设计在于wcf中的任意RPC组合都可以使用一个ServiceStack中的远程消息组合，并且只需要服务端的一次实现。

闲话说了这么多，现在来看看如何设计WebService的后向兼容性。谈到WebService，大家都会想到WCF，关于WCF的后向兼容，在Codeproject上，有人写了三篇文章WCF Backwards Compatibility and Versioning Strategies(part1,part2,part3)，由于ServiceStack仅支持Poco方式的请求参数，并且写在Poco中的字段都是必须的，没有WCF 中的对字段的 [DataMember(IsRequired = true)] 和 [DataMember(IsRequired = false)] 来标识字段是否可选，所以WCF支持的RPC方式的参数(Part1文章中的后向兼容算法)ServiceStack中无法做测试，这里对比做Part2文章中的测试。并且测试的时候，测试添加和移除字段对Service调用的影响。

建立测试之前，我们先建立一个基本的ServiceStack程序。 这个程序和前文中介绍一样，是一个简单的 ServiceStack序。

#p#

3. 基础

使用ServiceStack创建服务，基本的工程结构有三个。

ServiceModel这一层主要是定义 WebService中的请求参数和返回参数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; } 
    } 
} 

代码定义了请求参数DTO Employ对象，约定了其返回类型为 EmployResponse，这里继承IReturn< EmployResponse >是为了方便测试。 这里面指定了这个WebService的请求对象是Employ，返回对象是EmployResponse，并且通过’ /Employ/{EmpId}/{EmpName}’这样的方式来调用服务为Employ对象赋值。

ServiceInterface这一层是服务实现层。里面的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两种方式,请求参数类型Hello和返回值类型EmployResponse在Model中已经定义。我们不关心这个方法的名称，因为可以通过Rest路由来进行访问。

WebApplication和ConsoleApplicaiton是ServiceInterface的服务宿主层，我们可以使用ASP.NET 将服务部署到IIS上，也可以通过控制台程序进行部署以方便测试。

Web宿主很简单，我们定义一个类继承自AppHostbase，并提供包含有服务的程序集即可：

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()); 
        } 
    } 
} 

然后，在网站启动的时候，在Application_Start方法中初始化即可：

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

现在我们就可以通过Web的方式来查看我们创建的service服务：

可以通过Post Http的方式采用Json格式调用WebService服务，比如我们可以构造Json格式，将内容Post到 地址，http://localhost:28553/json/reply/ Employ：

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

返回值为：

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

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

不过在开发的时候，我们通常采用***种方式，将参数序列化为json字符串，然后post到我们部署的地址上。

以上是服务端代码，部署好了之后，客户端需要进行调用，调用的时候，我们需要引用ServiceModel这里面的请求和返回值实体类型。在部署了WebService之后，我们也可以通过引用WebService的方式来进行引用字段。

新建一个控制台应用程序，将上面的ServiceModel编译为dll之后，拷贝到新建的控制台程序下面，然后引用这个dll，客户端调用代码如下，我们采用了Json的方式传送数据，当然您可以选择其他的数据格式进行传输。代码如下：

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(); 
    } 
} 

把服务端代码运行起来之后，然后运行上面的控制台程序，输出如下：

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); 
        //..... 
    } 
}