一、核心原则：测试驱动与版本控制

# 无测试，直接在主分支修改
# 功能未验证就提交
# Commit 信息随意
# 多人同时改同一段代码
# 回退困难，Bug 难以追溯

# 先写测试，再写实现
# 功能分支开发，主干保护
# Commit 语义化，可追溯
# PR Review 合并代码
# CI 自动测试，发布有 Tag

二、科学测试方法论

2.1 测试金字塔

2.2 测试文件组织

project/
├── src/
│   └── myapp/
│       ├── __init__.py
│       ├── core.py
│       └── utils.py
├── tests/
│   ├── __init__.py
│   ├── unit/              # 单元测试
│   │   ├── test_core.py
│   │   └── test_utils.py
│   ├── integration/       # 集成测试
│   │   └── test_api.py
│   └── conftest.py        # pytest 共享 fixture
├── .github/workflows/
│   └── ci.yml
└── pyproject.toml

2.3 pytest 最佳实践

2.4 测试用例编写规范

# tests/unit/test_calculator.py
import pytest
from myapp.calculator import Calculator


class TestCalculator:
    """Calculator unit tests."""

    def test_add_positive_numbers(self):
        """Test addition with positive numbers."""
        calc = Calculator()
        assert calc.add(2, 3) == 5

    def test_add_negative_numbers(self):
        """Test addition with negative numbers."""
        calc = Calculator()
        assert calc.add(-2, -3) == -5

    def test_divide_by_zero_raises(self):
        """Test division by zero raises ZeroDivisionError."""
        calc = Calculator()
        with pytest.raises(ZeroDivisionError):
            calc.divide(10, 0)

    @pytest.mark.parametrize("a,b,expected", [
        (1, 2, 3),
        (0, 0, 0),
        (-1, 1, 0),
        (100, -50, 50),
    ])
    def test_add_parametrized(self, a, b, expected):
        """Test addition with multiple input sets."""
        calc = Calculator()
        assert calc.add(a, b) == expected

三、安全的代码修改策略

3.1 修改前准备

1. 确认当前分支干净：git status 无未提交的修改 如果有临时修改，用 git stash 暂存或先提交
2. 确认测试基线通过：pytest 全部通过 如果已有测试失败，先修复再开始新功能
3. 创建功能分支：git checkout -b feature/xxx 分支名要语义化：feature/、fix/、refactor/ 前缀
4. 编写失败的测试：先写测试，确认当前测试失败（TDD 红-绿-重构）

3.2 TDD 循环

3.3 代码质量工具链

3.4 pre-commit 配置

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.5.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.10.0
    hooks:
      - id: mypy
        additional_dependencies: [types-requests]

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

# 安装 pre-commit 钩子
pip install pre-commit
pre-commit install
pre-commit installed at .git/hooks/pre-commit

# 手动运行检查所有文件
pre-commit run --all-files

四、Git 分支管理模型

4.1 Git Flow 简化模型

main (protected)          # 生产分支，永远可部署
│
├─── develop              # 开发集成分支（可选）
│     │
│     ├─── feature/login  # 功能分支：feature/xxx
│     │
│     ├─── feature/auth   # 功能分支：feature/xxx
│     │
│     └─── fix/memory     # 修复分支：fix/xxx
│
└─── hotfix/security      # 紧急修复：hotfix/xxx

4.2 分支操作命令

# 创建并切换到功能分支
git checkout -b feature/user-authentication

# 推送分支到远程
git push -u origin feature/user-authentication

# 保持分支与 main 同步（rebase 方式，提交记录更整洁）
git checkout feature/user-authentication
git fetch origin
git rebase origin/main

# 功能完成后合并回 main
git checkout main
git pull origin main
git merge --no-ff feature/user-authentication
git push origin main

五、提交准则与 Commit Message

5.1 Conventional Commits 规范

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

5.2 优秀 Commit 示例

feat(auth): add JWT-based authentication

Implement JWT token generation and validation for user login.
- Add /login endpoint returning access_token
- Add token refresh mechanism
- Add token blacklist for logout

Closes #123

fix(api): handle missing parameters in /calculate endpoint

Return 400 Bad Request instead of 500 when required parameters
are missing. Add input validation before processing.

BREAKING CHANGE: error response format changed from plain text
to JSON with "detail" field.

