Malli项目中Swagger JSON生成的类型顺序问题解析

问题背景

在Malli项目中，当使用:or类型组合器定义包含:nil类型的可选字段时，生成的Swagger JSON会出现有效性问题。具体表现为当:nil类型作为:or组合中的第一个选项时，生成的Swagger规范会变得无效。

问题现象

Malli允许开发者使用类型组合器来定义复杂的类型结构。例如，可以定义一个既可以是整数也可以是空值的字段：

[:days-paid-leave-sick-child {:optional true} [:or [:int {:min 0 :max 30}] :nil]]

这种情况下生成的Swagger JSON是有效的，它会正确地表示为：

days-paid-leave-sick-child:
  type: integer
  format: int64
  minimum: 0
  maximum: 30
  x-anyOf:
    - type: integer
      format: int64
      minimum: 0
      maximum: 30
    - type: 'null'

然而，当:nil类型作为:or组合中的第一个选项时：

[:days-until-sick-leave-notice {:optional true} [:or :nil [:int {:min 1 :max 4}]]]

生成的Swagger JSON就变得无效了：

days-until-sick-leave-notice:
  type: 'null'
  x-anyOf:
    - type: 'null'
    - type: integer
      format: int64
      minimum: 1
      maximum: 4

技术分析

这个问题源于Malli在生成Swagger JSON时对类型组合的处理逻辑。根据JSON Schema规范，type字段的有效值应该是array、boolean、integer、number、object或string之一。'null'虽然在某些Swagger扩展中可能被支持，但不是标准的JSON Schema类型。

当:nil类型出现在:or组合的第一位时，Malli错误地将其作为主类型输出，导致了不符合规范的Swagger文档生成。正确的做法应该是选择第一个非空类型作为基础类型，然后使用anyOf或oneOf来表示类型组合。

解决方案

Malli项目维护者已经确认这是一个bug，并建议修复方向：在生成JSON Schema时，:or类型组合器应该选择第一个非空类型作为基础类型。这意味着：

1. 当处理:or类型组合时，应该跳过:nil类型，选择第一个有效的JSON Schema类型作为主类型
2. 仍然保留所有类型选项（包括:nil）在anyOf或oneOf结构中
3. 确保生成的文档符合JSON Schema规范

对开发者的影响

对于使用Malli生成API文档的开发者，目前可以采取以下临时解决方案：

1. 确保:nil类型总是出现在:or组合的末尾
2. 或者手动调整生成的Swagger文档
3. 等待官方修复并更新到新版本

最佳实践

在使用Malli定义包含可选字段的类型时，建议：

1. 将:nil类型放在:or组合的最后位置
2. 明确指定字段的{:optional true}属性
3. 验证生成的Swagger文档是否符合规范
4. 考虑使用更明确的类型组合方式，如:maybe来表示可选字段

这个问题提醒我们在使用类型系统生成API文档时，需要特别注意类型组合的顺序和规范兼容性。