批量操作

Batch Operations

Claude Code 提供了多种方式来执行批量操作，从简单的文件重命名到复杂的代码重构，都可以通过自然语言指令高效完成。本章介绍常见的批量操作场景及最佳实践。

批量文件重命名

Batch File Renaming

Claude Code 可以根据规则批量重命名文件，处理复杂的命名转换。

基本用法

bash

# 将 kebab-case 文件名转换为 camelCase
请将 src/components/ 目录下所有 .tsx 文件的文件名
从 kebab-case 转换为 PascalCase。

例如：
  user-profile.tsx → UserProfile.tsx
  nav-bar.tsx → NavBar.tsx

同时更新所有引用这些文件的 import 语句

常见重命名规则

规则	示例	说明
kebab → PascalCase	`my-component` → `MyComponent`	React 组件规范
snake → camelCase	`user_service` → `userService`	JavaScript 规范
添加前缀	`Button` → `AppButton`	命名空间隔离
添加后缀	`user` → `user.model`	类型标识
序号规范化	`img1` → `img001`	统一序号格式

高级重命名示例

bash

# 批量重命名图片文件，添加日期前缀
请将 assets/images/ 目录下所有图片文件按以下规则重命名：
- 格式：YYYY-MM-DD_原文件名
- 日期使用文件的最后修改时间
- 文件名中的空格替换为下划线
- 所有字母转为小写

请先列出将要执行的重命名操作清单，确认后再执行

安全实践

bash

# 重命名前先预览
请列出 src/ 下所有需要重命名的文件及新名称（不要执行）

# 确认后执行
确认无误，请执行重命名，并更新所有相关的 import 语句

批量代码修改

Batch Code Modifications

批量代码修改是 Claude Code 最强大的能力之一，可以在整个代码库中一致地应用变更。

全局 API 模式变更

bash

# 将所有 API 调用从 callback 模式迁移到 async/await
请将 src/ 目录下所有使用 callback 风格的 API 调用
改为 async/await 风格。

例如：
# 修改前
fetch('/api/users', (err, data) => {
  if (err) handleError(err);
  processData(data);
});

# 修改后
try {
  const data = await fetch('/api/users');
  processData(data);
} catch (err) {
  handleError(err);
}

依赖升级适配

bash

# 批量适配 React Router v5 → v6 的 API 变更
请将项目中所有 React Router 的使用从 v5 升级到 v6：

1. <Switch> 替换为 <Routes>
2. <Route component={X}> 替换为 <Route element={<X />}>
3. useHistory() 替换为 useNavigate()
4. history.push() 替换为 navigate()
5. <Redirect> 替换为 <Navigate>

错误处理统一

bash

# 统一全局错误处理模式
请检查 src/services/ 下所有文件，
将分散的 try-catch 错误处理统一为以下模式：

import { handleApiError } from '@/utils/error-handler';

try {
  // 业务逻辑
} catch (error) {
  throw handleApiError(error, 'ServiceName.methodName');
}

类型安全升级

bash

# 将 any 类型替换为具体类型
请查找 src/ 下所有使用 `any` 类型的位置，
根据上下文推断正确的类型并替换。

优先级：
1. 函数参数和返回值
2. 状态变量
3. Props 定义
4. API 响应类型

修改追踪表

操作	影响范围	风险等级	建议
命名规范变更	文件名 + import	中	分批执行，逐步验证
API 模式迁移	业务逻辑层	高	先写测试，再修改
依赖升级适配	框架使用处	高	按路由/组件分批
类型补全	类型声明	低	可一次性执行

批量测试生成

Batch Test Generation

Claude Code 可以为现有代码批量生成测试用例，快速提升测试覆盖率。

为模块生成测试

bash

# 为 services/ 目录下所有文件生成单元测试
请为 src/services/ 目录下的每个文件生成单元测试：

要求：
- 使用 Jest + @testing-library
- 测试文件保存在 src/services/__tests__/ 目录下
- 命名格式：[原文件名].test.ts
- 覆盖所有导出函数
- 包含正常路径和异常路径测试
- mock 外部依赖

测试生成示例

typescript

// src/services/user-service.ts
export async function getUser(id: string): Promise<User> {
  const response = await api.get(`/users/${id}`);
  return response.data;
}

export async function createUser(data: CreateUserInput): Promise<User> {
  validateInput(data);
  const response = await api.post('/users', data);
  return response.data;
}

生成的测试：

typescript

// src/services/__tests__/user-service.test.ts
import { getUser, createUser } from '../user-service';
import { api } from '@/lib/api';

jest.mock('@/lib/api');

