自动格式化Hook：代码风格自动统一

一、自动格式化Hook的设计

在团队协作开发中，代码风格不一致是最常见也最令人头痛的问题之一。不同的开发者使用不同的缩进方式（空格 vs Tab）、不同的引号风格（单引号 vs 双引号）、不同的换行规则，这些琐碎的差异在代码审查时占据了大量不必要的时间。自动格式化Hook正是为了解决这一问题而设计的——它在Claude Code完成代码编辑后，自动调用格式化工具对输出代码进行统一处理，确保所有提交的代码遵循一致的风格规范。

该Hook的核心设计理念是"零感知格式化"：开发者无需记住手动执行格式化命令，无需在编辑器中安装特定插件，甚至不需要了解团队使用哪种格式化工具。Hook在后台静默运行，在代码被写入文件系统之前或之后立即执行格式化，开发者只看到最终统一风格后的代码。这种设计最大程度地减少了格式问题对开发流程的干扰，让团队能够专注于代码逻辑本身。

核心设计目标：代码编辑完成 -> 自动触发格式化 -> 统一风格输出。整个过程对开发者透明，无需手动干预，确保仓库中所有代码风格一致。

自动格式化Hook的架构可以分为三个核心层面：触发层（决定何时运行格式化）、适配层（选择合适的格式化工具和配置）、执行层（运行格式化并处理结果）。这三个层面协同工作，构成了一个完整的自动化格式链路。

二、多语言格式化器自适应Hook

现代项目通常涉及多种编程语言，每种语言都有其主流的格式化工具。自动格式化Hook需要具备语言感知能力，能够根据当前编辑的文件类型自动选择对应的格式化器。这种自适应机制避免了手动指定格式化工具的繁琐，也防止了使用错误格式化器导致代码损坏的风险。

Hook通过文件扩展名（.js、.py、.rs、.go等）或文件内容中的shebang行来检测语言类型，然后映射到相应的格式化工具。如果文件类型无法识别或没有对应的格式化器，Hook会跳过格式化并给出提示，而不是报错中断流程。

语言与格式化器对应关系

文件类型	扩展名	推荐格式化器	配置文件名
JavaScript / TypeScript	.js .ts .jsx .tsx	Prettier	.prettierrc
Python	.py	Black	pyproject.toml
Rust	.rs	rustfmt	rustfmt.toml
Go	.go	gofmt / gofmt	.gofmt.ini
Java	.java	google-java-format	.google-java-format
C / C++	.c .cpp .h .hpp	clang-format	.clang-format
Ruby	.rb	RuboCop	.rubocop.yml
Swift	.swift	swift-format	.swift-format
PHP	.php	PHP CS Fixer	.php-cs-fixer.dist.php
Lua	.lua	StyLua	.stylua.toml

自适应检测流程： 获取文件扩展名 -> 查找语言映射表 -> 检查格式化器是否可用 -> 选择合适的格式化参数 -> 执行格式化。如果某一步失败，优雅降级为跳过格式化并记录日志。

在实际实现中，自适应Hook还应当考虑项目的特殊情况。例如，同一个项目中可能同时包含前端（JS/TS）和后端（Python/Java）代码，Hook需要能够正确处理不同目录下的不同文件类型。此外，某些项目可能在特定子目录中使用自定义格式化规则（如自动生成的代码目录不需要格式化），这些都需要通过配置路径过滤规则来实现。

#!/usr/bin/env python3
# 自动格式化Hook - 多语言格式化器自适应调度核心
import os
import subprocess
from pathlib import Path

# 语言-格式化器映射表
FORMATTER_MAP = {
    '.js':    {'name': 'prettier',  'args': ['--write']},
    '.ts':    {'name': 'prettier',  'args': ['--write']},
    '.jsx':   {'name': 'prettier',  'args': ['--write']},
    '.tsx':   {'name': 'prettier',  'args': ['--write']},
    '.py':    {'name': 'black',     'args': ['--quiet']},
    '.rs':    {'name': 'rustfmt',   'args': []},
    '.go':    {'name': 'gofmt',     'args': ['-w']},
    '.java':  {'name': 'google-java-format', 'args': []},
}

def get_formatter(file_path):
    ext = Path(file_path).suffix
    return FORMATTER_MAP.get(ext)

def format_file(file_path):
    formatter = get_formatter(file_path)
    if not formatter:
        print(f"[Hook] 跳过 {file_path}: 无对应格式化器")
        return
    cmd = [formatter['name']] + formatter['args'] + [file_path]
    try:
        subprocess.run(cmd, check=True, capture_output=True, text=True)
        print(f"[Hook] 已格式化: {file_path}")
    except subprocess.CalledProcessError as e:
        print(f"[Hook] 格式化失败: {file_path}")
        print(f"  stderr: {e.stderr}")

