OpenAPI TypeScript 项目中的不可变数组类型支持

在 TypeScript 开发中，不可变数据结构对于保证代码的稳定性和可预测性非常重要。OpenAPI TypeScript 项目作为一个能够将 OpenAPI 规范转换为 TypeScript 类型的工具，近期对其不可变类型支持进行了重要增强。

不可变类型的重要性

不可变数据结构是现代前端开发中的重要概念。它们能够：

• 防止意外的数据修改
• 简化状态管理
• 提高代码的可预测性
• 便于调试和追踪数据变化

在 OpenAPI TypeScript 项目中，通过 --immutable 标志可以生成不可变类型，但之前的版本存在一个局限性：虽然对象属性被标记为 readonly，但数组内容仍然可以被修改。

问题分析

考虑以下 OpenAPI 规范片段：

{
  "Test": {
    "type": "object",
    "properties": {
      "Foo": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}

在 7.0.0-next.7 版本中，生成的类型是：

Test: {
    readonly Foo: string[];
}

虽然 Foo 属性本身是只读的，但数组内容仍然可以被修改，例如通过 push()、pop() 等方法。这破坏了真正的不可变性。

解决方案实现

最新版本的 OpenAPI TypeScript 已经解决了这个问题，现在会生成以下两种等效形式之一：

Test: {
    readonly Foo: readonly string[];
}

或者

Test: {
    readonly Foo: ReadonlyArray<string>;
}

这两种形式在 TypeScript 中是等价的，都能确保数组内容不可变。ReadonlyArray 类型移除了所有会修改数组内容的方法，如 push()、pop()、splice() 等，只保留了不会修改原数组的方法如 map()、filter() 等。

技术实现细节

这一改进主要涉及对数组类型生成的修改。在代码层面，主要调整了 schema 对象转换逻辑中处理数组类型的部分。开发者现在可以确保通过 OpenAPI TypeScript 生成的不可变类型是真正不可变的，包括嵌套的数组结构。

使用建议

对于大多数 API 响应数据，推荐使用不可变类型：

1. 它能更好地反映 API 响应的本质（通常不应被修改）
2. 提高代码的稳定性
3. 简化状态管理

对于需要修改数据的场景（如准备请求数据），可以：

1. 使用类型断言（谨慎使用）
2. 创建新的数据结构副本
3. 使用专门的工具库处理不可变数据

总结

OpenAPI TypeScript 的这一改进使得生成的类型更加严格和安全，特别是对于不可变数据结构。开发者现在可以放心地使用生成的类型，确保数据的真正不可变性，从而编写出更健壮、更易维护的代码。