使用JSON协议处理版本控制的最佳方法是什么? [英] What is the best way to handle versioning using JSON protocol?

问题描述

我通常用C#编写代码的所有部分，编写序列化的协议时，我使用FastSerializer，该类可以快速，高效地对类进行序列化/反序列化.它也非常易于使用，并且非常直接地进行版本转换"，即处理序列化的不同版本.我通常使用的东西看起来像这样:

I am normally writing all parts of the code in C# and when writing protocols that are serialized I use FastSerializer that serializes/deserializes the classes fast and efficient. It is also very easy to use, and fairly straight-forward to do "versioning", ie to handle different versions of the serialization. The thing I normally use, looks like this:

public override void DeserializeOwnedData(SerializationReader reader, object context)
{
    base.DeserializeOwnedData(reader, context);
    byte serializeVersion = reader.ReadByte(); // used to keep what version we are using

    this.CustomerNumber = reader.ReadString();
    this.HomeAddress = reader.ReadString();
    this.ZipCode = reader.ReadString();
    this.HomeCity = reader.ReadString();
    if (serializeVersion > 0)
        this.HomeAddressObj = reader.ReadUInt32();
    if (serializeVersion > 1)
        this.County = reader.ReadString();
    if (serializeVersion > 2)
        this.Muni = reader.ReadString();
    if (serializeVersion > 3)
        this._AvailableCustomers = reader.ReadList<uint>();
}

和

public override void SerializeOwnedData(SerializationWriter writer, object context)
{            
    base.SerializeOwnedData(writer, context);
    byte serializeVersion = 4; 
    writer.Write(serializeVersion);


    writer.Write(CustomerNumber);
    writer.Write(PopulationRegistryNumber);            
    writer.Write(HomeAddress);
    writer.Write(ZipCode);
    writer.Write(HomeCity);
    if (CustomerCards == null)
        CustomerCards = new List<uint>();            
    writer.Write(CustomerCards);
    writer.Write(HomeAddressObj);

    writer.Write(County);

    // v 2
    writer.Write(Muni);

    // v 4
    if (_AvailableCustomers == null)
        _AvailableCustomers = new List<uint>();
    writer.Write(_AvailableCustomers);
}

因此很容易添加新东西，或者如果愿意的话，可以完全改变序列化.

So its easy to add new things, or change the serialization completely if one chooses to.

但是，我现在出于某种不相关的原因现在想使用JSON =)我目前正在使用 DataContractJsonSerializer ，并且我现在正在寻找一种具有与上面使用FastSerializer相同的灵活性的方法

However, I now want to use JSON for reasons not relevant right here =) I am currently using DataContractJsonSerializer and I am now looking for a way to have the same flexibility I have using the FastSerializer above.

问题是；创建JSON协议/序列化并能够如上所述详细描述序列化的最佳方法是什么，这样我就不会因为另一台机器尚未更新其版本而中断序列化?

So the question is; what is the best way to create a JSON protocol/serialization and to be able to detail the serialization as above, so that I do not break the serialization just because another machine hasn't yet updated their version?

推荐答案

JSON版本控制的关键是始终添加新属性，而不要删除或重命名现有属性.这类似于协议缓冲区如何处理版本控制.

The key to versioning JSON is to always add new properties, and never remove or rename existing properties. This is similar to how protocol buffers handle versioning.

例如，如果您使用以下JSON开头:

For example, if you started with the following JSON:

{
  "version": "1.0",
  "foo": true
}

您想将"foo"属性重命名为"bar"，而不仅仅是重命名.而是添加一个新属性:

And you want to rename the "foo" property to "bar", don't just rename it. Instead, add a new property:

{
  "version": "1.1",
  "foo": true,
  "bar": true
}

由于您永远不会删除属性，因此基于旧版本的客户端将继续运行.这种方法的缺点是JSON会随着时间的流逝而膨胀，您必须继续维护旧的属性.

Since you are never removing properties, clients based on older versions will continue to work. The downside of this method is that the JSON can get bloated over time, and you have to continue maintaining old properties.

为客户明确定义边缘"案例也很重要.假设您有一个名为"fooList"的数组属性. "fooList"属性可以采用以下可能的值:不存在/未定义(该属性在JSON对象中不存在，或者它存在并将其设置为未定义")，空列表，空列表或带有一个或多个值.客户必须了解行为方式，这一点很重要，尤其是在未定义/空/空的情况下.

It is also important to clearly define your "edge" cases to your clients. Suppose you have an array property called "fooList". The "fooList" property could take on the following possible values: does not exist/undefined (the property is not physically present in the JSON object, or it exists and is set to "undefined"), null, empty list or a list with one or more values. It is important that clients understand how to behave, especially in the undefined/null/empty cases.

我还建议您阅读语义版本控制的工作方式.如果在版本号中引入语义版本控制方案，则可以在次要版本边界上进行向后兼容的更改，而可以在主要版本边界上进行重大更改(客户端和服务器都必须在同一主要版本上达成一致) ).尽管这不是JSON本身的属性，但对于传达版本更改时客户端应期望的更改类型很有用.

I would also recommend reading up on how semantic versioning works. If you introduce a semantic versioning scheme to your version numbers, then backwards compatible changes can be made on a minor version boundary, while breaking changes can be made on a major version boundary (both clients and servers would have to agree on the same major version). While this isn't a property of the JSON itself, this is useful for communicating the types of changes a client should expect when the version changes.

这篇关于使用JSON协议处理版本控制的最佳方法是什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！