Azure SDK for Python 中模型序列化行为的重大变更分析

在 Azure SDK for Python 的 azure-mgmt-avs 模块从 Swagger 迁移到 TypeSpec 的过程中，我们发现模型序列化行为发生了三个重要变化，这些变化可能会对现有代码产生兼容性问题。

序列化参数名称变更

第一个变化是序列化方法参数名称的改变。在旧版本中，我们使用 keep_readonly 参数来控制是否保留只读属性，而在新版本中，这个参数被更名为 exclude_readonly，并且其含义也发生了反转。

旧版本示例：

model.as_dict(keep_readonly=False)  # 不保留只读属性

新版本示例：

model.as_dict(exclude_readonly=True)  # 排除只读属性

这种变化虽然容易理解，但需要开发者在升级时注意修改所有相关代码。

键名格式变化

第二个变化是字典键名的格式从 snake_case 变为了 camelCase。这种变化是为了更好地与 REST API 的命名约定保持一致。

旧版本输出：

{'linked_cloud': 'hello'}

新版本输出：

{'linkedCloud': 'hello'}

这种变化虽然直观，但会影响所有依赖键名格式的代码逻辑。

层次结构表示方式变化

第三个也是最显著的变化是模型层次结构的表示方式。旧版本会隐藏层次结构，使输出与模型定义保持一致，而新版本则严格遵循 REST API 的层次结构。

旧版本输出：

{'linked_cloud': 'hello'}

新版本输出：

{'properties': {'linkedCloud': 'hello'}}

这种变化影响最大，因为它改变了整个数据结构，所有依赖该结构的代码都需要相应调整。

迁移建议

对于这些变化，开发者可以采取以下策略：

1. 对于参数名称变更，全局搜索替换 keep_readonly 为 exclude_readonly 并反转布尔值
2. 对于键名格式变化，考虑使用辅助函数进行键名转换
3. 对于层次结构变化，可能需要重构数据处理逻辑，或者考虑在 SDK 中提供兼容层

这些变化虽然带来了迁移成本，但从长远来看，它们使 SDK 行为更加一致和可预测，特别是与 REST API 保持严格一致，减少了开发者的认知负担。