claude-code/claude-zh/commands/python-review.md

---
description: 對 Python 程式碼進行全面審查，包含 PEP 8 規範、型別提示、安全性及 Python 慣用法。此指令會呼叫 python-reviewer agent。
---

# Python 程式碼審查 (Python Code Review)

此指令會呼叫 **python-reviewer** agent 來進行針對 Python 語言特性的全面審查。

## 此指令的功能

1. **識別 Python 變更**：透過 `git diff` 找出修改過的 `.py` 檔案。
2. **執行靜態分析**：執行 `ruff`, `mypy`, `pylint`, `black --check`。
3. **安全掃描**：檢查是否存在 SQL 注入、指令注入、不安全的反序列化。
4. **型別安全審查**：分析型別提示 (Type hints) 與 mypy 錯誤。
5. **Pythonic 檢查**：驗證程式碼是否遵循 PEP 8 與 Python 最佳實踐。
6. **產生報告**：按嚴重程度對問題進行分類。

## 何時使用

在以下情況使用 `/python-review`：
- 撰寫或修改 Python 程式碼後。
- 提交 Python 變更前。
- 審查包含 Python 程式碼的 Pull Request 時。
- 進入新的 Python 專案庫時。
- 學習 Pythonic 模式與慣用法時。

## 審查類別

### 關鍵問題 (CRITICAL - 必須修復)
- SQL/指令注入漏洞。
- 不安全的 `eval()`/`exec()` 使用。
- Pickle 不安全的反序列化。
- 硬編碼的憑據。
- YAML 不安全的 `load()` (應使用 `safe_load()`)。
- 隱藏錯誤的空 `except` 區塊。

### 高優先級 (HIGH - 建議修復)
- 公共函式缺少型別提示。
- 使用可變物件作為預設參數 (Mutable default arguments)。
- 靜默吞掉異常 (Swallowing exceptions)。
- 資源使用未採用上下文管理器 (Context managers)。
- 使用 C 風格迴圈而非列表推導式 (Comprehensions)。
- 使用 `type()` 而非 `isinstance()`。
- 無鎖機制下的競態條件。

### 中優先級 (MEDIUM - 考慮調整)
- 違反 PEP 8 格式規範。
- 公共函式缺少 Docstrings。
- 使用 `print` 語句而非 `logging`。
- 低效的字串操作。
- 未使用具名常數的魔術數字 (Magic numbers)。
- 未使用 f-strings 進行格式化。
- 不必要的列表建立。

## 執行的自動化檢查

```bash
# 型別檢查
mypy .

# Lint 與格式檢查
ruff check .
black --check .
isort --check-only .

# 安全掃描
bandit -r .

# 依賴項稽核
pip-audit
safety check

# 測試
pytest --cov=app --cov-report=term-missing
```

## 使用範例

```text
使用者：/python-review

Agent：
# Python 程式碼審查報告

## 審查檔案
- app/routes/user.py (已修改)
- app/services/auth.py (已修改)

## 靜態分析結果
✓ ruff: 無問題
✓ mypy: 無錯誤
⚠️ black: 2 個檔案需要重新格式化
✓ bandit: 無安全問題

## 發現問題

[CRITICAL] SQL 注入漏洞
檔案: app/routes/user.py:42
問題: 使用者輸入直接插入 SQL 查詢字串
```python
query = f"SELECT * FROM users WHERE id = {user_id}"  # 錯誤
```
修復方案: 使用參數化查詢
```python
query = "SELECT * FROM users WHERE id = %s"  # 正確
cursor.execute(query, (user_id,))
```

[HIGH] 可變預設參數 (Mutable default argument)
檔案: app/services/auth.py:18
問題: 可變預設參數會導致狀態共享
```python
def process_items(items=[]):  # 錯誤
    items.append("new")
    return items
```
修復方案: 使用 None 作為預設值
```python
def process_items(items=None):  # 正確
    if items is None:
        items = []
    items.append("new")
    return items
```

[MEDIUM] 缺少型別提示
檔案: app/services/auth.py:25
問題: 公共函式缺少型別註解
```python
def get_user(user_id):  # 錯誤
    return db.find(user_id)
