使用 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 对象中，或者它存在并设置为 "；undefined")、null、空列表或具有一个或多个值的列表.让客户了解行为方式非常重要，尤其是在未定义/空/空的情况下.

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屋！