Django 驗證迴圈

Django 驗證迴圈 是做什麼的？

在發送 PR 前、進行重大修改後以及預先部署時執行，以確保 Django 應用程式的品質與安全性。

啟用時機

• 針對 Django 專案開啟拉取請求（Pull Request）之前
• 在重大模型變更、遷移更新或相依套件升級之後
• 預先部署驗證至暫存（Staging）或正式（Production）環境
• 執行完整流程：環境檢查 → lint → 測試 → 安全 → 部署就緒管道
• 驗證遷移安全性與測試覆蓋率

第一階段：環境檢查

# 驗證 Python 版本
python --version  # 應符合專案需求

# 檢查虛擬環境
which python
pip list --outdated

# 驗證環境變數
python -c "import os; import environ; print('DJANGO_SECRET_KEY set' if os.environ.get('DJANGO_SECRET_KEY') else 'MISSING: DJANGO_SECRET_KEY')"

若環境設定錯誤，請停止並修正。

第二階段：程式碼品質與格式化

# 型別檢查
mypy . --config-file pyproject.toml

# 使用 Ruff 進行 lint
ruff check . --fix

# 使用 Black 格式化
black . --check
black .  # 自動修正

# 匯入排序
isort . --check-only
isort .  # 自動修正

# Django 專用檢查
python manage.py check --deploy

常見問題：

• 公開函數缺少型別註記
• PEP 8 格式違規
• 未排序的匯入
• 正式組態中遺留除錯設定

第三階段：遷移

# 檢查未套用的遷移
python manage.py showmigrations

# 建立遺漏的遷移
python manage.py makemigrations --check

# 預演遷移套用
python manage.py migrate --plan

# 套用遷移（測試環境）
python manage.py migrate

# 檢查遷移衝突
python manage.py makemigrations --merge  # 僅在有衝突時執行

報告項目：

• 待處理遷移數量
• 任何遷移衝突
• 無對應遷移的模型變更

第四階段：測試 + 覆蓋率

# 使用 pytest 執行所有測試
pytest --cov=apps --cov-report=html --cov-report=term-missing --reuse-db

# 執行特定應用程式的測試
pytest apps/users/tests/

# 使用標記執行
pytest -m "not slow"  # 跳過慢速測試
pytest -m integration  # 僅執行整合測試

# 覆蓋率報告
open htmlcov/index.html

報告項目：

• 總測試數：X 通過，Y 失敗，Z 跳過
• 整體覆蓋率：XX%
• 各應用程式覆蓋率細項

覆蓋率目標：

元件	目標
模型	90%+
序列化器	85%+
檢視	80%+
服務	90%+
整體	80%+

第五階段：安全掃描

# 相依套件漏洞
pip-audit
safety check --full-report

# Django 安全檢查
python manage.py check --deploy

# Bandit 安全 lint
bandit -r . -f json -o bandit-report.json

# 機密掃描（若已安裝 gitleaks）
gitleaks detect --source . --verbose

# 環境變數檢查
python -c "from django.core.exceptions import ImproperlyConfigured; from django.conf import settings; settings.DEBUG"

報告項目：

• 發現的脆弱相依套件
• 安全性設定問題
• 偵測到的硬編碼機密
• DEBUG 模式狀態（正式環境應為 False）

第六階段：Django 管理命令

# 檢查模型問題
python manage.py check

# 收集靜態檔案
python manage.py collectstatic --noinput --clear

# 建立超級使用者（若測試需要）
echo "from apps.users.models import User; User.objects.create_superuser('[email protected]', 'admin')" | python manage.py shell

# 資料庫完整性
python manage.py check --database default

# 快取驗證（若使用 Redis）
python -c "from django.core.cache import cache; cache.set('test', 'value', 10); print(cache.get('test'))"

第七階段：效能檢查

# Django Debug Toolbar 輸出（檢查 N+1 查詢）
# 在開發模式下以 DEBUG=True 執行，並存取頁面
# 在 SQL 面板中檢查重複查詢

# 查詢計數分析
django-admin debugsqlshell  # 若已安裝 django-debug-sqlshell

# 檢查遺失的索引
python manage.py shell << EOF
from django.db import connection
with connection.cursor() as cursor:
    cursor.execute("SELECT table_name, index_name FROM information_schema.statistics WHERE table_schema = 'public'")
    print(cursor.fetchall())
EOF

報告項目：

• 每頁查詢數量（一般頁面應 < 50）
• 遺失的資料庫索引
• 偵測到的重複查詢

第八階段：靜態資源

# 檢查 npm 相依套件（若使用 npm）
npm audit
npm audit fix

# 建置靜態檔案（若使用 webpack/vite）
npm run build

# 驗證靜態檔案
ls -la staticfiles/
python manage.py findstatic css/style.css

第九階段：組態審查

# 在 Python shell 中執行以驗證設定
python manage.py shell << EOF
from django.conf import settings
import os

# 關鍵檢查
checks = {
    'DEBUG is False': not settings.DEBUG,
    'SECRET_KEY set': bool(settings.SECRET_KEY and len(settings.SECRET_KEY) > 30),
    'ALLOWED_HOSTS set': len(settings.ALLOWED_HOSTS) > 0,
    'HTTPS enabled': getattr(settings, 'SECURE_SSL_REDIRECT', False),
    'HSTS enabled': getattr(settings, 'SECURE_HSTS_SECONDS', 0) > 0,
    'Database configured': settings.DATABASES['default']['ENGINE'] != 'django.db.backends.sqlite3',
}

for check, result in checks.items():
    status = '✓' if result else '✗'
    print(f"{status} {check}")
