Python代碼質(zhì)量之從規(guī)范到自動化檢查全過程

更新時間：2026年05月07日 09:15:03 作者：牧碼人王木木

本文介紹了提高Python代碼質(zhì)量的十個關(guān)鍵方面,包括清晰的命名、一致性、注釋、模塊化、錯誤處理、測試、代碼簡潔、版本控制、性能優(yōu)化和文檔編寫,需要的朋友可以參考下

1. 技術(shù)分析

1.1 代碼質(zhì)量維度

維度	描述	工具
代碼風格	PEP 8規(guī)范	black, isort
類型檢查	類型注解檢查	mypy
代碼規(guī)范	最佳實踐	flake8, pylint
安全檢查	潛在漏洞	bandit, safety
測試覆蓋	代碼測試比例	coverage

1.2 工具對比

工具	功能	性能	學習曲線
black	代碼格式化	快	低
flake8	代碼檢查	快	低
mypy	類型檢查	中	中
pylint	全面檢查	慢	高
ruff	快速linting	極快	低

2. 核心功能實現(xiàn)

2.1 代碼格式化配置

# pyproject.toml
[tool.black]
line-length = 88
target-version = ['py39', 'py310', 'py311']
include = '\.pyi?$'
exclude = '''
/(
    \.git
    | \.venv
    | build
    | dist
)/
'''
[tool.isort]
profile = "black"
line_length = 88
known_first_party = ["src"]
skip = [".venv", "build", "dist"]
[tool.mypy]
python_version = "3.9"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = false
ignore_missing_imports = true
[tool.ruff]
line-length = 88
target-version = "py39"
[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "UP", "B", "C4"]
ignore = ["E501"]  # 行長度由black處理
[tool.coverage.run]
source = ["src"]
omit = ["*/tests/*", "*/test_*.py"]
[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "if __name__ == .__main__.:",
    "raise AssertionError()",
]

2.2 單元測試實踐

import pytest
from typing import List, Optional

class DataValidator:
    """數(shù)據(jù)驗證器"""
    
    @staticmethod
    def validate_email(email: str) -> bool:
        """驗證郵箱格式"""
        import re
        pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
        return bool(re.match(pattern, email))
    
    @staticmethod
    def validate_positive(value: float) -> bool:
        """驗證正數(shù)"""
        return value > 0
    
    @staticmethod
    def validate_in_range(value: float, min_val: float, max_val: float) -> bool:
        """驗證范圍"""
        return min_val <= value <= max_val

class TestDataValidator:
    """數(shù)據(jù)驗證器測試"""
    
    @pytest.mark.parametrize("email,expected", [
        ("test@example.com", True),
        ("user.name@domain.co.uk", True),
        ("invalid-email", False),
        ("@domain.com", False),
        ("user@", False),
        ("", False),
    ])
    def test_validate_email(self, email, expected):
        assert DataValidator.validate_email(email) == expected
    
    @pytest.mark.parametrize("value,expected", [
        (1.0, True),
        (0.0, False),
        (-1.0, False),
        (100.5, True),
    ])
    def test_validate_positive(self, value, expected):
        assert DataValidator.validate_positive(value) == expected
    
    def test_validate_in_range(self):
        assert DataValidator.validate_in_range(5, 0, 10) == True
        assert DataValidator.validate_in_range(0, 0, 10) == True
        assert DataValidator.validate_in_range(10, 0, 10) == True
        assert DataValidator.validate_in_range(-1, 0, 10) == False
        assert DataValidator.validate_in_range(11, 0, 10) == False

class TestEdgeCases:
    """邊界情況測試"""
    
    def test_empty_string(self):
        assert DataValidator.validate_email("") == False
    
    def test_unicode_email(self):
        assert DataValidator.validate_email("用戶@例子.廣告") == False
    
    def test_very_long_email(self):
        long_email = "a" * 100 + "@example.com"
        # 應該能處理但可能返回False（取決于具體實現(xiàn)）
        result = DataValidator.validate_email(long_email)
        assert isinstance(result, bool)

2.3 Mock與測試隔離

from unittest.mock import Mock, patch, MagicMock
import pytest

class APIClient:
    """API客戶端"""
    
    def __init__(self, base_url: str):
        self.base_url = base_url
        self.session = None
    
    def fetch(self, endpoint: str) -> dict:
        """獲取數(shù)據(jù)"""
        import requests
        response = requests.get(f"{self.base_url}/{endpoint}")
        return response.json()