test(calculator): add edge case tests for division

- Test division by zero raises ZeroDivisionError
- Test float division precision
- Test negative number division

六、协作开发与 Pull Request

6.1 PR 创建规范

1. 功能开发完成，本地测试全部通过
2. 推送分支到远程：git push origin feature/xxx
3. 在 GitHub/GitLab 创建 Pull Request 标题格式：[类型] 简要描述，如 “[feat] 添加用户认证模块”
4. 填写 PR 描述模板： – 变更内容：做了什么 – 测试覆盖：新增/修改了哪些测试 – 影响范围：是否涉及 API 变更 – 关联 Issue：Fixes #xxx
5. 添加 Reviewer，等待代码审查

6.2 PR 描述模板

## 变更内容

- 添加用户 JWT 认证模块
- 实现 /login 和 /refresh 端点

## 测试覆盖

- [x] 单元测试：新增 12 个测试用例
- [x] 集成测试：验证完整登录流程
- [x] 手动测试：Postman 验证 API

## 影响范围

- 无破坏性变更
- 新增环境变量 JWT_SECRET

## 关联 Issue
Fixes #123
Closes #124

## 截图（如适用）

6.3 代码审查 Checklist

七、冲突解决与代码审查

7.1 冲突预防策略

7.2 冲突解决流程

# 尝试合并 main 到当前分支
git merge origin/main
Auto-merging src/core.py
CONFLICT (content): Merge conflict in src/core.py
Automatic merge failed; fix conflicts and then commit the result.

# 查看冲突文件
git status
Unmerged paths:
  (use "git add <file>..." to mark resolution)
        both modified:   src/core.py

# 编辑冲突文件，解决冲突标记
# <<<<<<< HEAD
# 你的代码
# =======
# 对方代码
# >>>>>>> main

# 标记冲突已解决
git add src/core.py
git commit -m "merge: resolve conflict in core.py"

7.3 请求变更与回复

# 审查者提出意见
Comment on line 42:
> 建议将这里的魔法数字提取为常量
> MAGIC_NUMBER = 100

# 开发者回复并修改
Reply: 已修改，提取为 MAX_RETRY_COUNT = 3

# 开发者推送修改
git add src/core.py
git commit --amend --no-edit
git push --force-with-lease origin feature/xxx

八、版本发布与 Tag 管理

8.1 发布流程

8.2 Tag 操作

# 附注标签（推荐，包含签名信息）
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

# 轻量标签（仅引用，不推荐用于发布）
git tag v1.2.0
git push origin v1.2.0

# 查看标签列表
git tag -l "v1.*"

# 删除本地标签
git tag -d v1.2.0

8.3 CHANGELOG 驱动发布

# 发布前更新 CHANGELOG.md
## [1.2.0] - 2026-07-15

### Added
- 添加用户认证模块 (feat: auth)
- 支持批量导出功能

### Changed
- 优化数据库查询性能 30%

### Fixed
- 修复内存泄漏问题 (fix: memory)
- 修复并发下的竞态条件

### Security
- 升级依赖库修复 CVE-2026-xxx

九、CI/CD 自动化测试

9.1 GitHub Actions 完整配置

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13"]

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -e ".[dev]"

      - name: Lint with ruff
        run: ruff check src/ tests/

      - name: Type check with mypy
        run: mypy src/

      - name: Test with pytest
        run: pytest --cov=src --cov-report=xml

      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          file: ./coverage.xml
          fail_ci_if_error: false

  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: {python-version: "3.12"}
      - run: pip install bandit safety
      - run: bandit -r src/
      - run: safety check

9.2 分支保护规则

十、常见问题与应急预案

应急回滚操作

# 场景1：刚 push 到远程，想撤销最后一次提交
git revert HEAD
git push origin main

# 场景2：发现 main 有严重 Bug，需要紧急回滚到上一个版本
git log --oneline -5
abc1234 (HEAD -> main) 错误提交
def5678 上一个稳定版本
git revert abc1234
git push origin main

# 场景3：本地回滚到某个提交（未 push）
git reset --soft HEAD~1   # 保留修改到暂存区
git reset --mixed HEAD~1  # 保留修改到工作区
git reset --hard HEAD~1   # 完全丢弃修改（慎用）