describe('UserService', () => {
  describe('getUser', () => {
    it('should return user data for valid id', async () => {
      const mockUser = { id: '1', name: 'Alice' };
      (api.get as jest.Mock).mockResolvedValue({ data: mockUser });

      const result = await getUser('1');

      expect(result).toEqual(mockUser);
      expect(api.get).toHaveBeenCalledWith('/users/1');
    });

    it('should throw on network error', async () => {
      (api.get as jest.Mock).mockRejectedValue(new Error('Network error'));

      await expect(getUser('1')).rejects.toThrow('Network error');
    });
  });

  describe('createUser', () => {
    it('should create user with valid input', async () => {
      const input = { name: 'Bob', email: 'bob@example.com' };
      const mockUser = { id: '2', ...input };
      (api.post as jest.Mock).mockResolvedValue({ data: mockUser });

      const result = await createUser(input);

      expect(result).toEqual(mockUser);
    });

    it('should reject invalid input', async () => {
      const invalidInput = { name: '', email: 'invalid' };

      await expect(createUser(invalidInput)).rejects.toThrow();
    });
  });
});

测试策略配置

测试类型	适用场景	工具
单元测试	纯函数、工具方法	Jest
集成测试	API 路由、数据库操作	Jest + Supertest
组件测试	React/Vue 组件	Testing Library
E2E 测试	完整用户流程	Playwright

批量运行验证

bash

# 生成测试后批量运行验证
请运行所有新生成的测试，修复失败的用例

npm test -- --testPathPattern="src/services/__tests__"

批量文档更新

Batch Document Updates

保持文档与代码同步是常见痛点，Claude Code 可以批量更新文档内容。

API 文档更新

bash

# 根据代码变更批量更新 API 文档
请检查 src/routes/ 下的所有路由文件，
与 docs/api/ 下的对应文档进行对比，
更新所有不一致的地方：

- 新增的路由添加文档
- 删除的路由标记为 deprecated
- 参数变更更新文档
- 更新示例请求和响应

变更日志生成

bash

# 从 Git 提交历史生成 CHANGELOG
请读取最近 50 条 Git commit 记录，
按以下分类生成 CHANGELOG.md：

## [1.2.0] - 2025-03-15

### 新功能（feat）
### 修复（fix）
### 重构（refactor）
### 文档（docs）
### 其他（chore）

注释和 JSDoc 更新

bash

# 为所有导出函数添加 JSDoc 注释
请为 src/utils/ 目录下所有文件的导出函数添加 JSDoc：

要求：
- 描述函数功能
- 标注所有参数类型和说明
- 标注返回值类型和说明
- 标注可能抛出的异常
- 包含使用示例

示例格式：
/**
 * 计算两个日期之间的工作日天数
 *
 * @param startDate - 开始日期
 * @param endDate - 结束日期
 * @returns 工作日天数（不含周末和法定节假日）
 * @throws {InvalidDateError} 如果开始日期晚于结束日期
 *
 * @example
 * const days = getWorkingDays(new Date('2025-03-01'), new Date('2025-03-31'));
 * // returns 21
 */

使用 SubAgent 并行批处理

Parallel Batch Processing with SubAgent

Claude Code 的 SubAgent 功能允许你将大型批处理任务分解为多个并行子任务，大幅提升处理效率。

SubAgent 工作原理

主任务                     子任务（并行执行）
   │
   ├──── SubAgent 1 ────→ 处理 module-a/ 的测试生成
   │
   ├──── SubAgent 2 ────→ 处理 module-b/ 的测试生成
   │
   ├──── SubAgent 3 ────→ 处理 module-c/ 的测试生成
   │
   └──── 汇总结果 ←────── 所有子任务完成

使用场景

场景	并行策略
多模块测试生成	每个模块一个 SubAgent
多文件格式转换	每组文件一个 SubAgent
多语言翻译	每种目标语言一个 SubAgent
多组件样式更新	每个组件一个 SubAgent

提示词示例

bash

# 使用 SubAgent 并行处理
请使用并行方式处理以下任务：

对 src/ 下的每个子目录分别生成单元测试：
- src/services/ → 服务层测试
- src/utils/ → 工具函数测试
- src/components/ → 组件测试
- src/hooks/ → 自定义 Hook 测试

每个目录独立处理，最后汇总测试覆盖率报告

注意事项

bash

# SubAgent 的限制
- 每个 SubAgent 有独立的上下文窗口
- SubAgent 之间不共享状态
- 避免多个 SubAgent 修改同一个文件（可能冲突）
- 控制并行数量，避免资源耗尽

无头模式批处理脚本

Headless Mode Batch Processing Scripts

使用 claude -p 无头模式，可以将 Claude Code 集成到自动化脚本中，实现大规模批处理。

基本语法

bash

# 无头模式执行单个任务
claude -p "请为 src/utils/math.ts 生成单元测试"

# 指定输出格式
claude -p "列出所有 TODO 注释" --output-format json

批处理脚本示例

bash

#!/bin/bash
# batch-generate-tests.sh
# 批量为所有服务文件生成测试

SERVICES_DIR="src/services"
TEST_DIR="src/services/__tests__"

mkdir -p "$TEST_DIR"

