Biz 框架升级助手
帮助开发者从 biz-framework 平滑升级到 biz-core 的 VS Code 智能插件。
✨ 功能特性
- 一键代码升级 - 自动化 Git 工作流，支持 test/inte 环境的快速升级流程
- 实时检测 - 自动扫描代码中的废弃 API 和过时写法，支持简单模式匹配和 AST 复杂规则
- 智能提示 - 悬停显示详细的升级指南和代码示例
- 快速修复 - 一键自动替换为新框架写法，支持基于 AST 的智能转换
- 自定义规则 - 支持多来源配置、自定义规则文件和规则级别的忽略模式
- 配置热更新 - 修改配置文件后自动重新加载规则，无需重启
📦 插件安装
在 VS Code 扩展市场搜索 biz框架升级助手 或通过命令行安装：
code --install-extension GlimoraX.biz-upgrade-helper
在 Cursor / VS Code / Trae / Kiro 等 IDE 中可以通过以下方式安装：
Extensions → Install from VSIX → 选择文件: .upgrade/biz-upgrade-helper-X.X.X.vsix
🚀 使用方法
基本使用
- 在装了插件的IDE上打开app-service-plus项目
- 插件会自动扫描并标记需要升级的代码（支持 JavaScript、TypeScript、JSX、TSX、Vue、Svelte）
- 悬停在标记处查看升级指南和代码示例
cmd+shift+P 使用Helper命令进行一键代码升级- 点击灯泡图标或按
Ctrl+. 使用快速修复
命令介绍
Biz Helper: 一键代码升级 - 启动自动化升级流程（test/inte 环境）Biz Helper: 继续升级流程 - 在解决冲突或完成手动操作后继续升级流程
一键代码升级功能说明
该功能提供了完整的 Git 工作流自动化，适用于 test/inte 环境的快速升级：
- 前置检查 - 自动检查 Git 仓库状态和工作区变更
- 环境选择 - 选择 test 或 inte 环境
- 分支管理 - 自动创建/切换特性分支，合并源分支代码
- 冲突处理 - 自动检测合并冲突，暂停流程等待手动解决
- 升级脚本 - 在集成终端中执行升级脚本，保持彩色输出
- 单测验证 - 可选运行单元测试验证代码正确性
- 代码提交 - 自动提交升级变更到本地特性分支
- 分支合并 - 合并特性分支到目标分支并推送
升级流程示例：
- Test 环境：
源码分支(plus-upgrade-test) → 本地特性分支 → 目标分支（test-220915 ）
- Inte 环境：
源码分支(plus-upgrade-sprint） → 本地特性分支 → 目标分支（sprint-251225）
特性分支命名格式：upgrade/{env}-{suffix}（如：upgrade/test-250918）
升级过程中的冲突解决技巧
- 遇见voucherconfig文件 先采用当前分支，然后将app-service源码copy出来，后续通过脚本升级即可
- 遇见新写法的冲突一般采用当前，如冲突带有bizSchemaManager、bizApplication关键字
- 出现引用冲突的可以使用做简单对比，一般可以先采用新分支的，后续通过脚本升级
⚙️ 配置
配置文件
插件支持多个配置来源，按以下优先级加载（后面的会合并前面的）：
.upgrade/rules.json - 项目级规则文件upgrade.config.json - 项目根目录配置文件- VS Code 设置中的
bizFrameworkUpgrade.rules
配置示例
在项目根目录创建 upgrade.config.json：
{
"version": "1.0.0",
"frameworkName": {
"old": "biz-framework",
"new": "biz-core"
},
"ignorePatterns": ["**/node_modules/**", "**/dist/**", "**/*.test.ts"],
"customRules": [".upgrade/custom-rules.js"],
"rules": [
{
"id": "import-statement-change",
"severity": "error",
"category": "api",
"oldPattern": "from ['\"]biz-framework['\"]",
"newPattern": "from 'biz-core'",
"message": "请使用新的导入路径 'biz-core'",
"hoverMessage": "biz-framework 已升级为 biz-core",
"upgradeGuide": "将所有 import ... from 'biz-framework' 更改为 import ... from 'biz-core'",
"quickFix": {
"title": "更新为 biz-core 导入",
"transform": "code.replace(/from ['\"]biz-framework['\"]/g, \"from 'biz-core'\")"
},
"examples": {
"before": "import { Component } from 'biz-framework';",
"after": "import { Component } from 'biz-core';"
},
"ignorePatterns": ["**/legacy/**", "**/*.spec.ts"]
}
]
}
规则定义
每个规则支持以下字段：
id - 规则唯一标识severity - 严重程度：error | warning | infocategory - 分类：api | pattern | structure | lifecycleoldPattern - 旧代码模式（字符串或正则表达式）newPattern - 新代码模式（可选）astMatcher - AST 匹配函数（用于复杂规则，需在自定义规则文件中定义）message - 诊断消息hoverMessage - 悬停提示消息upgradeGuide - 升级指南quickFix - 快速修复配置
title - 修复操作标题transform - 转换表达式（字符串，使用 code 变量）
examples - 代码示例（before 和 after）ignorePatterns - 规则级别的忽略模式（支持 glob 模式）
规则级别的忽略模式
每个规则可以通过 ignorePatterns 字段指定忽略检查的文件或文件夹：
- 支持 glob 模式匹配
- 相对于项目根目录
- 常用模式：
**/legacy/** - 忽略所有 legacy 文件夹**/*.test.ts - 忽略所有测试文件src/old-code/** - 忽略特定目录**/vendor/** - 忽略第三方代码
自定义规则文件
可以通过 customRules 字段引用 JavaScript 模块文件，定义复杂的 AST 匹配规则：
// .upgrade/custom-rules.js
module.exports = [
{
id: "complex-ast-rule",
severity: "warning",
category: "pattern",
astMatcher: (node, context) => {
// 使用 AST 节点和上下文进行复杂匹配
return (
node.type === "CallExpression" &&
node.callee.name === "deprecatedMethod"
);
},
message: "检测到废弃方法调用",
hoverMessage: "此方法已废弃",
upgradeGuide: "使用新方法替代",
quickFix: {
title: "替换为新方法",
transform: (code) => code.replace(/deprecatedMethod/g, "newMethod"),
},
},
];
VS Code 设置
{
"bizFrameworkUpgrade.enabled": true,
"bizFrameworkUpgrade.autoScan": true,
"bizFrameworkUpgrade.showDashboardOnStartup": false,
"bizFrameworkUpgrade.rulePaths": [
".upgrade/rules.json",
"upgrade.config.json"
]
}
🔧 技术实现
- AST 分析 - 基于 Babel 解析器，支持 JavaScript、TypeScript、JSX、TSX
- 实时检测 - 监听文件变更，自动重新扫描
- 智能修复 - 基于 AST 上下文进行精确的代码转换
- Git 集成 - 完整的 Git 工作流自动化，支持冲突检测和处理
📝 License
MIT
