spark-store/.agents/workflows/refactoring.md

description

description
代码重构流程

工作流说明

此工作流指导如何安全地重构代码。

步骤

1. 识别重构需求

分析代码中的问题：

• 代码重复
• 复杂度过高
• 性能问题
• 可读性差
• 难以维护

2. 制定重构计划

• 确定重构范围
• 列出具体改进点
• 评估影响范围
• 制定测试策略

3. 创建重构分支

git checkout -b refactor/your-refactor

4. 编写测试

如果代码缺少测试，先添加测试：

// src/__tests__/unit/refactorTarget.test.ts
import { describe, it, expect } from "vitest";
import { functionToRefactor } from "@/modules/example";

describe("functionToRefactor", () => {
  it("should maintain existing behavior", () => {
    const result = functionToRefactor(input);
    expect(result).toBe(expected);
  });
});

5. 逐步重构

原则:

• 小步迭代
• 保持测试通过
• 不改变外部行为

示例:

// 重构前
function processApp(app: any) {
  if (app) {
    return {
      name: app.name,
      pkgname: app.pkgname,
      version: app.version,
    };
  }
  return null;
}

// 重构后 - 添加类型
interface App {
  name: string;
  pkgname: string;
  version: string;
}

function processApp(app: App | null): App | null {
  if (!app) return null;

  return {
    name: app.name,
    pkgname: app.pkgname,
    version: app.version,
  };
}

6. 运行测试

# 每次重构后运行测试
npm run test

# 确保所有测试通过
npm run test:all

7. 性能验证

如果重构涉及性能：

# 运行性能测试
npm run test:perf

# 对比重构前后性能

8. 代码审查

自我检查：

• 代码更清晰
• 性能未下降
• 测试全部通过
• 没有引入新问题

9. 更新文档

• 更新相关文档
• 添加注释说明
• 更新 CHANGELOG.md

10. 提交代码

git add .
git commit -m "refactor(scope): describe the refactoring" -s
git push origin refactor/your-refactor

11. 创建 Pull Request

• 说明重构原因
• 展示改进效果
• 提供性能对比（如需要）

12. 代码审查

• 响应审查意见
• 确保所有测试通过
• 合并到 main 分支

重构原则

不改变外部行为

• 保持 API 兼容
• 保持输出一致
• 保持错误处理

小步迭代

• 每次只改一处
• 频繁运行测试
• 及时提交代码

测试驱动

• 先写测试
• 重构代码
• 确保通过

保持简单

• 减少复杂度
• 提高可读性
• 增强可维护性

常见重构模式

提取函数

// 重构前
function processApps(apps: App[]) {
  for (const app of apps) {
    if (app.installed) {
      console.log(app.name + " is installed");
    }
  }
}

// 重构后
function logInstalledApp(app: App) {
  if (app.installed) {
    console.log(`${app.name} is installed`);
  }
}

function processApps(apps: App[]) {
  apps.forEach(logInstalledApp);
}

提取类型

// 重构前
function createDownload(data: any) {
  return {
    id: data.id,
    name: data.name,
    pkgname: data.pkgname,
  };
}

// 重构后
interface DownloadData {
  id: number;
  name: string;
  pkgname: string;
}

function createDownload(data: DownloadData): DownloadItem {
  return {
    id: data.id,
    name: data.name,
    pkgname: data.pkgname,
    status: "queued",
    progress: 0,
    downloadedSize: 0,
    totalSize: 0,
    speed: 0,
    timeRemaining: 0,
    startTime: Date.now(),
    logs: [],
    source: "APM Store",
    retry: false,
  };
}

简化条件

// 重构前
function getStatus(status: string): string {
  if (status === "queued") {
    return "Queued";
  } else if (status === "downloading") {
    return "Downloading";
  } else if (status === "installing") {
    return "Installing";
  } else if (status === "completed") {
    return "Completed";
  } else if (status === "failed") {
    return "Failed";
  } else {
    return "Unknown";
  }
}

// 重构后
const statusMap: Record<string, string> = {
  queued: "Queued",
  downloading: "Downloading",
  installing: "Installing",
  completed: "Completed",
  failed: "Failed",
};

function getStatus(status: string): string {
  return statusMap[status] || "Unknown";
}

注意事项

• ⚠️ 不要在重构中引入新功能
• ⚠️ 不要同时重构多处
• ⚠️ 确保测试覆盖充分
• ⚠️ 保持提交历史清晰
• ⚠️ 及时回退有问题的重构

相关文档

• CONTRIBUTING.md - 贡献指南
• DEVELOPMENT.md - 开发文档
• TESTING.md - 测试文档