ASP.NET Core扩展库中JSON Schema生成对数据注解的支持增强

在ASP.NET Core的扩展库中，JSON Schema生成功能即将迎来一个重要改进——支持System.ComponentModel.DataAnnotations命名空间下的数据验证特性。这一改进将显著提升开发者在构建AI功能时的参数验证体验。

当前实现现状

目前，当开发者使用记录类型(record)定义工具参数时，即便添加了各种数据验证特性，生成的JSON Schema中也不会包含这些验证约束。例如，对于以下记录定义：

public record SimulationSettings(
    [Range(-1, 10, ErrorMessage = "必须在-1到10之间")]
    decimal MarketROR
);

生成的JSON Schema仅包含基本类型信息：

{
  "marketROR": {
    "type": "number"
  }
}

改进后的预期行为

经过增强后，JSON Schema生成将能够识别并转换常见的数据验证特性：

• [Range(min, max)] → 生成"minimum"和"maximum"属性
• [Required] → 在"required"数组中标记必填字段
• [StringLength(max)] → 添加"maxLength"限制
• [RegularExpression(pattern)] → 包含正则表达式"pattern"
• [EmailAddress] → 设置"format"为"email"

以上面的示例为例，改进后将生成包含完整验证约束的Schema：

{
  "marketROR": {
    "type": "number",
    "minimum": -1,
    "maximum": 10
  }
}

技术实现考量

这一改进将在AIJsonUtilities中实现，保持与现有STJ(System.Text.Json)基础设施的兼容性。未来如果STJ原生支持这一特性，可以轻松移除AIJsonUtilities中的实现而不会影响功能。

开发者价值

这一增强为开发者带来多重好处：

1. 统一验证体验：开发者可以使用熟悉的.NET验证模式，无需学习新的验证机制
2. 开发效率提升：减少手动实现运行时验证的工作量
3. 前端验证支持：客户端可以根据Schema在调用前进行参数验证
4. 自文档化API：Schema本身成为API契约的一部分，提高可读性
5. 框架一致性：与ASP.NET Core、Minimal APIs等框架保持一致的验证体验

实际应用场景

在AI功能开发中，这一改进尤为重要。当LLM(大语言模型)生成工具调用参数时，如果Schema中包含完整的验证约束，LLM可以一次性生成符合要求的JSON，避免因验证失败导致的多次往返交互。这显著提升了AI应用的响应速度和可靠性。

总结

这一改进代表了ASP.NET Core扩展库在AI支持方面的重要进步，它弥合了.NET生态系统标准验证机制与AI工具Schema生成之间的鸿沟，为开发者提供了更加流畅和一致的开发体验。随着AI功能的日益普及，这类改进将帮助.NET开发者更高效地构建智能应用程序。