Shulou(Shulou.com)06/02 Report--

How to talk about WebService version compatibility design, many novices are not very clear about this, in order to help you solve this problem, the following editor will explain for you in detail, people with this need can come to learn, I hope you can gain something.

In today's large-scale projects or software development, there are generally many kinds of terminals, such as PC, such as Winform, WebForm, mobile, such as various Native clients (iOS, Android, WP), Html5, and so on. To meet the needs of all these clients and achieve the separation of front and rear, one of the most common ways is to write WebService API to provide data for the above clients. In recent years, more and more enterprises or websites support Restfull-style WebServiceAPI, such as Dangdang open source Dubbox, extended Dubbo service framework supports REST-style remote calls, this is the Java version, ServiceStack naturally supports Restfull-style WebService in .NET. Based on ServiceStack, this paper discusses the compatibility design of WebService.

1. Software compatibility

In the process of continuous software update and upgrade, API also needs to be constantly updated, so it is necessary to consider client upgrade and compatibility. At present, many users may not be able to upgrade to the * * version in time for a variety of reasons, especially Native users, so it is necessary to provide backward compatibility with the old version of API. At the beginning of API design, we need to consider some problems and solutions.

Backward compatibility (Backward_compatibility), or backward compatibility, means that older versions of the product or technology can output the same results for a given input. If a product or API can consider new standards at the beginning of its design, and is able to receive, read, and view old standards or formats, then the product is called backward compatibility, such as some data formats or communication protocols, which will be fully considered when the new version is launched. If an improvement to a product breaks backward compatibility, it's called a destructive change (breaking change), which I'm sure you've all encountered before.

App has not been updated for a long time, and after lagging behind many versions, opening the changed App again will prompt you to upgrade to * * version, or directly help you to force the upgrade.

When you open a project created by the old version of TortoiseSVN with the new version of TortoiseSVN, you will be prompted that you need to upgrade the project project to open it.

This usually occurs when there is a large change in the version, or the cost of support for the older version is relatively high, in which case, it is also necessary to provide customers with tools or solutions to migrate from the old version to the new version.

There are many types of compatibility, such as API compatibility, binary dll compatibility, and data document compatibility.

The compatibility of API actually involves the design of API. There are many related documents and books, and books on API design can be found in Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries (2nd Edition) and How to Design a Good API and Why it Matters.

This article focuses on the backward compatibility of API developed by WebService.

2. Backward compatibility of WebService

On the development of the WebService framework, we can't help talking about the design concepts and differences between WCF and ServiceStack.

In ServiceStack, the use of Message-based-style design is encouraged, because remote service invocation is time-consuming, and we should try to transfer more data that needs to be processed at once, rather than making multiple calls back and forth. In WCF, there are tools that enable developers to call remote methods as if they were local methods, which can be misleading. In fact, calling remote methods is thousands of times slower than calling remote methods. ServiceStack was inspired by Martine Flowler's Data Transfer Object pattern at the beginning of its design:

"When you're working with a remote interface, such as Remote Facade, each call to it is expensive. As a result you need to reduce the number of calls, and that means that you need to transfer more data with each call. One way to do this is to use lots of parameters. However, this is often awkward to program-indeed, it's often impossible with languages such as Java that return only a single value.

The solution is to create a Data Transfer Object that can hold all the data for the call. It needs to be serializable to go across the connection. Usually an assembler is used on the server side to transfer data between the DTO and any domain objects. "

In the design of API, WCF encourages WebService as a normal C # method call, which is based on a normal PRC-based call. For example:

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

The above WebService method is to obtain the user or user list through id,username or email. If you use ServiceStack's Message-base-style API design, the interface is:

Public class Customers: IReturn {public int [] Ids {get; set;} public string [] UserNames {get; set;} public string [] Emails {get; set;}}

In ServiceStack, all request information is wrapped in the DTO of this Customers, which does not rely on the signature of the server-side method. The simplest benefit of using message-base is that any RPC combination in wcf can use a remote message composition in ServiceStack and requires only one implementation on the server side.

After all the gossip, let's take a look at how to design backward compatibility for WebService. When it comes to WebService, everyone will think of WCF, about the backward compatibility of WCF. On Codeproject, someone wrote three articles WCF Backwards Compatibility and Versioning Strategies (part1,part2,part3). Because ServiceStack only supports Poco request parameters, and the fields written in Poco are required, there is no [DataMember (IsRequired = true)] and [DataMember (IsRequired = false)] in WCF to identify whether the field is optional. Therefore, the parameters of RPC mode supported by WCF (backward compatibility algorithm in Part1 article) cannot be tested in ServiceStack, which is compared with the test in Part2 article. And when testing, test the impact of adding and removing fields on Service calls.

