# magic-api-compare

**Repository Path**: hotspring/magic-api-compare

## Basic Information

- **Project Name**: magic-api-compare
- **Description**: magic-api-compare-tool 是一个用于比较  magic-api 不同版本脚本目录的本地 Web 工具。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-13
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# magic-api-compare-tool

## 项目介绍
`magic-api-compare-tool` 是一个用于比较 `magic-api` 不同版本脚本目录的本地 Web 工具。

核心能力：
- 对比两个本地目录（版本 A / 版本 B）
- 左侧树形展示文件状态（新增/删除/修改/相同）
- 右侧逐行高亮 diff（新增绿色、删除红色）
- 支持状态筛选（全部、仅修改、仅新增、仅删除、仅相同）
- 支持按文件类型使用不同对比规则

## 当前对比规则

### 1. `group.json`
仅比较以下字段：
- `name`
- `type`
- `parentId`
- `path`

其他字段不参与比较。

### 2. `*.ms`
仅比较以下字段：
- `script`
- `path`
- `method`
- `requestBody`

且对 `script` 执行注释忽略：
- 忽略 `//` 注释行
- 忽略 `#` 注释行
- 忽略 `/* ... */` 块注释

### 3. 其他文件
按普通文本比较。

## 项目结构

```text
magic-api-compare/
├─ public/
│  ├─ index.html        # 前端页面
│  ├─ style.css         # 前端样式
│  └─ app.js            # 前端逻辑（树、筛选、逐行diff）
├─ src/
│  ├─ server.js         # HTTP 服务与 API
│  ├─ compare.js        # 目录扫描与文件对比主流程
│  ├─ rules.js          # 文件规则归一化
│  └─ config.js         # 端口配置读取
├─ test/
│  ├─ rules.test.js     # 规则测试
│  ├─ diff.test.js      # 行级diff测试
│  └─ config.test.js    # 配置读取测试
├─ config.json          # 运行配置
└─ package.json
```

## 开发说明

### 环境要求
- Node.js 18+
- npm
- Windows（当前已验证）

### 安装依赖

```bash
npm install
```

### 本地开发运行

```bash
npm start
```

启动后访问：
- `http://localhost:3000`（默认端口）

### 运行测试

```bash
npm test
```

## 配置说明

默认读取项目根目录 `config.json`。

示例：

```json
{
  "port": 3000
}
```

端口规则：
1. 如存在 `config.json` 且有 `port`，使用该端口
2. 如未配置或配置文件不存在，默认 `3000`
3. 若端口被占用，程序报错退出（不会自动切换）

可选：通过环境变量指定配置文件路径：
- `MAGIC_COMPARE_CONFIG=<自定义配置文件路径>`

## 使用说明

1. 打开工具页面
2. 在“左目录”输入版本 A 路径
3. 在“右目录”输入版本 B 路径
4. 点击“开始比较”
5. 在左侧树中点击文件查看明细
6. 使用筛选按钮定位状态文件

说明：
- 输入框路径提示已隐藏具体样例路径
- 明细标题仅显示文件名，不显示完整路径

## 打包说明（exe）

项目使用 `pkg` 打包：

```bash
npm run build:exe
```

输出目录：
- `dist/magic-api-compare-tool.exe`

说明：
- 打包目标：`node18-win-x64`
- 已包含 `public/**/*` 静态资源

## 常见问题

### 1) 启动提示端口占用
修改 `config.json` 中 `port` 为其他未占用端口，或释放当前端口。

### 2) 某些文件无法按规则比较
如果文件内容格式异常（如 JSON 非法），系统会回退为文本比较。

### 3) 比较结果与预期不一致
请确认：
- `*.ms` 仅比较 `script/path/method/requestBody`
- `group.json` 仅比较 `name/type/parentId/path`

## 后续可扩展方向
- 支持目录选择器（避免手填路径）
- 支持导出比较报告（HTML/JSON）
- 支持 zip 文件输入
- 支持差异关键字搜索