Salvo框架中递归结构体导致OpenAPI文档生成栈溢出问题分析

问题背景

在使用Rust的Salvo框架开发Web API时，开发者可能会遇到需要定义递归数据结构的情况。这类数据结构在业务场景中很常见，比如树形结构、评论回复链等。然而，当这些递归结构体与Salvo的OpenAPI文档生成功能结合使用时，却可能导致程序运行时出现栈溢出错误。

问题现象

开发者定义了两个相互引用的结构体：

struct MyFirstStruct {
    field: MySecondStruct,
}

struct MySecondStruct {
    field: Option<Box<MyFirstStruct>>,
}

当使用Salvo的endpoint宏和ToSchema派生宏为这些结构体生成OpenAPI文档时，程序会在运行时崩溃并显示"thread 'main' has overflowed its stack"错误。有趣的是，如果使用handler宏而非endpoint宏，程序则能正常运行。

技术原理分析

问题的根源在于Salvo框架的OpenAPI文档生成机制。当使用ToSchema派生宏时，编译器会为结构体生成to_schema方法的实现，该方法会递归地为所有字段类型调用相应的to_schema方法。

对于递归结构体，这种递归调用会无限进行下去：

1. MyFirstStruct::to_schema调用MySecondStruct::to_schema
2. MySecondStruct::to_schema又调用MyFirstStruct::to_schema
3. 如此循环往复，最终导致调用栈溢出

解决方案探讨

正确的OpenAPI规范应该支持递归引用，通过引用($ref)机制来避免无限递归。理想情况下，生成的OpenAPI文档应该包含如下结构：

{
  "components": {
    "schemas": {
      "MyFirstStruct": {
        "properties": {
          "field": {
            "$ref": "#/components/schemas/MySecondStruct"
          }
        }
      },
      "MySecondStruct": {
        "properties": {
          "field": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MyFirstStruct"
              }
            ],
            "nullable": true
          }
        }
      }
    }
  }
}

临时解决方案

在Salvo框架修复此问题前，开发者可以采取以下临时解决方案：

1. 使用handler宏替代endpoint宏，但这会失去自动生成OpenAPI文档的能力
2. 手动实现ToSchema trait，避免自动生成的无限递归
3. 重构数据结构，尽量避免深度递归

最佳实践建议

在设计递归数据结构时，建议：

1. 合理使用Box或引用类型来避免无限大小的类型
2. 考虑设置递归深度限制
3. 对于复杂的API文档需求，可以部分手动编写OpenAPI规范

总结

递归数据结构在Web开发中很常见，但需要特别注意与API文档生成工具的兼容性。Salvo框架团队已经确认此问题，并计划在后续版本中修复。开发者在使用时应当了解这一限制，并根据项目需求选择合适的解决方案。