Before setting up the test, let's build a basic ServiceStack program. As described in the previous article, this program is a simple ServiceStack order.

3. Basics

Using ServiceStack to create services, there are three basic engineering structures.

The ServiceModel layer mainly defines the request parameters and return parameters DTO in WebService. The code in Employ is as follows:

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

The code defines the request parameter DTO Employ object and specifies that its return type is EmployResponse, where IReturn is inherited.

It's for testing. It specifies that the request object of the WebService is Employ, the return object is EmployResponse, and the service is called to assign a value to the Employ object through the way'/ Employ/ {EmpId} / {EmpName}'.

The ServiceInterface layer is the service implementation layer. The EmployServices in it inherits directly from the Service object in ServiceStack.

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

Here Any indicates that the Restfull request supports both Post and Get. The request parameter type Hello and the return value type EmployResponse have been defined in Model. We don't care about the name of this method because it can be accessed via Rest routing.

WebApplication and ConsoleApplicaiton are the service host layer of ServiceInterface. We can use ASP.NET to deploy the service to IIS, or we can deploy it through the console program to facilitate testing.

The Web host is simple. We define a class that inherits from AppHostbase and provide an assembly that contains services:

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

Then, when the website starts, initialize it in the Application_Start method:

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

Now we can view the service service we created through Web:

You can invoke the WebService service in Json format through Post Http. For example, we can construct the Json format, Post the content to the address, and http://localhost:28553/json/reply/ Employ:

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

The returned value is:

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

Or type: http://localhost:28553/Employ/p1/zhangshan directly in the address bar

However, during development, we usually use the * * method to serialize the parameters into a json string, and then post to the address where we deployed.

The above is the server code. After deployment, the client needs to make a call. When calling, we need to refer to the request and return value entity types in ServiceModel. After deploying WebService, we can also reference fields by referencing WebService.

Create a new console application, compile the above ServiceModel into dll, copy it to the new console program, and then reference the dll. The client call code is as follows. We use Json to transfer data. Of course, you can choose another data format to transfer. The code is as follows:

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

After running the server code, then run the console program above, and the output is as follows:

EmoplyId:p1,EmployName:zhangshan

4. test

4.1 Case 1 add New Fields

Now suppose we have only two fields for the Employ entity in our v1 version of API. Later, we found that in the v2 version, we also need to add an Address field to indicate the address of the employee, so we modified the Model, added the Address field, and modified this field in both Request and Response. Now the server code is as follows:

Namespace WebApplication1.ServiceModel {[Route ("/ Employ/ {EmpId} / {EmpName}")] public class Employ: IReturn {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};}

Then compile and run. It should be noted that the ServiceModel dll referenced by the client is still the previous version of dll with only two fields. Now run the client again with the output as follows:

EmoplyId:0,EmployName:zhangshan

The result is the same as the previous one, which means that adding new fields to the new API and adding new fields to the return value will not affect the existing WebService.

4.2 Case 2: modify the type of data field

Later, in the V3 version, we found that EmpID should be an int type, so we changed the EmployID of the server Employ entity from string type to int type, and then ran the client, because on the client side, we passed "p1" of string type to ID, which could not be directly converted to int type, and the real output was as follows:

EmoplyId:0,EmployName:zhangshan

There is no mistake, but it is not the result we expected. When the client passes the EmpolyID field "p1", the server has changed the field type to int, and "p1" has not been converted to int, so it will use the default initial value of 0 of int instead.

4.3 Case 3: remove necessary fields

Now let's compile the ServiceModel and copy it to ServiceClint to update the client's dll reference so that the client can get the Address field. If it's WebService, just update the reference directly. Now let's modify the client to assign a value to Address when requested.