```
修復方案: 加入型別提示
```python
def get_user(user_id: str) -> Optional[User]:  # 正確
    return db.find(user_id)
```

[MEDIUM] 未使用上下文管理器
檔案: app/routes/user.py:55
問題: 發生異常時檔案未關閉
```python
f = open("config.json")  # 錯誤
data = f.read()
f.close()
```
修復方案: 使用 context manager
```python
with open("config.json") as f:  # 正確
    data = f.read()
```

## 摘要
- CRITICAL: 1
- HIGH: 1
- MEDIUM: 2

建議: ❌ 在修復 CRITICAL 問題前，禁止合併 (Block merge)

## 所需格式化
請執行：`black app/routes/user.py app/services/auth.py`
```

## 核准標準

| 狀態 | 條件 |
|--------|-----------|
| ✅ 核准 (Approve) | 無 CRITICAL 或 HIGH 問題 |
| ⚠️ 警告 (Warning) | 僅存在 MEDIUM 問題 (謹慎合併) |
| ❌ 阻斷 (Block)   | 發現 CRITICAL 或 HIGH 問題 |

## 與其他指令的整合

- 先使用 `/tdd` 確保測試通過。
- 對於非 Python 特有的通用問題，請使用 `/code-review`。
- 在提交前使用 `/python-review`。
- 若靜態分析工具失敗，則使用 `/build-fix`。

## 框架特定審查

### Django 專案
審查者會檢查：
- N+1 查詢問題 (應使用 `select_related` 與 `prefetch_related`)。
- 模型變更但缺少 Migrations。
- 在能使用 ORM 時使用了原生 SQL。
- 多步驟操作缺少 `transaction.atomic()`。

### FastAPI 專案
審查者會檢查：
- CORS 配置錯誤。
- 使用 Pydantic 模型進行請求驗證。
- 回應模型 (Response models) 的正確性。
- 正確使用 async/await。
- 依賴注入模式。

### Flask 專案
審查者會檢查：
- 上下文管理 (App context, Request context)。
- 正確的錯誤處理。
- Blueprint 結構組織。
- 配置管理。

## 相關參考

- Agent: `agents/python-reviewer.md`
- 技能: `skills/python-patterns/`, `skills/python-testing/`

## 常見修復方法範例

### 加入型別提示
```python
# 修復前
def calculate(x, y):
    return x + y

# 修復後
from typing import Union

def calculate(x: Union[int, float], y: Union[int, float]) -> Union[int, float]:
    return x + y
```

### 使用上下文管理器
```python
# 修復前
f = open("file.txt")
data = f.read()
f.close()

# 修復後
with open("file.txt") as f:
    data = f.read()
```

### 使用列表推導式 (List Comprehensions)
```python
# 修復前
result = []
for item in items:
    if item.active:
        result.append(item.name)

# 修復後
result = [item.name for item in items if item.active]
```

### 修正可變預設參數
```python
# 修復前
def append(value, items=[]):
    items.append(value)
    return items

# 修復後
def append(value, items=None):
    if items is None:
        items = []
    items.append(value)
    return items
```

### 使用 f-strings (Python 3.6+)
```python
# 修復前
name = "Alice"
greeting = "Hello, " + name + "!"
greeting2 = "Hello, {}".format(name)

# 修復後
greeting = f"Hello, {name}!"
```

### 修正迴圈中的字串拼接
```python
# 修復前
result = ""
for item in items:
    result += str(item)

# 修復後
result = "".join(str(item) for item in items)
```

## Python 版本相容性

審查者會指示程式碼何時使用了較新版本的特性：

| 特性 | 最低 Python 版本 |
|---------|----------------|
| 型別提示 (Type hints) | 3.5+ |
| f-strings | 3.6+ |
| 海象運算子 (Walrus operator `:=`) | 3.8+ |
| 僅限位置參數 (Position-only) | 3.8+ |
| Match 語句 | 3.10+ |
| 型別聯集 (Type unions `x | None`) | 3.10+ |

請確保您的 `pyproject.toml` 或 `setup.py` 指定了正確的最低 Python 版本。