当 AI 替你写代码，ORM 惯性终于不再是借口

# Django ORM — 看起来简洁，实际灾难
orders = Order.objects.filter(user_id=42).order_by("-created_at")[:100]
for order in orders:
    items = order.items.all()          # 每条订单发一次查询
    print(order.id, [i.name for i in items])

SELECT o.id AS order_id, i.name AS item_name
FROM orders o
JOIN order_items oi ON oi.order_id = o.id
JOIN items i ON i.id = oi.item_id
WHERE o.user_id = 42
ORDER BY o.created_at DESC
LIMIT 100;

# CLAUDE.md — 放在项目根目录

## 数据库规则

- 禁止生成 N+1 查询模式。涉及关联数据时，必须使用 JOIN 或子查询在单次查询中完成。
- 优先手写 SQL，而非依赖 ORM 的懒加载机制。
- 所有列表查询必须带 LIMIT；所有分页必须用 keyset pagination（基于排序键），而非 OFFSET。
- WHERE 条件中的列必须与索引定义匹配，避免隐式类型转换。
- 生成 SQL 后，附上对应的索引建议。

请查询用户 42 最近 100 条订单及每条订单的商品名称，
遵循 CLAUDE.md 中的数据库规则，用纯 SQL 实现，
返回 Python 执行代码。

import psycopg2

conn = psycopg2.connect(dsn="postgresql://app:secret@db-host/mydb")

SQL = """
SELECT o.id AS order_id, o.created_at, i.name AS item_name
FROM orders o
JOIN order_items oi ON oi.order_id = o.id
JOIN items i       ON i.id = oi.item_id
WHERE o.user_id = 42
ORDER BY o.created_at DESC
LIMIT 100;
"""

with conn.cursor() as cur:
    cur.execute(SQL)
    rows = cur.fetchall()
    # 按 order_id 分组展示
    from collections import defaultdict
    result = defaultdict(list)
    for order_id, created_at, item_name in rows:
        result[order_id].append(item_name)
    for oid, items in result.items():
        print(f"Order {oid}: {items}")

## NoRM 规则

- 数据访问层使用 raw SQL + 轻量结果映射，不使用 ORM Model 的懒加载。
- 示例模式：

```python
from dataclasses import dataclass

@dataclass
class OrderRow:
    order_id: int
    item_names: list[str]

def get_recent_orders(user_id: int, limit: int = 100) -> list[OrderRow]:
    SQL = """..."""  # 单次 JOIN 查询
    rows = execute(SQL, {"user_id": user_id, "limit": limit})
    return map_rows_to(OrderRow, rows)

当这类模式出现在项目上下文中，AI 会倾向于复用，而非回退到 ORM 默认路径。**你不需要说服开发者改变习惯——你只需要让 AI 看到更好的模式存在于这个项目里。**

## 边界与风险

这条路并非没有隐患：

- **AI 也会犯错**——生成的 SQL 可能遗漏索引提示、选错 JOIN 类型，必须人工 review 执行计划。
- **规则冲突**——如果团队规范强制使用 ORM，CLAUDE.md 的指令会与既有代码风格打架，AI 可能左右摇摆。
- **上下文窗口限制**——复杂查询涉及多表关联时，AI 可能简化甚至跳过规则，需要拆分任务逐步引导。
- **可持续性**——规则写在配置文件里，新成员不一定读；最好配合 CI 中的 SQL 审查工具（如 `sqlfluff`）做自动化校验。

一个务实的起步方式：

```bash
# 安装 sqlfluff，在 CI 中自动检查 AI 生成的 SQL
pip install sqlfluff
sqlfluff lint queries/ --dialect postgres