Cjn-interface

一个强大的VS Code插件，用于根据可自定义模板快速生成接口文件。

✨ 特性

🚀 API 文档自动生成：支持从 Swagger 2.0/3.0、OpenAPI 3.0/3.1、Apifox 自动生成接口代码
⚡ 超高性能：优化后解析速度提升 3-5 倍，内存占用减少 40%
💾 智能缓存：持久化缓存系统，避免重复下载相同文档
🎯 多种内置模板：支持TypeScript API接口、Interface定义、React Hooks等常用模板
🔍 接口过滤：支持按路径、方法、标签过滤接口
🛠️ 完全可定制：通过配置文件自定义您自己的模板
📊 进度可视化：实时进度条和详细统计信息
💡 智能提示：在生成过程中提供友好的交互式提示

🆕 最新优化（v0.3.0）

性能提升

⚡ 解析速度提升 3-5倍（使用缓存时可达 15倍）
💾 内存占用减少 40%
🚀 支持并发处理：可配置并发数，默认5个并发请求
📦 流式生成：支持超大型API文档（数千个接口）

新增功能

✅ 持久化缓存：API文档缓存24小时，避免重复下载
✅ 接口过滤：按路径、HTTP方法、标签过滤接口
✅ 进度条：实时显示生成进度
✅ 性能统计：详细的时间和速度统计
✅ 增强日志：可选的详细日志模式

📖 查看完整优化说明：OPTIMIZATION-GUIDE.md

📦 安装

方式一：安装 VS Code 扩展（推荐）

在VS Code中打开扩展面板（Ctrl+Shift+X 或 Cmd+Shift+X）
搜索 "Cjn-interface"
点击安装

方式二：直接使用终端命令

无需下载任何文件！ 安装扩展后，在你的项目中直接运行：

# 增强版命令（推荐）
npm run create-config:enhanced   # 创建配置
npm run generate:enhanced        # 生成接口

# 标准版命令
npm run create-config            # 创建配置
npm run generate                 # 生成接口

如果提示命令不存在，说明脚本还未安装到项目中，请先按下面步骤操作：

方式三：手动复制脚本文件

从扩展安装目录复制脚本到你的项目：

Mac/Linux:

# 复制增强版脚本（推荐）
cp ~/.vscode/extensions/cjn.cjn-interface-*/scripts/create-config-enhanced.js ./scripts/
cp ~/.vscode/extensions/cjn.cjn-interface-*/scripts/generate-from-config-enhanced.js ./scripts/

# 或复制标准版
cp ~/.vscode/extensions/cjn.cjn-interface-*/scripts/create-config.js ./scripts/
cp ~/.vscode/extensions/cjn.cjn-interface-*/scripts/generate-from-config.js ./scripts/

Windows (PowerShell):

# 复制增强版脚本（推荐）
copy $env:USERPROFILE\.vscode\extensions\cjn.cjn-interface-*\scripts\create-config-enhanced.js .\scripts\
copy $env:USERPROFILE\.vscode\extensions\cjn.cjn-interface-*\scripts\generate-from-config-enhanced.js .\scripts\

# 或复制标准版
copy $env:USERPROFILE\.vscode\extensions\cjn.cjn-interface-*\scripts\create-config.js .\scripts\
copy $env:USERPROFILE\.vscode\extensions\cjn.cjn-interface-*\scripts\generate-from-config.js .\scripts\

然后在 package.json 中添加：

{
  "scripts": {
    "create-config": "node scripts/create-config-enhanced.js",
    "generate": "node scripts/generate-from-config-enhanced.js"
  },
  "devDependencies": {
    "axios": "^1.6.0",
    "swagger-parser": "^10.0.3"
  }
}

安装依赖：

# 使用 npm
npm install

# 使用 pnpm
pnpm install

# 使用 yarn
yarn install

🚀 使用方法

🔥 方式一：VS Code 命令（最简单）

无需任何配置，开箱即用！

安装 Cjn-interface 扩展
按 Cmd+Shift+P (Mac) 或 Ctrl+Shift+P (Windows/Linux) 打开命令面板
选择以下命令：
- 创建接口生成配置文件 - 创建 .cjn-interface.json
- 从配置文件批量生成接口 - 批量生成所有配置的接口
- 从 API 文档生成接口 - 单次生成某个 API 的接口

⚡ 方式二：终端命令（高效批量）

适合 CI/CD 和自动化场景。

第一步：复制脚本到项目

# Mac/Linux
mkdir -p scripts
cp ~/.vscode/extensions/cjn.cjn-interface-*/scripts/create-config-enhanced.js ./scripts/
cp ~/.vscode/extensions/cjn.cjn-interface-*/scripts/generate-from-config-enhanced.js ./scripts/