Static void Main (string [] args) {Console.Title = "ServiceStack Console Client"; using (var client = new JsonServiceClient ("http://localhost:28553/")) {EmployResponse employResponse = client.Send (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 ();}

You can see that the client has updated the EmpId has been int, if the transmission of p1, it will report an error. Now that the compilation is running, the output should be:

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

Now, in the V4 version, we found that the work address Address field added in the v2 version should not be placed in the Employ, so the field was removed on the server side and redeployed. The client runs again and the result is as follows:

EmoplyId:1,EmployName:zhangshan,Work at:

As you can see, after the Address field is removed from the server, the Address element is missing from the original data returned by the server. When deserializing, the client assigns the value to null without this field.

5. Summary

If you use ServiceStack, during the evolution of API, the new version of API may have the following modifications compared to the older version of API:

Add, remove, or rename fields.

Convert the type of a field from int to double or long, which can be implicitly converted.

Change the collection type from List to HashSet.

Change the strongly typed collection to the loosely typed List collection and change the element in the loosely typed List to Dictionary.

A new enumeration type has been added.

A nullable field was added.

After the client serializes the entity, when it is transferred to the server, the serialization tool will automatically deal with the above types of changes and inconsistencies. If the field does not match, or the type conversion fails, the default value of the type of the field on the server will be used instead.

With regard to the compatibility strategy of API, there are several points to note:

5.1 the evolution of the existing version of API should be addressed rather than re-implementing a

Only one parameter for the new field has been added. Because, if you want to maintain several different versions of API at the same time, but implement the same functionality, it may make a lot of work and prone to errors. This convention should be followed at the beginning of writing * * versions of API. Writing multiple versions of API that implement the same or similar functions at the same time violates the DRY principle.

5.2 take full advantage of the version features of the self-built serialization tool

Some serialization tools will attach the default value of changing the field type to the field when the field does not match; can automatically convert between collection types of the same structure; can carry out implicit conversion of types, and so on. For example, if an id uses the int type in the older api, then in the new version, we can directly change it to the long type to be backward compatible.

Enhance the defense of existing services against change

In WCF, you can use DataContract to freely add or remove fields without generating breaking change. This is mainly due to its implementation of the IExtensibleDataObject interface. On a DTO object of a return type, you can also implement this function if you implement this interface. When you are compatible with older versions of DTOs, you should do adequate testing, in general:

Do not modify the data type of an existing field, if you do need to, add another property, and determine the version based on the field you have.

Defensive programming is to determine which fields may not exist in older versions of the client, so don't force them to exist.

Ensure that there is only one unique global namespace. This can be handled in the AssemblyInfo.cs of the program. Generally, we define a common AssemblyInfo, and then link references in various DTO projects.

5.3 add version control information to DTO

This is also the easiest to think of and achieve. In most cases, if you use the idea of defensive programming and smoothly evolve the API, you can usually infer the client version from the data. However, in some special cases, the server needs to deal with it according to the specific version of the client, so you can add version information to the request DTO. Examples are as follows:

For example, when the service Empoly was first released, it didn't think much about defining the DTO of the following request:

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

Then, due to some reasons, the UI of the application has changed, and we do not want to return this general Name attribute to the customer. We need to track the version used by the client to consider returning that value, so DTO is modified to the following, and new fields DisplayName and Age are added:

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

However, after discussion at the meeting, we found that DisplayName is still not very good. * can split it into two fields, and it is not good to store Age, so we should store DateOfBirth, so our DTO becomes like this:

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

Up to the current location, the client has three versions, and they send the request to the server as follows:

V1 version:

Client.Send (new Employ {Name = "zhangshan"})

V2 version:

Client.Send (new Employ {Name= zhangshan "DisplayName=" Ms Zhang ", Age=22})

V3 version:

Client.Send (new Employ {FirstName = "zhang" LastName= "shan", DateOfBirth=new DateTime (1992 Person01)})

Now, the server can uniformly handle the requests of the above three versions of the client:

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

5.4 follow the principle of "minimization"

One point should be a summary of experience in practice. Just as we write query conditions in SQLServer, do not try to use select * to replace the fields that need to be entered manually, excluding efficiency reasons, because once the order of the fields queried changes, it may affect the resolution. You also need to consider this issue when designing optional values for DTO. Here's an example:

For example, we want to design an API to find accessories merchants, the API supports finding accessories for hotels, restaurants and unlimited. So we usually define a field SearchScope that represents the look-up scope in DTO and define some enumerated values.

0-unlimited 1-hotel 2-catering

It should be noted here that if we use 0 to indicate no limit at the beginning of the * * version, in the implementation, such as in the SQL statement, we will usually limit the query conditions, so that the * * version will be issued normally.

In the second version, however, we added support for nearby places of entertainment and developed special page support for search results for places of entertainment. Therefore, it is natural to consider adding an enumerated value to represent entertainment in SearchScope, and increasing the storage of entertainment place information in DB.

3-Entertainment

Then the interface of the V2 version was released smoothly. At this time, if there is no version information in DTO, the problem arises. In the V1 version, when users search, if the choice is not limited, then the search results will appear "entertainment" related information, but click on the search results of "entertainment", other pages in the V1 version, did not do the corresponding page processing. So there will be some problems. So when you release the V2 version of API, you need to modify the processing logic of the V1 version.

So when designing the V1 version of API, for cases where there are not too many conditions or combinations, for the "unlimited" scenario, we should pass all the supported categories, such as "1Mague 2" instead of "0". Or when designing the scope, enumerate values that can be carried out or "|", such as 0-unlimited, 1-hotel, 2-catering, 4-entertainment, etc. In this way, the release of the new version has less impact on the API called the old version.

Is it helpful for you to read the above content? If you want to know more about the relevant knowledge or read more related articles, please follow the industry information channel, thank you for your support.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.