Orval项目中readonly字段在mutation函数输入类型缺失问题分析

在Orval项目6.25.0版本中，发现了一个关于OpenAPI规范中readonly字段处理的bug。这个问题会导致在生成mutation函数时，输入类型不正确，从而影响API调用的正常使用。

问题现象

当使用Orval根据OpenAPI规范生成客户端代码时，如果规范中定义了包含readonly属性的对象作为mutation操作的输入参数，生成的TypeScript类型会出现问题。具体表现为：

1. 输入参数的类型会被推断为空对象{}
2. 实际调用mutation函数时，无法正确传递参数
3. 类型检查失效，可能导致运行时错误

技术背景

OpenAPI规范允许通过readOnly标记来指定某些属性是只读的。这些属性通常用于响应数据，表示它们不应该出现在请求体中。Orval在处理这些标记时，会使用NonReadonly<T>类型工具来过滤掉readonly属性，只保留可写属性作为mutation函数的输入类型。

问题根源

通过分析发现，问题出在NonReadonly<T>类型工具的实现上。当前实现无法正确处理嵌套对象中的readonly属性，导致整个类型被推断为空对象。具体来说：

1. 当对象包含readonly数组属性时，类型转换失败
2. 类型工具没有正确处理嵌套对象的readonly标记
3. 类型推断过于激进，导致所有属性都被过滤

解决方案

修复这个bug需要改进NonReadonly<T>类型工具的实现，确保它能够：

1. 正确识别和保留非readonly属性
2. 递归处理嵌套对象中的属性
3. 保持数组类型的完整性
4. 为readonly属性生成正确的排除逻辑

影响范围

这个bug会影响所有使用以下特性的项目：

1. 在OpenAPI规范中定义了readonly属性
2. 这些readonly属性出现在mutation操作的输入类型中
3. 使用Orval生成的客户端代码进行API调用

最佳实践

为了避免类似问题，建议：

1. 明确定义哪些属性应该出现在请求体和响应体中
2. 避免在mutation输入类型中使用readonly属性
3. 定期更新Orval版本以获取最新的bug修复
4. 对生成的类型进行测试验证

总结

Orval作为强大的OpenAPI客户端代码生成工具，在处理readonly属性时出现的这个bug虽然影响范围有限，但对于依赖它的项目来说可能造成严重问题。理解这个问题的本质有助于开发者更好地设计API规范，并在遇到类似问题时能够快速定位和解决。