COMPATIBILITY.md

向后兼容性说明

✅ 完全兼容零配置使用方式

所有原有的零配置使用方式都完全兼容，行为与之前完全一致。

兼容性验证

场景 1：纯命令行（无配置文件）

# 原有用法，完全兼容
openapi-typescript-cli -f ./openapi.json -n api
openapi-typescript-cli -u http://localhost:8080/v3/api-docs -n api
openapi-typescript-cli -f ./openapi.json -m ./middleware.js

行为：

• ✅ 自动查找配置文件（如果不存在，静默跳过）
• ✅ 使用命令行参数
• ✅ 输出到当前目录（process.cwd()）
• ✅ 与之前行为完全一致

场景 2：有配置文件，但使用命令行覆盖

# 即使有配置文件，命令行参数优先级更高
openapi-typescript-cli -f ./openapi.json -n customName

行为：

• ✅ 加载配置文件
• ✅ 命令行参数覆盖配置文件
• ✅ 最终使用命令行参数的值

场景 3：纯配置文件（零命令行参数）

# 只有配置文件，无命令行参数
openapi-typescript-cli

行为：

• ✅ 自动查找并加载配置文件
• ✅ 使用配置文件中的所有设置
• ✅ 如果配置文件不存在，会提示错误（需要至少提供 input/url）

默认行为保持不变

配置项	默认值	说明
name	'index'	与之前完全一致
output	process.cwd()	与之前完全一致（当前目录）
apifile	-	必须通过命令行或配置文件提供
url	-	必须通过命令行或配置文件提供

关键兼容性保证

1. 配置文件查找是静默的

   • 如果不存在配置文件，不会输出任何日志
   • 不会影响性能（只检查文件是否存在）

2. 命令行参数优先级最高

   • 即使有配置文件，命令行参数会覆盖配置
   • 原有用法完全不受影响

3. 默认值保持不变

   • name: 'index'
   • output: process.cwd()
   • 所有默认行为与之前版本一致

4. 输出目录处理

   • 默认输出到当前目录（与之前一致）
   • 只有明确指定 -o 或配置文件中设置 output 时才会创建新目录

迁移建议

从零配置迁移到配置文件

之前：

openapi-typescript-cli -u http://localhost:8080/v3/api-docs -n api -m ./middleware.js

现在（可选）：

// openapi-typescript-cli.config.js
module.exports = {
  url: 'http://localhost:8080/v3/api-docs',
  name: 'api',
  middleware: './middleware.js',
};

# 然后只需运行
openapi-typescript-cli

或者继续使用命令行（完全兼容）：

openapi-typescript-cli -u http://localhost:8080/v3/api-docs -n api -m ./middleware.js

总结

✅ 100% 向后兼容

• 所有原有用法都正常工作
• 默认行为完全一致
• 配置文件是可选的增强功能
• 不会破坏任何现有工作流