三、格式化配置自动检测

团队级别的格式一致性要求所有开发者使用完全相同的格式化规则。自动检测项目中的格式化配置文件是实现这一目标的关键。Hook在运行格式化器之前，会从当前文件所在目录开始向上搜索，查找项目中已有的格式化配置文件，确保格式化结果与团队约定一致。

配置检测策略采用"就近优先"原则：先从文件所在目录查找配置文件，如果没有则逐级向上搜索父目录，直到项目根目录。这种策略允许项目不同部分使用不同的格式化规则（例如测试目录使用更宽松的规则），同时保持整体一致性。当配置文件完全缺失时，Hook会使用格式化器的内置默认值，并给出配置缺失的警告信息。

import os
from pathlib import Path

# 每种格式化器对应的配置文件名优先级列表
CONFIG_FILES = {
    'prettier': ['.prettierrc', '.prettierrc.json',
                   '.prettierrc.yaml', 'prettier.config.js'],
    'black':    ['pyproject.toml'],
    'rustfmt':  ['rustfmt.toml', '.rustfmt.toml'],
    'gofmt':    [],  # gofmt 无配置文件，使用固定规则
    'google-java-format': [],
}

def find_config(file_path, formatter_name):
    current_dir = Path(file_path).parent
    config_names = CONFIG_FILES.get(formatter_name, [])
    if not config_names:
        return None  # 该格式化器不需要配置文件
    # 从当前目录向上搜索
    for parent in [current_dir] + list(current_dir.parents):
        for config_name in config_names:
            config_path = parent / config_name
            if config_path.exists():
                return config_path
    return None  # 未找到任何配置文件

def format_with_config(file_path):
    formatter = get_formatter(file_path)
    if not formatter:
        return
    config_path = find_config(file_path, formatter['name'])
    if config_path:
        print(f"[Hook] 使用配置文件: {config_path}")
    else:
        print(f"[Hook] 警告: 未找到 {formatter['name']} 配置文件，"
              "使用默认配置")
    # 执行格式化...
    cmd = [formatter['name']] + formatter['args'] + [str(file_path)]
    if config_path and formatter['name'] == 'prettier':
        cmd.extend(['--config', str(config_path)])
    subprocess.run(cmd, check=True)

配置缺失警告示例： 当Hook检测到项目中没有Prettier配置文件时，会输出警告信息："[Hook] 警告: 项目根目录未找到 .prettierrc 配置文件，建议在项目根目录创建格式化配置文件以确保团队成员使用一致的格式规则。当前将使用Prettier默认配置。" 这个警告会提示但不会阻止格式化的执行。

四、格式化执行和验证Hook（after:tool/Edit）

在Claude Code的Hook系统中，after:tool/Edit是一个关键的触发点。当Claude Code完成对某个文件的编辑操作后，系统会自动触发注册在此事件上的Hook函数。格式化Hook正是挂载在这个事件上，在每次编辑完成后对被修改的文件执行格式化。这种设计确保了格式化动作与编辑动作紧密绑定，不存在遗漏的情况。

格式化执行流程

Hook被触发后，会执行以下完整流程：首先获取被编辑文件的路径和当前内容快照，然后根据文件类型选择合适的格式化器，检测项目配置，在内存中执行格式化操作。格式化完成后，将格式化后的内容与原始内容进行差异对比，生成格式修改报告。如果格式化前后没有差异，说明代码已经符合规范，直接跳过。如果有差异，将格式化后内容写回文件，并将差异信息反馈给用户。

# after:tool/Edit 格式化验证Hook核心实现
import difflib
import tempfile

