ASP.NET Extensions项目中AIJsonUtilities对record struct的JSON Schema生成不一致问题解析

在ASP.NET Extensions项目中，AIJsonUtilities.CreateJsonSchema方法在处理record struct和record class时存在不一致的行为，特别是在处理Description特性时表现不同。这个问题涉及到System.Text.Json(简称STJ)序列化器的底层机制，值得开发者深入了解。

问题现象

当使用AIJsonUtilities.CreateJsonSchema方法为record类型生成JSON Schema时，如果类型是record class，无论使用[Description]还是[property: Description]都能正确生成描述信息；但对于record struct，只有显式使用[property: Description]才能正常工作。

示例代码展示了这种不一致性：

record class Person([Description("very cool")] string FirstName, [property: Description("last name")] string LastName);
readonly record struct Pet([Description("不会生效"] string Name, [property: Description("会生效"] int Age);

技术背景

这个问题的根源在于System.Text.Json的构造函数解析算法。对于struct类型，STJ总是选择参数最少的构造函数，而对于struct来说这就是默认构造函数。因此，位置record struct的主构造函数永远不会被纳入合约考虑范围。

对于record class，STJ能够正确识别主构造函数并处理其参数特性；而对于record struct，由于上述机制，STJ会回退到使用init访问器来设置属性值，这就导致了参数上的特性被忽略。

解决方案

目前有两种处理方式：

1. 显式标记JsonConstructor：为主构造函数添加[method:JsonConstructor]特性，强制STJ使用该构造函数

[method:JsonConstructor]
readonly record struct Pet([Description("name")] string Name, int Age);

2. 始终使用property目标：对于record struct，总是显式指定[property: Description]而非简单的[Description]

readonly record struct Pet([property: Description("name")] string Name, int Age);

深入分析

这个行为差异实际上反映了STJ对struct和class处理的基本哲学差异。由于struct有默认构造函数，STJ优先考虑它，而class没有默认构造函数，所以会考虑主构造函数。

这种设计选择早期可能出于性能考虑，因为使用默认构造函数+属性设置可能比调用自定义构造函数更高效。但随着record struct的引入，这种假设可能不再成立。

最佳实践建议

1. 对于需要JSON序列化的record struct，总是显式使用property目标或添加JsonConstructor特性
2. 考虑编写自定义的JSON Schema生成器或扩展方法，以统一处理record struct和record class
3. 在团队内部建立编码规范，统一record struct的特性使用方式

这个问题虽然看起来是API行为不一致，但深入理解后可以帮助开发者更好地掌握STJ的序列化机制，写出更健壮的序列化代码。