Claude之父AI编程技巧九：代码格式化工具——让AI代码产出即规范化

引言

大语言模型生成代码有一个固有的挑战：由于其"概率抽卡"的工作机制，生成的代码在格式上可能存在不一致——JSON可能缺少逗号，XML可能标签不匹配，代码缩进可能不统一。虽然这些"小问题"不会影响代码的逻辑正确性，但它们会影响代码的可读性、可维护性和专业性。

在实际使用中，我们可以结合Claude Code与各种代码格式化工具来确保生成的代码始终保持整洁和规范。本文将深入探讨如何配置和使用这些工具，让Claude Code生成的代码始终保持整洁和规范。

理解格式化工具

什么是代码格式化？

代码格式化是自动调整代码格式的过程，包括：

1. 缩进和空格：统一代码缩进、括号对齐
2. 换行：合理的换行和空行
3. 引号：统一使用单引号或双引号
4. 分号：添加或删除分号
5. 注释格式化：调整注释位置和格式

为什么需要格式化？

好处	描述
一致性	所有代码遵循相同的格式标准
可读性	代码更容易阅读和理解
协作	团队成员更容易协作
质量	统一的代码风格提升专业性
维护性	降低维护成本

常用格式化工具

JavaScript/TypeScript

Prettier

Prettier是JavaScript、TypeScript、HTML、CSS等的代码格式化工具：

# 安装
npm install --save-dev prettier

# 格式化单个文件
npx prettier --write src/index.ts

# 格式化整个项目
npx prettier --write "src/**/*.{ts,tsx,js,jsx}"

# 检查格式（不修改）
npx prettier --check src/index.ts

配置Prettier

创建.prettierrc文件：

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false
}

创建格式化脚本

#!/bin/bash
# scripts/format.sh

echo "格式化代码..."

# 格式化TypeScript和JavaScript
npx prettier --write "src/**/*.{ts,tsx,js,jsx}"

# 格式化JSON
npx prettier --write "*.json"

# 格式化Markdown
npx prettier --write "*.md"

# 格式化CSS
npx prettier --write "src/**/*.{css,scss,less}"

echo "格式化完成！"

ESLint自动修复

# 安装ESLint
npm install --save-dev eslint

# 自动修复
npx eslint src --ext .ts,.tsx,.js,.jsx --fix

# 或者结合Prettier
npm install --save-dev eslint-config-prettier eslint-plugin-prettier

# 在.eslintrc.json中配置
{
  "extends": [
    "eslint:recommended",
    "prettier"
  ],
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error"
  }
}

Python

Black

Black是Python代码格式化工具：

# 安装
pip install black

# 格式化单个文件
black src/main.py

# 格式化整个项目
black src/

# 检查格式（不修改）
black --check src/

配置Black

创建pyproject.toml：

[tool.black]
line-length = 88
target-version = ['py38']
include = '\.pyi?$'

isort

isort用于排序和格式化import语句：

# 安装
pip install isort

# 格式化import
isort src/

# 检查格式
isort --check-only src/

创建Python格式化脚本

#!/bin/bash
# scripts/format-python.sh

echo "格式化Python代码..."

# 排序import语句
isort src/

# 格式化代码
black src/

echo "Python格式化完成！"

JSON

jq

# 格式化JSON文件
jq '.' input.json > output.json

# 直接修改文件
jq '.' input.json | sponge input.json

# 检查JSON是否有效
jq empty input.json && echo "Valid JSON" || echo "Invalid JSON"

Python JSON工具

#!/bin/bash
# 格式化JSON
python3 -m json.tool input.json > output.json

YAML

yq

# 安装yq
brew install yq

# 格式化YAML文件
yq eval '.' input.yaml -i

# 验证YAML
yq eval 'input.yaml' --no-colors

Markdown

Prettier for Markdown

# 使用Prettier格式化Markdown
npx prettier --write "*.md"

# 使用markdown-tidy
npm install -g markdown-tidy
tidy -md input.md > output.md

创建格式化脚本

#!/bin/bash
# scripts/format-markdown.sh

echo "格式化Markdown文件..."

# 使用Prettier
npx prettier --write "*.md"

echo "Markdown格式化完成！"

集成到工作流

Git Hooks

使用pre-commit hook确保代码提交前格式化：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml

  - repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
      - id: black
        language_version: python3

  - repo: https://github.com/pycqa/isort
    rev: 5.12.0
    hooks:
      - id: isort

  - repo: https://github.com/pre-commit/mirrors-eslint
    rev: v8.39.0
    hooks:
      - id: eslint
        types: [javascript, jsx, ts, tsx]

安装pre-commit：

pip install pre-commit
pre-commit install

GitHub Actions

创建CI流程自动格式化：

# .github/workflows/format-check.yml
name: Format Check

on: [push, pull_request]

