@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/backend-common-issues.md

@@ -0,0 +1,589 @@
+# 后端常见问题检查清单 (Backend Common Issues)
+
+> 后端开发中经常出现的 Bug 和问题，代码审查时必须逐项检查。
+
+---
+
+## 🔴 P0 级问题 (必须修复)
+
+### 1. 并发与线程安全问题
+
+#### 1.1 共享状态竞态条件
+
+```python
+# ❌ 错误：修改共享的单例对象
+class ChatService:
+    def __init__(self):
+        self.agent = load_agent()  # 单例，所有请求共享
+
+    async def chat(self, user_input, llm_id=None):
+        if llm_id:
+            self.agent.llm_provider_id = llm_id  # 竞态条件！影响其他用户
+        return await self.agent.run(user_input)
+
+# ✅ 正确：传递参数而非修改共享状态
+class ChatService:
+    def __init__(self):
+        self.agent = load_agent()
+
+    async def chat(self, user_input, llm_id=None):
+        # 传递参数，不修改共享对象
+        return await self.agent.run(user_input, override_llm_id=llm_id)
+```
+
+**检查点**:
+- [ ] 是否修改了单例/全局对象的属性
+- [ ] 请求级数据是否存储在共享对象中
+- [ ] 是否有线程/协程安全的数据结构
+
+#### 1.2 数据库事务问题
+
+```python
+# ❌ 错误：事务范围不正确
+async def transfer_money(from_id, to_id, amount):
+    from_account = await db.get(from_id)
+    from_account.balance -= amount
+    await db.save(from_account)  # 如果下面失败，钱已扣除！
+
+    to_account = await db.get(to_id)
+    to_account.balance += amount
+    await db.save(to_account)
+
+# ✅ 正确：使用事务
+async def transfer_money(from_id, to_id, amount):
+    async with db.transaction():
+        from_account = await db.get(from_id)
+        to_account = await db.get(to_id)
+
+        if from_account.balance < amount:
+            raise InsufficientFundsError()
+
+        from_account.balance -= amount
+        to_account.balance += amount
+
+        await db.save(from_account)
+        await db.save(to_account)
+```
+
+**检查点**:
+- [ ] 多表操作是否在同一事务中
+- [ ] 事务隔离级别是否正确
+- [ ] 是否有死锁风险
+
+#### 1.3 异步任务错误处理
+
+```python
+# ❌ 错误：后台任务错误被吞掉
+asyncio.create_task(send_notification(user_id))  # 失败了也不知道
+
+# ✅ 正确：添加错误回调
+task = asyncio.create_task(send_notification(user_id))
+
+def handle_error(t):
+    if not t.cancelled() and t.exception():
+        logger.error(f"Background task failed: {t.exception()}")
+        # 可选：发送告警、重试等
+
+task.add_done_callback(handle_error)
+
+# ✅ Python 3.11+ 使用 TaskGroup
+async with asyncio.TaskGroup() as tg:
+    tg.create_task(send_notification(user_id))
+```
+
+**检查点**:
+- [ ] 后台任务是否有错误处理
+- [ ] 是否有任务超时机制
+- [ ] 失败任务是否有重试策略
+
+---
+
+### 2. 数据库问题
+
+#### 2.1 N+1 查询问题
+
+```python
+# ❌ 错误：N+1 查询
+users = await User.all()  # 1 次查询
+for user in users:
+    orders = await user.orders.all()  # N 次查询！
+    print(f"{user.name}: {len(orders)} orders")
+
+# ✅ 正确：预加载关联数据
+users = await User.all().prefetch_related('orders')  # 2 次查询
+for user in users:
+    print(f"{user.name}: {len(user.orders)} orders")
+
+# ✅ 或使用 JOIN
+users = await User.all().select_related('profile')  # 1 次 JOIN 查询
+```
+
+**检查点**:
+- [ ] 循环中是否有数据库查询
+- [ ] 是否使用了 prefetch_related/select_related
+- [ ] 是否有 SQL 日志监控 N+1
+
+#### 2.2 SQL 注入
+
+```python
+# ❌ 危险：字符串拼接 SQL
+user_id = request.args.get('id')
+query = f"SELECT * FROM users WHERE id = {user_id}"  # SQL 注入！
+cursor.execute(query)
+
+# ✅ 安全：参数化查询
+cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
+
+# ✅ 使用 ORM
+user = await User.get(id=user_id)
+```
+
+**检查点**:
+- [ ] 是否有字符串拼接 SQL
+- [ ] 是否使用参数化查询
+- [ ] 动态表名/列名是否经过白名单验证
+
+#### 2.3 连接泄漏
+
+```python
+# ❌ 错误：连接未释放
+async def get_data():
+    conn = await pool.acquire()
+    result = await conn.fetch("SELECT * FROM data")
+    return result  # 连接未释放！
+
+# ✅ 正确：使用上下文管理器
+async def get_data():
+    async with pool.acquire() as conn:
+        result = await conn.fetch("SELECT * FROM data")
+        return result
+
+# ✅ 或使用 try-finally
+async def get_data():
+    conn = await pool.acquire()
+    try:
+        result = await conn.fetch("SELECT * FROM data")
+        return result
+    finally:
+        await pool.release(conn)
+```
+
+**检查点**:
+- [ ] 数据库连接是否正确释放
+- [ ] 是否使用连接池
+- [ ] 连接池配置是否合理
+
+---
+
+### 3. API 设计问题
+
+#### 3.1 缺少输入验证
+
+```python
+# ❌ 错误：没有验证输入
+@app.post("/users")
+async def create_user(data: dict):
+    user = User(**data)  # 任意字段都能传入！
+    await user.save()
+    return user
+
+# ✅ 正确：使用 Pydantic 验证
+from pydantic import BaseModel, EmailStr, constr
+
+class CreateUserRequest(BaseModel):
+    email: EmailStr
+    password: constr(min_length=8)
+    name: constr(min_length=1, max_length=100)
+
+@app.post("/users")
+async def create_user(data: CreateUserRequest):
+    user = User(**data.dict())
+    await user.save()
+    return user
+```
+
+**检查点**:
+- [ ] 所有输入是否有类型验证
+- [ ] 字符串是否有长度限制
+- [ ] 数字是否有范围限制
+- [ ] 是否验证了必填字段
+
+#### 3.2 缺少权限检查
+
+```python
+# ❌ 错误：没有权限检查
+@app.get("/users/{user_id}/orders")
+async def get_user_orders(user_id: int):
+    return await Order.filter(user_id=user_id).all()  # 任何人都能查！
+
+# ✅ 正确：检查权限
+@app.get("/users/{user_id}/orders")
+async def get_user_orders(user_id: int, current_user: User = Depends(get_current_user)):
+    # 只能查自己的订单，或者是管理员
+    if current_user.id != user_id and not current_user.is_admin:
+        raise HTTPException(status_code=403, detail="Forbidden")
+    return await Order.filter(user_id=user_id).all()
+```
+
+**检查点**:
+- [ ] 每个端点是否有认证检查
+- [ ] 是否验证了资源所有权
+- [ ] 管理员操作是否有额外验证
+
+#### 3.3 错误响应不一致
+
+```python
+# ❌ 错误：错误响应格式不一致
+@app.get("/users/{id}")
+async def get_user(id: int):
+    user = await User.get_or_none(id=id)
+    if not user:
+        return {"error": "not found"}  # 有时返回这个
+        # raise HTTPException(404)  # 有时抛异常
+        # return None  # 有时返回 None
+
+# ✅ 正确：统一错误处理
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request, exc):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "error": {
+                "code": exc.status_code,
+                "message": exc.detail
+            }
+        }
+    )
+
+@app.get("/users/{id}")
+async def get_user(id: int):
+    user = await User.get_or_none(id=id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+```
+
+**检查点**:
+- [ ] 错误响应格式是否统一
+- [ ] 是否有全局异常处理器
+- [ ] 错误信息是否对用户友好
+
+---
+
+### 4. 安全问题
+
+#### 4.1 密码存储不安全
+
+```python
+# ❌ 危险：明文存储密码
+user.password = request.password  # 明文！
+
+# ❌ 危险：使用 MD5/SHA1
+import hashlib
+user.password = hashlib.md5(request.password.encode()).hexdigest()
+
+# ✅ 安全：使用 bcrypt
+from passlib.hash import bcrypt
+
+user.password_hash = bcrypt.hash(request.password)
+
+# 验证密码
+if bcrypt.verify(request.password, user.password_hash):
+    # 密码正确
+```
+
+**检查点**:
+- [ ] 密码是否使用 bcrypt/argon2 加密
+- [ ] 是否有密码强度要求
+- [ ] 密码是否在日志中出现
+
+#### 4.2 命令注入
+
+```python
+# ❌ 危险：shell=True + 用户输入
+import subprocess
+filename = request.args.get('file')
+subprocess.run(f"cat {filename}", shell=True)  # 命令注入！
+
+# ✅ 安全：使用列表参数
+subprocess.run(["cat", filename])  # 安全
+
+# ✅ 更安全：验证输入
+import re
+if not re.match(r'^[a-zA-Z0-9_.-]+$', filename):
+    raise ValueError("Invalid filename")
+subprocess.run(["cat", filename])
+```
+
+**检查点**:
+- [ ] 是否使用了 shell=True
+- [ ] 用户输入是否直接用于命令
+- [ ] 是否有输入白名单验证
+
+#### 4.3 敏感信息泄露
+
+```python
+# ❌ 错误：日志中记录敏感信息
+logger.info(f"User login: {username}, password: {password}")
+logger.error(f"API call failed: {api_key}")
+
+# ❌ 错误：错误信息暴露内部细节
+except Exception as e:
+    return {"error": str(e)}  # 可能暴露堆栈、SQL 等
+
+# ✅ 正确：脱敏日志
+logger.info(f"User login: {username}")
+logger.error(f"API call failed: {api_key[:4]}****")
+
+# ✅ 正确：通用错误信息
+except Exception as e:
+    logger.exception("Internal error")  # 内部记录详情
+    return {"error": "Internal server error"}  # 对外通用信息
+```
+
+**检查点**:
+- [ ] 日志是否记录了密码/token/密钥
+- [ ] 错误响应是否暴露了内部细节
+- [ ] 是否有敏感信息脱敏机制
+
+---
+
+## 🟠 P1 级问题 (应该修复)
+
+### 5. 性能问题
+
+#### 5.1 缺少超时设置
+
+```python
+# ❌ 错误：没有超时
+response = requests.get(external_api_url)  # 可能永远等待
+
+# ✅ 正确：设置超时
+response = requests.get(external_api_url, timeout=10)
+
+# ✅ 异步版本
+async with aiohttp.ClientSession() as session:
+    async with session.get(url, timeout=aiohttp.ClientTimeout(total=10)) as resp:
+        return await resp.json()
+```
+
+**检查点**:
+- [ ] HTTP 请求是否有超时
+- [ ] 数据库查询是否有超时
+- [ ] 外部服务调用是否有超时
+
+#### 5.2 缺少重试机制
+
+```python
+# ❌ 错误：没有重试
+def call_external_api():
+    return requests.get(api_url).json()  # 失败就失败
+
+# ✅ 正确：指数退避重试
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=1, min=1, max=10)
+)
+def call_external_api():
+    response = requests.get(api_url, timeout=10)
+    response.raise_for_status()
+    return response.json()
+```
+
+**检查点**:
+- [ ] 外部调用是否有重试
+- [ ] 重试是否使用指数退避
+- [ ] 是否有最大重试次数限制
+
+#### 5.3 缓存问题
+
+```python
+# ❌ 错误：缓存穿透 - 不存在的数据反复查库
+def get_user(user_id):
+    cached = redis.get(f"user:{user_id}")
+    if cached:
+        return cached
+    user = db.query(User).get(user_id)
+    if user:
+        redis.set(f"user:{user_id}", user, ex=3600)
+    return user  # None 不缓存，下次还查库
+
+# ✅ 正确：缓存空值
+def get_user(user_id):
+    cached = redis.get(f"user:{user_id}")
+    if cached == "NULL":
+        return None
+    if cached:
+        return cached
+    user = db.query(User).get(user_id)
+    if user:
+        redis.set(f"user:{user_id}", user, ex=3600)
+    else:
+        redis.set(f"user:{user_id}", "NULL", ex=60)  # 短期缓存空值
+    return user
+```
+
+**检查点**:
+- [ ] 是否有缓存穿透防护
+- [ ] 缓存是否有过期时间
+- [ ] 数据更新时是否清除缓存
+
+---
+
+### 6. 可观测性问题
+
+#### 6.1 日志不足
+
+```python
+# ❌ 错误：没有日志
+async def process_order(order_id):
+    order = await Order.get(order_id)
+    await payment_service.charge(order.amount)
+    order.status = "paid"
+    await order.save()
+
+# ✅ 正确：关键操作有日志
+async def process_order(order_id):
+    logger.info(f"Processing order: {order_id}")
+    order = await Order.get(order_id)
+
+    logger.info(f"Charging amount: {order.amount}")
+    try:
+        await payment_service.charge(order.amount)
+    except PaymentError as e:
+        logger.error(f"Payment failed for order {order_id}: {e}")
+        raise
+
+    order.status = "paid"
+    await order.save()
+    logger.info(f"Order {order_id} completed successfully")
+```
+
+**检查点**:
+- [ ] 关键业务操作是否有日志
+- [ ] 错误是否有详细日志
+- [ ] 日志是否包含追踪 ID
+
+#### 6.2 缺少健康检查
+
+```python
+# ❌ 错误：没有健康检查端点
+# 无法知道服务是否正常
+
+# ✅ 正确：完整的健康检查
+@app.get("/health")
+async def health_check():
+    checks = {}
+
+    # 检查数据库
+    try:
+        await db.execute("SELECT 1")
+        checks["database"] = "healthy"
+    except Exception as e:
+        checks["database"] = f"unhealthy: {e}"
+
+    # 检查 Redis
+    try:
+        await redis.ping()
+        checks["redis"] = "healthy"
+    except Exception as e:
+        checks["redis"] = f"unhealthy: {e}"
+
+    status = "healthy" if all(v == "healthy" for v in checks.values()) else "unhealthy"
+    return {"status": status, "checks": checks}
+```
+
+**检查点**:
+- [ ] 是否有 /health 端点
+- [ ] 健康检查是否包含依赖服务
+- [ ] 是否有 /ready 端点（K8s）
+
+---
+
+### 7. 资源管理问题
+
+#### 7.1 文件句柄泄漏
+
+```python
+# ❌ 错误：文件未关闭
+def read_file(path):
+    f = open(path)
+    content = f.read()
+    return content  # 文件未关闭！
+
+# ✅ 正确：使用上下文管理器
+def read_file(path):
+    with open(path) as f:
+        return f.read()
+```
+
+**检查点**:
+- [ ] 文件是否使用 with 语句
+- [ ] 网络连接是否正确关闭
+- [ ] 是否有资源泄漏风险
+
+#### 7.2 内存泄漏
+
+```python
+# ❌ 错误：无限增长的缓存
+cache = {}
+
+def get_data(key):
+    if key not in cache:
+        cache[key] = expensive_computation(key)  # 永远不清理！
+    return cache[key]
+
+# ✅ 正确：使用 LRU 缓存
+from functools import lru_cache
+
+@lru_cache(maxsize=1000)
+def get_data(key):
+    return expensive_computation(key)
+
+# ✅ 或使用 TTL 缓存
+from cachetools import TTLCache
+
+cache = TTLCache(maxsize=1000, ttl=3600)
+```
+
+**检查点**:
+- [ ] 缓存是否有大小限制
+- [ ] 是否有内存泄漏风险
+- [ ] 长时间运行是否会 OOM
+
+---
+
+## 📋 后端检查清单汇总
+
+```markdown
+## 后端代码审查检查清单
+
+### P0 必须检查
+- [ ] 竞态条件：不修改共享单例状态
+- [ ] 事务边界：多表操作在同一事务
+- [ ] 后台任务：有错误处理回调
+- [ ] N+1 查询：使用预加载
+- [ ] SQL 注入：使用参数化查询
+- [ ] 连接泄漏：使用上下文管理器
+- [ ] 输入验证：所有输入都验证
+- [ ] 权限检查：每个端点都检查
+- [ ] 密码存储：使用 bcrypt/argon2
+- [ ] 命令注入：不用 shell=True
+- [ ] 敏感信息：不在日志/响应中暴露
+
+### P1 应该检查
+- [ ] 超时设置：所有外部调用有超时
+- [ ] 重试机制：外部调用有重试
+- [ ] 缓存穿透：缓存空值
+- [ ] 日志完整：关键操作有日志
+- [ ] 健康检查：有 /health 端点
+- [ ] 资源管理：文件/连接正确关闭
+- [ ] 内存管理：缓存有大小限制
+
+### 错误响应检查
+- [ ] 格式统一：所有错误响应格式一致
+- [ ] 信息友好：错误信息对用户友好
+- [ ] 不泄露：不暴露内部细节
+```