# Windows (PowerShell)
mkdir scripts -Force
copy $env:USERPROFILE\.vscode\extensions\cjn.cjn-interface-*\scripts\create-config-enhanced.js .\scripts\
copy $env:USERPROFILE\.vscode\extensions\cjn.cjn-interface-*\scripts\generate-from-config-enhanced.js .\scripts\

在 package.json 中添加：

{
  "scripts": {
    "create-config": "node scripts/create-config-enhanced.js",
    "generate": "node scripts/generate-from-config-enhanced.js"
  },
  "devDependencies": {
    "axios": "^1.6.0",
    "swagger-parser": "^10.0.3"
  }
}

安装依赖（支持多种包管理器）：

npm install    # 使用 npm
pnpm install   # 使用 pnpm
yarn install   # 使用 yarn
bun install    # 使用 bun

第二步：创建配置文件

运行命令创建配置：

# 交互式创建（推荐）
npm run create-config

# 快速创建示例配置
npm run create-config -- --quick

# 详细模式
npm run create-config -- --verbose

交互式输入 API 文档配置：

🚀 Cjn-interface 配置文件创建工具

请输入 API 文档配置（输入空行完成）：

--- API 文档 [#1](https://github.com/543369/cjn-interface/issues/1) ---
API 文档地址 (必填，直接回车结束): https://api.example.com/v2/api-docs
输出目录 (可选，默认 api): api/backend
接口组名称 (可选): backend

--- API 文档 [#2](https://github.com/543369/cjn-interface/issues/2) ---
API 文档地址 (必填，直接回车结束): [直接回车完成]

✅ 配置文件已创建: .cjn-interface.json

或手动创建 .cjn-interface.json 文件：

```json { "apiDocs": [ { "url": "https://petstore.swagger.io/v2/swagger.json", "outputDir": "api/petstore", "name": "petstore" }, { "url": "http://your-api.com/v2/api-docs", "outputDir": "api/backend", "name": "backend" }, { "url": "https://s.apifox.cn/your-project", "outputDir": "api/apifox", "name": "apifox" } ] } ```

配置说明：

`url`: API 文档地址（必填）
`outputDir`: 输出目录，相对于项目根目录（可选，默认 `api`）
`name`: 接口组名称，用作文件名前缀（可选）

第三步：批量生成接口

# 如果已复制脚本到项目中
node scripts/generate-from-config.js

# 或使用 npm script
npm run generate

输出效果：

🚀 Cjn-interface 批量生成工具
标准生成
npm run generate

# 详细模式（显示进度和统计）
npm run generate -- --verbose

# 禁用缓存（强制重新下载）
npm run generate -- --no-cache

# 指定配置文件
npm run generate -- --config=prod-config.json
[1/2] 处理: petstore
📡 正在获取 API 文档: https://petstore.swagger.io/v2/swagger.json
  ✓ 找到 20 个接口
  ✓ 创建目录: api/petstore
  ✓ 生成 20 个接口文件到 api/petstore

[2/2] 处理: backend
📡 正在获取 API 文档: http://your-api.com/v2/api-docs
  ✓ 找到 15 个接口
  ✓ 生成 15 个接口文件到 api/backend

✅ 批量生成完成！成功处理 2/2 个 API 文档

输出效果：

🚀 Cjn-interface 批量生成工具

📄 读取配置文件: .cjn-interface.json

📦 共有 2 个 API 文档需要处理

[1/2] 📡 petstore
    ✓ 找到 20 个接口
    🔨 生成接口文件...
    [████████████████████] 100% (20/20)
    ✅ 成功生成 20 个文件到 api/petstore
    ⏱️  耗时: 2.5s

[2/2] 📡 backend
    ✓ 找到 15 个接口
    🔨 生成接口文件...
    [████████████████████] 100% (15/15)
    ✅ 成功生成 15 个文件到 api/backend
    ⏱️  耗时: 1.8s

==================================================
📊 生成统计
==================================================
  API 文档数: 2/2
  接口总数:   35
  生成文件:   35
  总耗时:     4.3s
  平均速度:   8.14 接口/秒
==================================================

✅ 所有 API 文档处理完成！

支持的文档格式：

✅ Swagger 2.0/3.0
✅ OpenAPI 3.0/3.1
✅ Apifox 分享链接

支持的包管理器：

✅ npm
✅ pnpm
✅ yarn
✅ bun

📝 方式三：使用模板（手动输入）

命令面板

按 `Cmd+Shift+P` 打开命令面板
输入 "生成接口文件"
选择要使用的模板
按提示输入变量值
接口文件将在当前工作区根目录生成

右键菜单

在资源管理器中右键点击文件夹
选择 "生成接口文件"
选择模板并输入变量
文件将在所选文件夹中生成

📋 内置模板

1. TypeScript API接口

生成包含请求和响应类型定义的API调用函数：

```typescript export interface GetUserRequest { } export interface GetUserResponse { } export function getUserApi(data: GetUserRequest): Promise { } ```

2. TypeScript Interface

生成TypeScript接口定义及相关类型：

```typescript export interface User { } export type UserPartial = Partial; export type UserRequired = Required; ```

3. React Hooks接口

生成React Hook用于API调用：

```typescript export function useGetUser(params: GetUserRequest) { const [data, setData] = useState<GetUserResponse | null>(null); // ... } ```

⚙️ 自定义模板

在设置中配置

打开VS Code设置（`Ctrl+,` 或 `Cmd+,`）
搜索 "Cjn-interface"
点击 "在settings.json中编辑"
添加自定义模板配置

配置示例

```json { "interfaceGenerator.templates": [ { "name": "自定义模板", "description": "我的自定义接口模板", "fileName": "{{name}}.service", "fileExtension": ".ts", "template": "export class {{Name}}Service {\n // TODO: 实现服务方法\n}\n", "variables": [ { "name": "name", "description": "服务名称（小驼峰）", "default": "user" }, { "name": "Name", "description": "服务名称（大驼峰）", "default": "User" } ] } ] } ```

模板配置说明

name: 模板名称（在选择模板时显示）
description: 模板描述
fileName: 文件名模板，支持 `{{变量名}}` 占位符
fileExtension: 文件扩展名（如 `.ts`, `.js`, `.jsx`）
template: 模板内容，支持 `{{变量名}}` 占位符
variables: 变量列表
- name: 变量名
- description: 变量描述（用于输入提示）
- default: 默认值（可选）

🎮 命令

VS Code 命令面板

Cjn-interface: 从配置文件批量生成接口 - 从配置文件批量生成所有接口（推荐）
Cjn-interface: 从 API 文档生成接口 - 从 Swagger/OpenAPI/Apifox 生成接口
Cjn-interface: 创建接口生成配置文件 - 在 VS Code 中创建配置文件
Cjn-interface: 生成接口文件 - 根据模板手动生成接口文件
Cjn-interface: 打开模板配置 - 打开模板配置设置
Cjn-interface: 重新加载模板 - 重新加载模板配置

终端命令（需先复制脚本）

# 增强版（推荐）
npm run create-config      # 交互式创建配置
npm run create-config -- --quick  # 快速创建示例
npm run generate           # 批量生成接口
npm run generate -- --verbose  # 详细模式
npm run generate -- --no-cache  # 禁用缓存

🔧 配置选项

配置项	类型	默认值	描述
`interfaceGenerator.apiDocumentUrl`	string	`""`	API 文档地址（支持 Swagger/OpenAPI/Apifox）
`interfaceGenerator.templates`	array	`[]`	自定义模板配置数组

💡 使用技巧

API 文档生成（推荐）：
- 配置好 API 文档地址后，可快速批量生成接口
- 生成的代码包含完整的类型定义和请求函数
- 支持多选接口，一次性生成多个文件
- Apifox 用户直接使用分享链接即可
ES 模块项目：
- 生成的脚本使用 ES 模块格式，与现代项目兼容
- CommonJS 项目使用 .mjs 扩展名或配置 "type": "module"
变量命名约定：
- 小驼峰：`{{name}}` → `getUser`
- 大驼峰：`{{Name}}` → `GetUser`
- 全大写：`{{NAME}}` → `GET_USER`
模板组织：建议为不同项目或团队创建不同的模板集
文件命名：使用变量让文件名动态生成，如 `{{name}}.api.ts`

🐛 问题反馈

如果您遇到任何问题或有功能建议，请在 GitHub Issues 中提交。

常见问题

下载 404 错误：查看下载故障排除指南
ES 模块错误（require is not defined）：将文件重命名为 .mjs 或在 package.json 添加 "type": "module"
网络问题：使用本地脚本或备用 CDN，详见故障排除指南

�� 更新日志

查看 CHANGELOG.md 了解版本更新历史。

📄 许可证

MIT

🤝 贡献

Q: 找不到 npm 命令？ A: 请先按照安装步骤复制脚本文件到项目中，并在 package.json 添加 scripts 配置。

Q: 扩展目录在哪里？ A:

Mac/Linux: ~/.vscode/extensions/
Windows: %USERPROFILE%\.vscode\extensions\

使用 ls ~/.vscode/extensions/ | grep cjn 查找扩展目录。

Q: 支持哪些包管理器？ A: 支持 npm、pnpm、yarn、bun。安装依赖时使用对应命令即可。

Q: 可以不用终端命令吗？ A: 可以！直接在 VS Code 中使用命令面板（Cmd+Shift+P），选择 "从配置文件批量生成接口"。

Q: GitHub 文件无法访问？ A: 无需从 GitHub 下载。安装 VS Code 扩展后，直接从扩展目录复制脚本到项目中即可。

Enjoy coding! 🎉