您的 WebService 版本控制最佳实践是什么? [英] What are your WebService Versioning best practices?

问题描述

我们有 2 个独立的产品，它们需要通过网络服务相互通信.支持 API 版本化的最佳实践是什么?

We have 2 separate products that need to communicate with each other via web services. What is the best-practice to support versioining of the API?

我在 2004 年有 这篇文章 声称没有实际标准，只有最佳实践.有什么更好的解决方案吗?您如何解决 WS 版本控制?

I have this article from 2004 claiming there is no actual standard, and only best practices. Any better solutions? How do you solve WS versioning?

class SystemAClient{
    SystemBServiceStub systemB;
    public void consumeFromB(){
        SystemBObject bObject = systemB.getSomethingFromB(new SomethingFromBRequest("someKey"));

    }
}

服务

class SystemAService{
    public SystemAObject getSomethingFromA(SomethingFromARequest req){
        return new SystemAObjectFactory.getObject(req);
    }
}

可转移对象

版本 1

class SystemAObject{
     Integer id;
     String name;
     ... // getters and setters etc;
}

版本 2

class SystemAObject{
     Long id;
     String name;
     String description;
     ... // getters and setters etc;
}

请求对象

版本 1

class SomethingFromARequest {
     Integer requestedId;
     ... // getters and setters etc;

}

版本 2

class SomethingFromARequest {
     Long requestedId;
     ... // getters and setters etc;

}

系统 B

客户

class SystemBClient{
    SystemAServiceStub systemA;
    public void consumeFromA(){
        SystemAObject aObject = systemA.getSomethingFromA(new SomethingFromARequest(1));
        aObject.getDescription() // fail point
        // do something with it...
    }
}

服务

class SystemBService{
    public SystemBObject getSomethingFromB(SomethingFromBRequest req){
        return new SystemBObjectFactory.getObject(req);
    }
}

可转移对象

版本 1

class SystemBObject{
     String key;
     Integer year;
     Integer month;
     Integer day;

     ... // getters and setters etc;
}

版本 2

class SystemBObject{
     String key;
     BDate date;
     ... // getters and setters etc;
}

class BDate{
     Integer year;
     Integer month;
     Integer day;
     ... // getters and setters etc;

}

请求对象

版本 1

class SomethingFromBRequest {
     String key;
     ... // getters and setters etc;
}

版本 2

class SomethingFromBRequest {
     String key;
     BDate afterDate;
     BDate beforeDate;
     ... // getters and setters etc;
}

失败场景

如果版本 1 的系统 A客户端调用系统 B服务 版本 2 可能会失败:

Fail Scenarios

If a System A client of version 1 calls a System B service of version 2 it can fail on:

• SystemBObject 上的缺失方法(getYear()、getMonth()、getDay())
• 未知类型BDate

• missing methods on SystemBObject (getYear(), getMonth(), getDay())
• Unknown type BDate

如果系统A客户端版本2调用系统B服务 版本 1 可能会失败:

If a System A client of version 2 calls a System B service of version 1 it can fail on:

• SomethingFromBRequest 上的未知类型 BDate(客户端使用 B 版本 1 无法识别的较新的 B 请求对象)
• 如果系统 A 客户端足够聪明，可以使用请求对象的版本 1，它可能会在 SystemBObject 对象 (getDate()) 上缺少方法时失败

• Unknown type BDate on the SomethingFromBRequest (A client uses a newer B request object that B version 1 doesn't recognize)
• If the System A client is smart enough to use version 1 of the request object, it can fail on missing methods on the SystemBObject object (getDate())

如果系统 B客户端版本 1 调用系统 A 服务 版本 2 可能会失败:

If a System B client of version 1 calls a System A service of version 2 it can fail on:

• SystemAObject 上的类型不匹配或溢出(返回 Long 但预期为 Integer)

• Type missmatch or overflow on SystemAObject (returned Long but expected Integer)

如果系统 B客户端版本 2 调用系统 A 服务 版本 1 可能会失败:

If a System B client of version 2 calls a System A service of version 1 it can fail on:

• 在 SystemARequest 上键入不匹配或溢出(请求 Long 而不是 Integer)
• 如果请求以某种方式通过，则转换问题(存根是 Long，但服务返回一个 Integer 并非在所有 WS 实现中都完全兼容)

• Type missmatch or overflow on SystemARequest (request Long instead of Integer)
• If the request passed somehow, casting issues (the stub is Long but the service returns an Integer not nessecarily compatible in all WS implementations)

1. 在推进版本时使用数字:例如SystemAObject1、SystemBRequest2 等，但缺少匹配源/目标版本的 API
2. 在签名中，传递 XML 而不是对象(糟糕，传递 XML 中的转义 XML，双重序列化，反序列化/解析，解解析)
3. 其他:例如Document/literal/WS-I 有补救措施吗?

1. Use numbers when advancing versions: e.g. SystemAObject1, SystemBRequest2 etc but this is missing a an API for matching source / target version
2. In the signature, pass XML and not objects (yuck, pass escaped XML in XML, double serialization, deserialization / parsing, unparsing)
3. Other: e.g. does Document/literal / WS-I has a remedy?

推荐答案

我更喜欢 Salesforce.com 的版本控制方法.每个版本的 Web 服务都有一个不同的 URL，格式如下:

I prefer the Salesforce.com method of versioning. Each version of the Web Services gets a distinct URL in the format of:

http://api.salesforce.com/{version}/{serviceName}

因此您将拥有如下所示的 Web 服务 URL:

So you'll have Web Service URLs that look like:

http://api.salesforce.com/14/Lead

http://api.salesforce.com/15/Lead

等等...

使用此方法，您可以获得以下好处:

With this method, you get the benefits of:

1. 你总是知道你在谈论哪个版本.

1. You always know which version you're talking to.

保持向后兼容性.

您不必担心依赖问题.每个版本都有完整的服务集.您只需要确保不要在调用之间混合版本(但这取决于服务的消费者，而不是您作为开发人员).

You don't have to worry about dependency issues. Each version has the complete set of services. You just have to make sure you don't mix versions between calls (but that's up to the consumer of the service, not you as the developer).

这篇关于您的 WebService 版本控制最佳实践是什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！