EOF

第十階段：日誌設定

# 測試日誌輸出
python manage.py shell << EOF
import logging
logger = logging.getLogger('django')
logger.warning('Test warning message')
logger.error('Test error message')
EOF

# 檢查日誌檔案（若有設定）
tail -f /var/log/django/django.log

第十一階段：API 文件（若使用 DRF）

# 產生 schema
python manage.py generateschema --format openapi-json > schema.json

# 驗證 schema
# 檢查 schema.json 是否為有效 JSON
python -c "import json; json.load(open('schema.json'))"

# 存取 Swagger UI（若使用 drf-yasg）
# 在瀏覽器中造訪 http://localhost:8000/swagger/

第十二階段：差異審查

# 顯示差異統計
 git diff --stat

# 顯示實際變更
 git diff

# 顯示變更的檔案
 git diff --name-only

# 檢查常見問題
 git diff | grep -i "todo\|fixme\|hack\|xxx"
 git diff | grep "print("  # 除錯陳述
 git diff | grep "DEBUG = True"  # 除錯模式
 git diff | grep "import pdb"  # 除錯器

檢查清單：

• 無除錯陳述（print、pdb、breakpoint()）
• 關鍵程式碼中無 TODO/FIXME 註解
• 無硬編碼機密或憑證
• 模型變更已包含資料庫遷移
• 組態變更已記錄
• 外部呼叫已包含錯誤處理
• 必要處已使用交易管理

輸出範本

DJANGO 驗證報告
==========================

第一階段：環境檢查
  ✓ Python 3.11.5
  ✓ 虛擬環境啟用
  ✓ 所有環境變數已設定

第二階段：程式碼品質
  ✓ mypy：無型別錯誤
  ✗ ruff：發現 3 個問題（已自動修正）
  ✓ black：無格式問題
  ✓ isort：匯入已正確排序
  ✓ manage.py check：無問題

第三階段：遷移
  ✓ 無未套用的遷移
  ✓ 無遷移衝突
  ✓ 所有模型都有對應遷移

第四階段：測試 + 覆蓋率
  測試：247 通過，0 失敗，5 跳過
  覆蓋率：
    整體：87%
    users：92%
    products：89%
    orders：85%
    payments：91%

第五階段：安全掃描
  ✗ pip-audit：發現 2 個漏洞（需修正）
  ✓ safety check：無問題
  ✓ bandit：無安全問題
  ✓ 未偵測到機密
  ✓ DEBUG = False

第六階段：Django 命令
  ✓ collectstatic 完成
  ✓ 資料庫完整性 OK
  ✓ 快取後端可連線

第七階段：效能
  ✓ 未偵測到 N+1 查詢
  ✓ 資料庫索引已設定
  ✓ 查詢數量可接受

第八階段：靜態資源
  ✓ npm audit：無漏洞
  ✓ 資源建置成功
  ✓ 靜態檔案已收集

第九階段：組態
  ✓ DEBUG = False
  ✓ SECRET_KEY 已設定
  ✓ ALLOWED_HOSTS 已設定
  ✓ HTTPS 已啟用
  ✓ HSTS 已啟用
  ✓ 資料庫已設定

第十階段：日誌
  ✓ 日誌已設定
  ✓ 日誌檔案可寫入

第十一階段：API 文件
  ✓ Schema 已產生
  ✓ Swagger UI 可存取

第十二階段：差異審查
  變更檔案數：12
  +450, -120 行
  ✓ 無除錯陳述
  ✓ 無硬編碼機密
  ✓ 已包含遷移

建議：警告：部署前請先修正 pip-audit 漏洞

後續步驟：
1. 更新脆弱相依套件
2. 重新執行安全掃描
3. 部署至暫存環境進行最終測試

預先部署檢查清單

• 所有測試通過
• 覆蓋率 ≥ 80%
• 無安全性漏洞
• 無未套用的遷移
• 正式組態中 DEBUG = False
• SECRET_KEY 已正確設定
• ALLOWED_HOSTS 已正確設定
• 資料庫備份已啟用
• 靜態檔案已收集並提供服務
• 日誌已設定且正常運作
• 錯誤監控（Sentry 等）已設定
• CDN 已設定（如適用）
• Redis/快取後端已設定
• Celery worker 正在執行（如適用）
• HTTPS/SSL 已設定
• 環境變數已文件化

持續整合

GitHub Actions 範例

# .github/workflows/django-verification.yml
name: Django Verification

on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:14
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Cache pip
        uses: actions/cache@v3
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}

      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install ruff black mypy pytest pytest-django pytest-cov bandit safety pip-audit

      - name: Code quality checks
        run: |
          ruff check .
          black . --check
          isort . --check-only
          mypy .

      - name: Security scan
        run: |
          bandit -r . -f json -o bandit-report.json
          safety check --full-report
          pip-audit

      - name: Run tests
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost:5432/test
          DJANGO_SECRET_KEY: test-secret-key
        run: |
          pytest --cov=apps --cov-report=xml --cov-report=term-missing

      - name: Upload coverage
        uses: codecov/codecov-action@v3

快速參考

檢查項目	指令
環境	python --version
型別檢查	mypy .
Linting	ruff check .
格式化	black . --check
遷移	python manage.py makemigrations --check
測試	pytest --cov=apps
安全	pip-audit && bandit -r .
Django 檢查	python manage.py check --deploy
收集靜態檔案	python manage.py collectstatic --noinput
差異統計	git diff --stat

請記住：自動化驗證能捕捉常見問題，但無法取代人工程式碼審查和在暫存環境中的測試。