7.1 KiB

Raw Blame History

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

Python 程式碼審查 (Python Code Review)

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

此指令的功能

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

何時使用

在以下情況使用 /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 進行格式化。
不必要的列表建立。

執行的自動化檢查

# 型別檢查
mypy .

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

# 安全掃描
bandit -r .

# 依賴項稽核
pip-audit
safety check

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

使用範例

使用者：/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}"  # 錯誤

修復方案: 使用參數化查詢

query = "SELECT * FROM users WHERE id = %s"  # 正確
cursor.execute(query, (user_id,))

[HIGH] 可變預設參數 (Mutable default argument) 檔案: app/services/auth.py:18 問題: 可變預設參數會導致狀態共享

def process_items(items=[]):  # 錯誤
    items.append("new")
    return items

修復方案: 使用 None 作為預設值

def process_items(items=None):  # 正確
    if items is None:
        items = []
    items.append("new")
    return items

[MEDIUM] 缺少型別提示檔案: app/services/auth.py:25 問題: 公共函式缺少型別註解

def get_user(user_id):  # 錯誤
    return db.find(user_id)

修復方案: 加入型別提示

def get_user(user_id: str) -> Optional[User]:  # 正確
    return db.find(user_id)

[MEDIUM] 未使用上下文管理器檔案: app/routes/user.py:55 問題: 發生異常時檔案未關閉

f = open("config.json")  # 錯誤
data = f.read()
f.close()

修復方案: 使用 context manager

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

使用上下文管理器

# 修復前
f = open("file.txt")
data = f.read()
f.close()

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

使用列表推導式 (List Comprehensions)

# 修復前
result = []
for item in items:
    if item.active:
        result.append(item.name)

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

修正可變預設參數

# 修復前
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+)

# 修復前
name = "Alice"
greeting = "Hello, " + name + "!"
greeting2 = "Hello, {}".format(name)

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

修正迴圈中的字串拼接

# 修復前
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`)

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

7.1 KiB Raw Blame History Unescape Escape