for file in "$SERVICES_DIR"/*.ts; do
    filename=$(basename "$file" .ts)

    # 跳过已有测试的文件
    if [ -f "$TEST_DIR/${filename}.test.ts" ]; then
        echo "跳过: $filename（测试已存在）"
        continue
    fi

    echo "生成测试: $filename"
    claude -p "请为 $file 生成完整的单元测试，\
        使用 Jest 框架，保存到 $TEST_DIR/${filename}.test.ts。\
        覆盖所有导出函数的正常和异常路径。" \
        --dangerously-skip-permissions

    echo "完成: $filename"
done

echo "所有测试生成完成！"

# 运行所有测试验证
npm test -- --testPathPattern="$TEST_DIR"

批量代码审查脚本

bash

#!/bin/bash
# batch-review.sh
# 批量审查修改的文件

# 获取所有修改的文件
CHANGED_FILES=$(git diff --name-only HEAD~1)

for file in $CHANGED_FILES; do
    echo "审查: $file"

    claude -p "请审查 $file 的最新修改（git diff HEAD~1），\
        检查以下方面：\
        1. 代码质量和可读性\
        2. 潜在的 bug\
        3. 性能问题\
        4. 安全隐患\
        输出为 JSON 格式" \
        --output-format json > "reviews/${file//\//_}.json"
done

echo "审查完成，结果保存在 reviews/ 目录"

批处理最佳实践

实践	说明
使用 `--dangerously-skip-permissions`	CI 环境中跳过确认提示
指定 `--output-format json`	便于脚本解析结果
错误处理	每个任务添加 `
日志记录	将输出重定向到日志文件
限速控制	添加 `sleep` 避免 API 限流
幂等设计	脚本可重复执行而不产生副作用

输出格式选项

格式	参数	适用场景
纯文本	默认	人工阅读
JSON	`--output-format json`	脚本解析
Stream JSON	`--output-format stream-json`	实时流式处理

综合案例：大规模代码迁移

Comprehensive Case: Large-Scale Code Migration

以下是一个将项目从 JavaScript 迁移到 TypeScript 的批量操作案例。

步骤一：分析项目

bash

claude -p "分析 src/ 目录的文件结构和依赖关系，\
    列出所有 .js 文件及其 import 依赖图"

步骤二：配置 TypeScript

bash

claude -p "为项目初始化 TypeScript 配置，\
    安装必要的依赖，创建 tsconfig.json"

步骤三：批量转换

bash

#!/bin/bash
# migrate-to-typescript.sh

# 按依赖顺序排列的文件列表（叶子节点优先）
FILES=(
    "src/utils/constants.js"
    "src/utils/helpers.js"
    "src/types/index.js"
    "src/services/api.js"
    "src/services/auth.js"
    "src/components/Button.jsx"
    "src/components/Input.jsx"
    "src/pages/Home.jsx"
    "src/pages/Login.jsx"
)

for file in "${FILES[@]}"; do
    echo "迁移: $file"
    claude -p "请将 $file 从 JavaScript 迁移到 TypeScript：\
        1. 重命名为 .ts/.tsx\
        2. 添加类型注解\
        3. 替换 PropTypes 为 TypeScript interface\
        4. 更新所有相关的 import 路径\
        5. 确保没有 TypeScript 编译错误" \
        --dangerously-skip-permissions
done

# 最终类型检查
npx tsc --noEmit

步骤四：验证

bash

# 运行类型检查和测试
npx tsc --noEmit
npm test
npm run build

批量操作 ​

批量文件重命名 ​

基本用法 ​

常见重命名规则 ​

高级重命名示例 ​

安全实践 ​

批量代码修改 ​

全局 API 模式变更 ​

依赖升级适配 ​

错误处理统一 ​

类型安全升级 ​

修改追踪表 ​

批量测试生成 ​

为模块生成测试 ​

测试生成示例 ​

测试策略配置 ​

批量运行验证 ​

批量文档更新 ​

API 文档更新 ​

变更日志生成 ​

注释和 JSDoc 更新 ​

使用 SubAgent 并行批处理 ​

SubAgent 工作原理 ​

使用场景 ​

提示词示例 ​

注意事项 ​

无头模式批处理脚本 ​

基本语法 ​

批处理脚本示例 ​

批量代码审查脚本 ​

批处理最佳实践 ​

输出格式选项 ​

综合案例：大规模代码迁移 ​

步骤一：分析项目 ​

步骤二：配置 TypeScript ​

步骤三：批量转换 ​

步骤四：验证 ​

批量操作

批量文件重命名

基本用法

常见重命名规则

高级重命名示例

安全实践

批量代码修改

全局 API 模式变更

依赖升级适配

错误处理统一

类型安全升级

修改追踪表

批量测试生成

为模块生成测试

测试生成示例

测试策略配置

批量运行验证

批量文档更新

API 文档更新

变更日志生成

注释和 JSDoc 更新

使用 SubAgent 并行批处理

SubAgent 工作原理

使用场景

提示词示例

注意事项

无头模式批处理脚本

基本语法

批处理脚本示例

批量代码审查脚本

批处理最佳实践

输出格式选项

综合案例：大规模代码迁移

步骤一：分析项目

步骤二：配置 TypeScript

步骤三：批量转换

步骤四：验证