jobs:
  format-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

      - name: Install dependencies
        run: |
          npm install
          pip install black isort

      - name: Check TypeScript/JavaScript
        run: |
          npx prettier --check "src/**/*.{ts,tsx,js,jsx}"
          npx eslint src --ext .ts,.tsx,.js,.jsx

      - name: Check Python
        run: |
          black --check src/
          isort --check-only src/

VS Code配置

创建.vscode/settings.json：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  },
  "python.formatting.provider": "black",
  "[markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

自动化脚本

通用格式化脚本

#!/bin/bash
# scripts/format-all.sh

echo "================================"
echo "开始格式化所有代码..."
echo "================================"

# 检测项目类型
if [ -f "package.json" ]; then
    echo "检测到Node.js项目"

    # 安装依赖
    npm install

    # 格式化JS/TS
    if [ -d "src" ]; then
        echo "格式化JavaScript/TypeScript..."
        npx prettier --write "src/**/*.{js,jsx,ts,tsx}"
        npx eslint src --ext .ts,.tsx,.js,.jsx --fix || true
    fi

    # 格式化JSON
    echo "格式化JSON文件..."
    find . -name "*.json" -not -path "./node_modules/*" -exec npx prettier --write {} \;

elif [ -f "pyproject.toml" ] || [ -f "requirements.txt" ]; then
    echo "检测到Python项目"

    # 安装依赖
    pip install black isort

    # 格式化Python
    echo "格式化Python代码..."
    black src/ || true
    isort src/ || true

else
    echo "未知项目类型，跳过格式化"
fi

# 格式化Markdown
echo "格式化Markdown文件..."
find . -name "*.md" -not -path "./node_modules/*" -exec npx prettier --write {} \; || true

# 格式化YAML
echo "格式化YAML文件..."
find . -name "*.{yml,yaml}" -not -path "./node_modules/*" -exec yq eval '.' -i {} \; || true

echo "================================"
echo "格式化完成！"
echo "================================"

Makefile

创建Makefile：

.PHONY: format format-check install-deps

# 安装依赖
install-deps:
	npm install
	pip install black isort

# 格式化代码
format:
	npm run format
	black src/
	isort src/

# 检查格式（不修改）
format-check:
	npm run format:check
	black --check src/
	isort --check-only src/

与Claude Code配合使用

请求格式化

当Claude Code生成代码后，你可以要求它格式化：

请使用Prettier格式化这段代码：

```typescript
// 原始代码
const user = {
name: 'John',
age: 30,
email: 'john@example.com'
}

function getUser(id: string) {
return users.find(u => u.id === id)
}

Claude会输出格式化后的代码。

### 格式化后验证

```bash
# 格式化后检查是否有语法错误
npx tsc --noEmit  # TypeScript
python -m py_compile src/*.py  # Python

最佳实践

1. 配置优先

• 在项目根目录添加格式化工具配置文件
• 确保团队成员使用相同配置
• 版本控制配置文件

2. 自动化流程

• 使用Git Hooks自动格式化
• CI流程检查格式
• 提交前自动格式化

3. 选择合适的工具

语言/框架	推荐工具	补充工具
JS/TS	Prettier	ESLint
Python	Black	isort
JSON	jq	python -m json.tool
YAML	yq
Markdown	Prettier	markdown-tidy
CSS	Prettier	Stylelint
HTML	Prettier

4. 团队规范

• 统一代码风格指南
• 文档化格式化规则
• 定期回顾和调整

常见问题与解决方案

问题1：格式化冲突

症状：多个格式化工具产生冲突

解决方案：

• 使用Prettier作为统一格式化工具
• 配置ESLint使用Prettier
• 禁用冲突的格式化规则

{
  "extends": [
    "eslint:recommended",
    "prettier"
  ],
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error",
    "no-unused-vars": "off"
  }
}

问题2：格式化时间过长

症状：格式化整个项目很慢

解决方案：

• 只格式化修改的文件
• 使用并行处理
• 缓存配置

# 只格式化修改的文件
git diff --name-only HEAD~1 | grep '\.ts$' | xargs npx prettier --write

问题3：第三方库被格式化

症状：格式化了不应该格式化的第三方代码

解决方案：

• 使用.prettierignore
• 配置文件模式排除

{
  "ignorePatterns": [
    "dist/",
    "node_modules/",
    "*.min.js"
  ]
}

结语

代码格式化是提升代码质量的重要环节。通过将Claude Code与各种格式化工具结合，你可以确保生成的代码始终保持一致和专业的格式。

从今天开始，选择适合你项目技术栈的格式化工具，并将其集成到你的工作流中。你会发现，随着格式化的自动化，代码质量会持续提升，团队协作也会更加顺畅。

---

参考资源：

• Prettier文档
• Black文档
• ESLint文档
• Git Hooks指南
• GitHub Actions