class TestAPIClient:
    """API客戶端測試"""
    
    @patch('requests.get')
    def test_fetch_success(self, mock_get):
        """測試成功獲取"""
        mock_response = Mock()
        mock_response.json.return_value = {"status": "success", "data": [1, 2, 3]}
        mock_get.return_value = mock_response
        
        client = APIClient("https://api.example.com")
        result = client.fetch("users")
        
        assert result["status"] == "success"
        assert result["data"] == [1, 2, 3]
        mock_get.assert_called_once_with("https://api.example.com/users")
    
    @patch('requests.get')
    def test_fetch_error(self, mock_get):
        """測試獲取失敗"""
        mock_get.side_effect = ConnectionError("Network error")
        
        client = APIClient("https://api.example.com")
        
        with pytest.raises(ConnectionError):
            client.fetch("users")
    
    def test_with_fixture(self, mock_get):
        """使用fixture的測試"""
        # fixture在conftest.py中定義
        result = self.client.fetch("users")
        assert "status" in result

2.4 性能測試

import pytest
import time

class TestPerformance:
    """性能測試"""
    
    def test_sort_performance(self):
        """測試排序性能"""
        import random
        
        # 生成大量數(shù)據(jù)
        data = [random.randint(0, 10000) for _ in range(10000)]
        
        start = time.perf_counter()
        sorted_data = sorted(data)
        elapsed = time.perf_counter() - start
        
        # 應該在1秒內(nèi)完成
        assert elapsed < 1.0, f"排序耗時 {elapsed:.2f}s，超過1秒"
        
        # 驗證排序正確性
        assert sorted_data == sorted(data)
    
    @pytest.mark.benchmark
    def test_list_comprehension_performance(self, benchmark):
        """基準測試列表推導式"""
        result = benchmark(lambda: [i**2 for i in range(10000)])
        assert len(result) == 10000

# conftest.py
def pytest_configure(config):
    config.addinivalue_line("markers", "benchmark: mark test as a benchmark")

@pytest.fixture
def sample_data():
    """示例數(shù)據(jù)fixture"""
    return [i for i in range(100)]

3. 持續(xù)集成配置

3.1 pre-commit配置

# .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
      - id: check-added-large-files
      - id: check-merge-conflict
  - repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
      - id: black
        language_version: python3.10
  - repo: https://github.com/pycqa/isort
    rev: 5.12.0
    hooks:
      - id: isort
        args: ["--profile", "black"]
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.0.261
    hooks:
      - id: ruff
        args: ["--fix"]
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.3.0
    hooks:
      - id: mypy
        additional_dependencies: [types-all]

3.2 GitHub Actions CI

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.9', '3.10', '3.11']
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v4
        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/
      - name: Format check with black
        run: black --check src/
      - name: Type check with mypy
        run: mypy src/
      - name: Test with pytest
        run: |
          coverage run -m pytest tests/
          coverage report --fail-under=80
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage.xml

4. 代碼質(zhì)量指標

4.1 覆蓋率報告

# 運行測試并生成覆蓋率報告
$ coverage run -m pytest tests/
$ coverage report -m

Name                 Stmts   Miss  Cover   Missing
-----------------------------------------------------
src/validators.py       45      5    89%    23,45,67
src/models.py           78     12    85%    34,56,78
tests/test_validators.py  60      0   100%    -
-----------------------------------------------------
TOTAL                 183     17    91%

4.2 復雜度分析

# 使用radon進行復雜度分析
from radon.metrics import mi_visit, h_visit
from radon.complexity import cc_visit

def analyze_complexity(filepath: str):
    """代碼復雜度分析"""
    with open(filepath, 'r') as f:
        source = f.read()
    
    # 圈復雜度
    complexity = cc_visit(source)
    print("圈復雜度:")
    for item in complexity:
        if item.classname:
            name = f"{item.classname}.{item.name}"
        else:
            name = item.name
        print(f"  {name}: {item.complexity}")
    
    # 維護性指數(shù)
    mi = mi_visit(source, multi=True)
    print(f"\n維護性指數(shù): {mi:.1f}")
    
    # Halstead指標
    from radon.metrics import h_visit
    halstead = h_visit(source)
    print(f"難度: {halstead.difficulty:.1f}")

5. 最佳實踐

5.1 代碼審查清單

- [ ] 代碼符合PEP 8規(guī)范
- [ ] 函數(shù)和類有docstring
- [ ] 類型注解完整
- [ ] 單元測試覆蓋關(guān)鍵邏輯
- [ ] 沒有硬編碼的魔法數(shù)字
- [ ] 錯誤處理適當
- [ ] 沒有安全漏洞
- [ ] 性能符合要求

5.2 提交前檢查

#!/bin/bash
# pre-commit-check.sh
set -e
echo "運行代碼檢查..."
# 格式化
black --check src/
echo "? 格式化檢查通過"
# 檢查import
isort --check-only --diff src/
echo "? import檢查通過"
# Lint
ruff check src/
echo "? Lint檢查通過"
# 類型檢查
mypy src/
echo "? 類型檢查通過"
# 測試
pytest tests/ -v
echo "? 測試通過"
echo "所有檢查通過!"