def format_and_validate(edited_file_path):
    # 1. 读取原始内容快照
    with open(edited_file_path, 'r', encoding='utf-8') as f:
        original_content = f.read()

    # 2. 检查是否属于排除列表（自动生成文件等）
    if is_excluded(edited_file_path):
        print(f"[Hook] 跳过排除文件: {edited_file_path}")
        return

    # 3. 获取格式化器并执行格式化
    formatter = get_formatter(edited_file_path)
    if not formatter:
        return

    # 4. 在临时文件中执行格式化，避免直接覆盖
    with tempfile.NamedTemporaryFile(mode='w', suffix=Path(edited_file_path).suffix,
                                      delete=False, encoding='utf-8') as tmp:
        tmp.write(original_content)
        tmp_path = tmp.name

    try:
        cmd = [formatter['name']] + formatter['args'] + [tmp_path]
        result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)

        if result.returncode != 0:
            # 格式化失败，回退：保留原始文件，通知用户
            print(f"[Hook] 格式化失败 (return code {result.returncode})")
            print(f"[Hook] 错误信息: {result.stderr}")
            print("[Hook] 已回退到原始内容，请手动检查格式问题")
            return

        # 5. 读取格式化后的内容
        with open(tmp_path, 'r', encoding='utf-8') as f:
            formatted_content = f.read()

        # 6. 差异对比
        if original_content != formatted_content:
            diff = difflib.unified_diff(
                original_content.splitlines(True),
                formatted_content.splitlines(True),
                fromfile='原始', tofile='格式化后'
            )
            diff_text = ''.join(diff)
            print(f"[Hook] 格式修改差异:\n{diff_text}")

            # 7. 写回格式化后的内容
            with open(edited_file_path, 'w', encoding='utf-8') as f:
                f.write(formatted_content)
            print(f"[Hook] 已应用格式修正: {edited_file_path}")
        else:
            print(f"[Hook] 代码已符合格式规范，无需修改")

    except subprocess.TimeoutExpired:
        print("[Hook] 格式化超时 (30s)，已跳过格式化")
    except FileNotFoundError:
        print(f"[Hook] 格式化器 {formatter['name']} 未安装，"
              "请通过包管理器安装")
    finally:
        # 清理临时文件
        Path(tmp_path).unlink(missing_ok=True)

排除文件配置

某些文件不应该被自动格式化，包括自动生成的代码（如Protocol Buffer生成的pb文件）、第三方依赖库、大型数据文件、以及特定构建产物。Hook支持通过通配符模式配置排除列表，这些文件将跳过格式化流程。排除配置可以放在项目根目录的 .formatignore 文件中，格式类似于 .gitignore。

# .formatignore - 自动格式化排除清单
# 自动生成的文件
*_pb.py
*_pb2.py
*.gen.*
# 第三方依赖
vendor/**
node_modules/**
# 构建产物
dist/**
build/**
# 大型数据文件
*.json
*.min.js
*.min.css

五、团队格式一致性保障

自动格式化Hook不仅仅是一个本地开发工具，它还是团队代码质量标准的重要组成部分。通过将格式化检查集成到CI/CD流水线和代码审查流程中，可以实现全团队的格式一致性保障。即使个别开发者没有配置本地Hook，CI阶段的格式检查也能捕获并阻止不符合规范的代码合并。

团队级别的格式一致性策略采用"多层防御"架构：第一层是开发者本地的pre-commit hook或Claude Code的after:tool/Edit hook，在代码生成时自动格式化；第二层是CI流水线中的格式检查步骤，作为代码合并前的最后一道防线；第三层是代码审查阶段的格式标注，让审查者能够清晰看到格式问题。这三层防御共同确保了仓库中代码风格的高度一致。

PR自动标注与CI集成

在CI环境中，格式化检查步骤会对PR中的所有改动文件运行格式化器，然后检查是否有文件被修改。如果有文件在格式化后发生了变化，说明PR中的代码不符合格式规范。CI步骤会以非零状态码退出，并将格式差异以注释形式发布到PR上，让开发者清楚地知道需要修正哪些格式问题。

# .github/workflows/format-check.yml
name: 格式检查
on:
  pull_request:
    branches: [main, develop]

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

      - name: 安装依赖
        run: |
          npm install prettier
          pip install black

      - name: 检查代码格式
        run: |
          npx prettier --check "src/**/*.{js,ts,jsx,tsx}"
          black --check --diff src/

      - name: 生成格式报告
        if: failure()
        uses: reviewdog/action-suggester@v1
        with:
          tool_name: format-check

CI集成最佳实践： 在CI中使用 `--check` 模式（只检查不修改），而非 `--write` 模式。这样可以避免CI直接修改PR中的代码，让开发者在本地手动修正格式问题。同时，将格式检查步骤放在CI流程的前期（如lint阶段），以便尽早发现问题，避免浪费后续测试资源。

格式检查结果的可视化

为了让格式检查结果更加直观，可以通过GitHub Actions的annotations功能或第三方工具（如reviewdog）将格式差异直接标注在PR的文件diff中。这样审查者在查看代码变更时可以一目了然地看到哪些行存在格式问题，而不需要在CI日志中搜索。

多层防御体系总结： 本地Hook（自动格式化） -> pre-commit Hook（强制检查） -> CI检查（验证） -> PR标注（可视化）。每一层都在前一层的基上增加了额外的安全保障，确保即使某一层失效，后续层级仍然能够捕获格式问题。这种设计将格式一致性从"个人习惯"提升为"团队纪律"。

六、格式化失败的处理策略

自动格式化并非总能成功。常见的失败场景包括：格式化器未安装、配置文件语法错误、代码中存在语法错误导致格式化器无法解析、格式化超时等。一个健壮的自动格式化Hook必须为这些失败场景设计合理的处理策略，确保在格式化失败时不会丢失代码内容或破坏文件结构。

失败场景与处理策略对照

失败场景	原因	处理策略	用户通知
格式化器未安装	缺少运行时依赖	跳过格式化，保留原始内容	警告并提示安装命令
配置文件语法错误	配置文件格式不正确	使用默认配置继续格式化	警告配置解析失败
代码语法错误	代码存在语法问题	跳过格式化，保留原始内容	警告语法错误影响格式化
格式化超时	文件过大或格式化器卡死	中断格式化，保留原始内容	通知超时，建议手动处理
格式化后内容为空	格式化器发生未知错误	回退到原始内容，禁止写入空内容	告警并记录错误详情
磁盘空间不足	无法写入临时文件	捕获IO异常，保留原始内容	通知磁盘空间问题

在所有失败场景中，最核心的原则是：绝不因格式化失败而导致代码丢失或损坏。Hook应当始终优先保护原始代码内容，格式化操作应当先写入临时文件，验证通过后再替换原文件。此外，所有失败都应该有清晰的日志记录，方便开发者排查问题。对于CI环境中的格式化失败，应当输出详细的错误上下文，包括文件路径、格式化器版本、配置内容摘要等信息。

重要警告： 绝对不要在未验证格式化结果有效性的情况下直接覆盖原始文件。始终使用"先写临时文件 -> 验证内容 -> 再替换原文件"的三步策略。这是防止格式化器bug导致代码损坏的关键保障措施。

七、实际应用场景与配置示例

理解了自动格式化Hook的原理和设计之后，下面给出几个实际项目中的配置示例，涵盖前端项目、后端项目和全栈项目三种常见场景。

场景一：前端项目（JavaScript/TypeScript + Prettier）

// .prettierrc - 前端项目格式化配置
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100,
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf"
}

场景二：Python后端项目（Black + isort）

# pyproject.toml - Python项目格式化配置
[tool.black]
line-length = 100
target-version = ['py311']
include = '\.pyi?$'
extend-exclude = '''
/(
    \.eggs
  | \.git
  | \.hg
  | \.mypy_cache
  | \.tox
  | \.venv
  | _build
  | buck-out
  | build
  | dist
)/
'''

[tool.isort]
profile = "black"
line_length = 100

场景三：全栈项目（同时使用Prettier和Black）

# 自动格式化Hook完整配置 - 支持全栈项目
{
  "hooks": {
    "after:tool/Edit": {
      "format": {
        "enabled": true,
        "formatters": {
          "prettier": {
            "extensions": [".js", ".ts", ".jsx", ".tsx", ".json", ".css", ".md"],
            "config_search": true
          },
          "black": {
            "extensions": [".py"],
            "line_length": 100
          },
          "gofmt": {
            "extensions": [".go"]
          }
        },
        "exclude": ["**/vendor/**", "**/node_modules/**",
                    "**/*.pb.go", "**/*_pb.py"],
        "timeout": 30,
        "show_diff": true,
        "on_failure": "warn_only"
      }
    }
  }
}

实践建议： 在团队中推行自动格式化Hook时，建议先在CI阶段以"警告"模式运行一段时间（不阻止合并），让团队成员熟悉格式化规则。待大家适应后再切换到"强制"模式。这样可以减少推行阻力，让团队平滑过渡到统一格式的编码规范。

八、核心要点总结

自动触发

after:tool/Edit事件触发，编辑完成后自动运行格式化，无需手动操作

多语言支持

自动检测文件类型并选择对应格式化器：Prettier、Black、rustfmt、gofmt等

配置感知

自动搜索项目格式化配置文件，使用团队统一规则，配置缺失时发出警告

安全回退

格式化失败时保留原始内容，先写入临时文件验证成功后再替换原文件

差异展示

格式化前后差异对比展示，让用户清晰了解格式修改内容

团队保障

CI检测 + PR标注 + 本地Hook多层防线，确保全团队格式一致性

一句话总结： 自动格式化Hook通过在代码编辑完成后自动触发格式化工具，实现了"编辑即格式化"的零摩擦体验，将代码风格统一从人为约束转变为自动化机制，从根本上解决了团队协作中的格式争议问题。