@pilllesss/yorn 1.0.182 → 1.0.183

package/dist/skills/code-review/reference/cross-cutting/n-plus-one-queries.md

@@ -0,0 +1,309 @@
+# N+1 查询问题 — 跨语言通用指南
+
+> N+1 查询是 ORM 和数据库访问层最常见的性能反模式。本文档覆盖问题定义、检测方法、通用解决方案和跨语言代码示例。
+
+## 目录
+
+- [问题定义](#问题定义)
+- [性能影响](#性能影响)
+- [检测方法](#检测方法)
+- [通用解决方案](#通用解决方案)
+- [语言特定实现](#语言特定实现)
+- [Review Checklist](#review-checklist)
+
+---
+
+## 问题定义
+
+N+1 查询是指：**1 次查询获取 N 条记录，随后在循环中触发 N 次额外查询**来获取关联数据。
+
+```
+请求流程:
+  1 query   → 获取 N 条主记录
+  N queries → 每条主记录查一次关联数据
+  ─────────
+  Total: 1 + N queries
+```
+
+### 危害
+
+| 问题 | 影响 |
+|------|------|
+| **查询数量线性增长** | 100 条记录 = 101 条 SQL，1000 条 = 1001 条 |
+| **网络延迟叠加** | 每条查询都有往返延迟（RTT），N 次往返 >> 1 次批量查询 |
+| **连接池耗尽** | 大量查询占满数据库连接，拖慢整个应用 |
+| **难以在开发中发现** | 开发环境数据少，N+1 不明显；生产环境数据量大时性能崩塌 |
+
+---
+
+## 性能影响
+
+### 场景对比：获取 100 个用户及其订单
+
+| 方案 | SQL 数量 | 延迟（假设 RTT=1ms） | 适用场景 |
+|------|----------|---------------------|---------|
+| N+1 懒加载 | 101 条 | ~101ms | 极少数据量 |
+| Eager loading (JOIN) | 1 条 | ~1ms | 一对多，数据量适中 |
+| Eager loading (IN) | 2 条 | ~2ms | 多对多，大数据集 |
+| DataLoader / batch | 2 条 | ~2ms | GraphQL / 复杂图查询 |
+
+### SQL 数量对比
+
+```sql
+-- ❌ N+1: 1 + 100 = 101 queries
+SELECT * FROM users;                          -- 1 query
+SELECT * FROM orders WHERE user_id = 1;       -- query 2
+SELECT * FROM orders WHERE user_id = 2;       -- query 3
+...
+SELECT * FROM orders WHERE user_id = 100;     -- query 101
+
+-- ✅ Batch: 2 queries
+SELECT * FROM users;
+SELECT * FROM orders WHERE user_id IN (1,2,...,100);
+```
+
+---
+
+## 检测方法
+
+### 1. ORM SQL 日志
+
+开启 SQL 日志，在测试或开发环境中观察查询数量：
+
+```python
+# Django
+import logging
+logging.getLogger('django.db.backends').setLevel(logging.DEBUG)
+
+# SQLAlchemy
+import logging
+logging.getLogger('sqlalchemy.engine').setLevel(logging.INFO)
+```
+
+```java
+// Spring Boot application.yml
+spring:
+  jpa:
+    show-sql: true
+    properties:
+      hibernate.format_sql: true
+```
+
+```csharp
+// EF Core
+optionsBuilder.LogTo(Console.WriteLine, LogLevel.Information);
+```
+
+### 2. 查询计数断言
+
+在测试中断言 SQL 查询数量：
+
+```python
+# Django: django-assert-num-queries
+from django.test.utils import CaptureQueriesContext
+from django.db import connection
+
+with CaptureQueriesContext(connection) as ctx:
+    list(User.objects.select_related("profile").all())
+assert len(ctx) <= 2  # 预期最多 2 条查询
+```
+
+```java
+// Hibernate: p6spy 或 datasource-proxy
+// 在测试中统计 SQL 执行次数
+assertThat(sqlCount).isLessThanOrEqualTo(2);
+```
+
+### 3. APM / 数据库监控工具
+
+- **Django Debug Toolbar** — 实时显示 SQL 数量和时间
+- **p6spy** (Java) — JDBC 层拦截，记录所有 SQL
+- **MiniProfiler** (.NET) — 页面内嵌 SQL 统计
+- **DataDog / New Relic** — 生产环境慢查询告警
+
+---
+
+## 通用解决方案
+
+### 方案 1: Eager Loading（JOIN 预加载）
+
+一次 JOIN 查询获取主记录和关联记录。适用于一对一、一对多。
+
+### 方案 2: Batch Fetching（IN 子句批量查询）
+
+两次查询：主记录 + `WHERE id IN (...)` 批量获取关联记录。适用于多对多、大数据集。
+
+### 方案 3: DataLoader Pattern
+
+在 GraphQL 或复杂图查询场景中，收集所有需要的 ID，合并为一次批量查询。
+
+```
+// DataLoader 伪代码
+class DataLoader<K, V> {
+    load(K key) → V         // 注册需求，不立即查询
+    loadAll([K]) → [V]      // 合并为一次批量查询
+}
+```
+
+### 方案 4: Projection（投影）
+
+只查询需要的字段，减少数据传输量：
+
+```sql
+-- ❌ 获取所有列
+SELECT * FROM users JOIN profiles ON ...
+
+-- ✅ 只投影需要的字段
+SELECT u.name, p.avatar_url FROM users u JOIN profiles p ON ...
+```
+
+---
+
+## 语言特定实现
+
+### Python / Django
+
+> 详见 [Django Guide](../django.md#n1-查询优化)
+
+```python
+# ForeignKey / OneToOne → select_related (SQL JOIN)
+books = Book.objects.select_related("publisher")
+
+# M2M / reverse FK → prefetch_related (2 queries + Python merge)
+authors = Author.objects.prefetch_related("books")
+
+# 嵌套预加载
+authors = Author.objects.prefetch_related("books__publisher")
+
+# Prefetch 对象精细控制
+from django.db.models import Prefetch
+authors = Author.objects.prefetch_related(
+    Prefetch("books", queryset=Book.objects.filter(published=True), to_attr="published_books")
+)
+```
+
+### Python / SQLAlchemy (FastAPI)
+
+> 详见 [FastAPI Guide](../fastapi.md#database-sessions--n1)
+
+```python
+from sqlalchemy.orm import selectinload
+
+# selectinload: IN 子句批量加载（推荐异步场景）
+stmt = select(Order).options(selectinload(Order.customer))
+
+# joinedload: JOIN 加载
+stmt = select(Order).options(joinedload(Order.customer))
+```
+
+### Java / JPA (Spring Boot)
+
+> 详见 [Java Guide](../java.md)
+
+```java
+// ❌ FetchType.EAGER 或循环中触发懒加载
+@OneToMany(fetch = FetchType.EAGER)  // 危险！
+
+// ✅ JOIN FETCH
+@Query("SELECT u FROM User u JOIN FETCH u.orders")
+List<User> findAllWithOrders();
+
+// ✅ @EntityGraph（声明式）
+@EntityGraph(attributePaths = {"orders", "profile"})
+List<User> findAll();
+
+// ✅ @BatchSize（减少 N+1 为 N/batchSize + 1）
+@OneToMany
+@BatchSize(size = 50)
+private List<Order> orders;
+```
+
+### C# / EF Core
+
+> 详见 [C# Guide](../csharp.md)
+
+```csharp
+// ❌ N+1: foreach 触发懒加载
+foreach (var blog in await context.Blogs.ToListAsync())
+    foreach (var post in blog.Posts)  // 每次循环都查询！
+
+// ✅ Include + ThenInclude
+var blogs = await context.Blogs
+    .Include(b => b.Posts)
+    .ToListAsync();
+
+// ✅ 投影（最安全，避免过度获取）
+var data = await context.Blogs
+    .Select(b => new { b.Url, PostTitles = b.Posts.Select(p => p.Title) })
+    .ToListAsync();
+```
+
+### PHP / Laravel / Doctrine
+
+> 详见 [PHP Guide](../php.md)
+
+```php
+// ❌ 循环内查询
+foreach ($orders as $order) {
+    $customer = $customerRepo->find($order->customerId);
+    render($order, $customer);
+}
+
+// ✅ 批量预加载
+$customerIds = array_unique(array_map(fn($o) => $o->customerId, $orders));
+$customers = $customerRepo->findByIds($customerIds);
+
+foreach ($orders as $order) {
+    render($order, $customers[$order->customerId] ?? null);
+}
+
+// Laravel Eloquent: with()
+$orders = Order::with('customer')->get();
+
+// Doctrine: JOIN FETCH
+$dql = 'SELECT o, c FROM Order o JOIN o.customer c';
+```
+
+### TypeScript / Prisma
+
+```typescript
+// ❌ N+1
+const users = await prisma.user.findMany();
+for (const user of users) {
+    user.posts = await prisma.post.findMany({ where: { userId: user.id } });
+}
+
+// ✅ include（Prisma 自动生成 JOIN 或批量查询）
+const users = await prisma.user.findMany({
+    include: { posts: true },
+});
+
+// ✅ 嵌套 include
+const users = await prisma.user.findMany({
+    include: {
+        posts: {
+            include: { comments: true },
+        },
+    },
+});
+```
+
+---
+
+## Review Checklist
+
+### 检测
+- [ ] 开启了 SQL 日志或查询计数监控
+- [ ] 测试中有查询数量断言
+- [ ] APM 工具配置了 N+1 告警
+
+### 修复
+- [ ] ForeignKey / OneToOne 关系使用 JOIN eager loading
+- [ ] M2M / 反向关系使用 IN 批量预加载
+- [ ] 避免在循环中触发数据库查询
+- [ ] 使用投影只获取需要的字段
+
+### 架构
+- [ ] 列表 API 分页，避免一次加载过多记录
+- [ ] GraphQL 场景使用 DataLoader
+- [ ] 缓存策略（Redis）处理高频读取的关联数据

package/dist/skills/code-review/reference/cross-cutting/sql-injection-prevention.md

@@ -0,0 +1,308 @@
+# SQL Injection Prevention Guide
+
+Language-agnostic SQL injection prevention strategies with cross-language code examples.
+
+> **Related**: [Security Review Guide](../security-review-guide.md) for comprehensive security checklist and decision framework.
+
+## Attack Types
+
+SQL injection (SQLi) is ranked #3 in the OWASP Top 10 (2021). Three common variants:
+
+| Type | Description | Risk |
+|------|-------------|------|
+| **Classic (In-band)** | Attacker receives results directly in the HTTP response | Data exfiltration, authentication bypass |
+| **Blind (Boolean/Time-based)** | Attacker infers data from response differences or timing | Slower but still viable for data extraction |
+| **Out-of-band** | Attacker uses DNS/HTTP callbacks to exfiltrate data | Less common but harder to detect |
+
+## Universal Prevention Strategy
+
+1. **Parameterized queries** — always (the #1 defense)
+2. **ORM safe usage** — understand what your ORM escapes
+3. **Input validation** — whitelist over blacklist
+4. **Least privilege** — database user with minimal permissions
+5. **WAF** — web application firewall as defense-in-depth
+
+---
+
+## Cross-Language Examples
+
+### Python
+
+```python
+# ❌ Vulnerable: string formatting
+query = f"SELECT * FROM users WHERE id = {user_id}"
+cursor.execute(query)
+
+# ❌ Vulnerable: % formatting
+cursor.execute("SELECT * FROM users WHERE id = %s" % user_id)
+
+# ✅ Parameterized (DB-API)
+cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
+
+# ✅ SQLAlchemy ORM
+User.query.filter(User.id == user_id).all()
+
+# ❌ SQLAlchemy raw SQL with string interpolation
+session.execute(text(f"SELECT * FROM users WHERE id = {user_id}"))
+
+# ✅ SQLAlchemy raw SQL with bound parameters
+session.execute(text("SELECT * FROM users WHERE id = :id"), {"id": user_id})
+
+# ✅ Django ORM
+User.objects.filter(id=user_id)
+
+# ❌ Django extra() with string interpolation
+User.objects.extra(where=[f"username = '{username}'"])
+
+# ✅ Django raw() with parameters
+User.objects.raw("SELECT * FROM users WHERE id = %s", [user_id])
+```
+
+### Java
+
+```java
+// ❌ Vulnerable: string concatenation
+String query = "SELECT * FROM users WHERE id = " + userId;
+Statement stmt = connection.createStatement();
+ResultSet rs = stmt.executeQuery(query);
+
+// ✅ JDBC PreparedStatement
+String query = "SELECT * FROM users WHERE id = ?";
+PreparedStatement stmt = connection.prepareStatement(query);
+stmt.setLong(1, userId);
+ResultSet rs = stmt.executeQuery();
+
+// ✅ JPA parameter binding
+@Query("SELECT u FROM User u WHERE u.id = :id")
+User findById(@Param("id") Long id);
+
+// ✅ Spring Data JPA method naming
+User findById(Long id);
+
+// ❌ JPA native query with string concatenation
+entityManager.createNativeQuery(
+    "SELECT * FROM users WHERE name = '" + name + "'"
+);
+
+// ✅ JPA native query with parameter binding
+Query query = entityManager.createNativeQuery(
+    "SELECT * FROM users WHERE name = :name"
+);
+query.setParameter("name", name);
+```
+
+### Go
+
+```go
+// ❌ Vulnerable: fmt.Sprintf
+query := fmt.Sprintf("SELECT * FROM users WHERE id = %s", userID)
+rows, err := db.Query(query)
+
+// ✅ database/sql parameterized
+rows, err := db.Query("SELECT * FROM users WHERE id = ?", userID)
+
+// ✅ Named parameters (sqlx)
+rows, err := db.NamedQuery(
+    "SELECT * FROM users WHERE id = :id",
+    map[string]interface{}{"id": userID},
+)
+
+// ⚠️ Dynamic identifiers (table/column names) can't use placeholders
+// Must validate against whitelist
+var allowedColumns = map[string]bool{
+    "id": true, "name": true, "email": true, "created_at": true,
+}
+
+func queryWithOrder(db *sql.DB, orderBy string) (*sql.Rows, error) {
+    if !allowedColumns[orderBy] {
+        return nil, fmt.Errorf("invalid column: %s", orderBy)
+    }
+    return db.Query(
+        fmt.Sprintf("SELECT * FROM users ORDER BY %s", orderBy),
+    )
+}
+```
+
+### Node.js
+
+```typescript
+// ❌ Vulnerable: template literal
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+const result = await client.query(query);
+
+// ✅ pg parameterized ($1, $2, ...)
+const result = await client.query(
+    "SELECT * FROM users WHERE id = $1",
+    [userId]
+);
+
+// ✅ Prisma ORM (parameterized by default)
+const user = await prisma.user.findUnique({
+    where: { id: userId },
+});
+
+// ❌ Prisma $queryRawUnsafe with string interpolation
+await prisma.$queryRawUnsafe(
+    `SELECT * FROM users WHERE id = ${userId}`
+);
+
+// ✅ Prisma $queryRaw with tagged template (safe)
+await prisma.$queryRaw`
+    SELECT * FROM users WHERE id = ${userId}
+`;
+```
+
+### PHP
+
+```php
+<?php
+
+// ❌ Vulnerable: string concatenation
+$sql = "SELECT * FROM users WHERE email = '" . $_GET['email'] . "'";
+$user = $pdo->query($sql)->fetch();
+
+// ✅ PDO prepared statements
+$stmt = $pdo->prepare("SELECT * FROM users WHERE email = :email");
+$stmt->execute(['email' => $email]);
+$user = $stmt->fetch(PDO::FETCH_ASSOC);
+
+// ✅ PDO positional placeholders
+$stmt = $pdo->prepare("SELECT * FROM users WHERE id = ?");
+$stmt->execute([$id]);
+
+// ❌ mysqli with string interpolation
+$result = mysqli_query($conn,
+    "SELECT * FROM users WHERE id = " . $id
+);
+
+// ✅ mysqli prepared statements
+$stmt = mysqli_prepare($conn, "SELECT * FROM users WHERE id = ?");
+mysqli_stmt_bind_param($stmt, "i", $id);
+mysqli_stmt_execute($stmt);
+
+// ✅ Laravel Eloquent ORM
+User::where('id', $id)->first();
+
+// ❌ Laravel DB::raw with interpolation
+DB::select(DB::raw("SELECT * FROM users WHERE id = {$id}"));
+
+// ✅ Laravel parameterized raw
+DB::select("SELECT * FROM users WHERE id = ?", [$id]);
+```
+
+### C# / .NET
+
+```csharp
+// ❌ Vulnerable: string concatenation
+var query = $"SELECT * FROM Users WHERE Id = {userId}";
+using var cmd = new SqlCommand(query, connection);
+var reader = cmd.ExecuteReader();
+
+// ✅ ADO.NET parameterized
+var query = "SELECT * FROM Users WHERE Id = @Id";
+using var cmd = new SqlCommand(query, connection);
+cmd.Parameters.AddWithValue("@Id", userId);
+
+// ✅ Dapper parameterized
+var users = connection.Query<User>(
+    "SELECT * FROM Users WHERE Id = @Id",
+    new { Id = userId }
+);
+
+// ❌ Dapper with string interpolation
+var users = connection.Query<User>(
+    $"SELECT * FROM Users WHERE Id = {userId}"
+);
+
+// ✅ EF Core (parameterized by default)
+var user = await context.Users
+    .Where(u => u.Id == userId)
+    .FirstOrDefaultAsync();
+
+// ❌ EF Core FromSqlRaw with interpolation
+var users = context.Users
+    .FromSqlRaw($"SELECT * FROM Users WHERE Id = {userId}")
+    .ToList();
+
+// ✅ EF Core FromSql with FormattableString (parameterized)
+var users = context.Users
+    .FromSql($"SELECT * FROM Users WHERE Id = {userId}")
+    .ToList();
+```
+
+---
+
+## ORM Unsafe Usage Patterns
+
+ORMs do NOT automatically prevent SQL injection in all cases:
+
+```python
+# ❌ SQLAlchemy: text() with f-string
+session.execute(text(f"SELECT * FROM users WHERE id = {user_id}"))
+
+# ❌ Django: extra() / RawSQL() with string interpolation
+User.objects.extra(where=[f"username = '{username}'"])
+User.objects.annotate(
+    val=RawSQL(f"SELECT col FROM other WHERE id = {user_id}")
+)
+
+# ❌ JPA: createNativeQuery with string concatenation
+entityManager.createNativeQuery("SELECT * FROM users WHERE name = '" + name + "'")
+
+# ❌ EF Core: FromSqlRaw with string interpolation
+context.Users.FromSqlRaw($"SELECT * FROM Users WHERE Id = {userId}")
+```
+
+**Rule**: Every ORM has a "raw SQL" escape hatch. String interpolation in that escape hatch = SQL injection. Always use the ORM's parameter binding mechanism.
+
+---
+
+## Dynamic Identifiers (Table/Column Names)
+
+Placeholders can only bind **values**, not table names, column names, or SQL keywords. For dynamic identifiers:
+
+```python
+# ✅ Whitelist validation
+ALLOWED_COLUMNS = {"id", "name", "email", "created_at"}
+ALLOWED_DIRECTIONS = {"ASC", "DESC"}
+
+def get_users(order_by: str, direction: str) -> list[User]:
+    if order_by not in ALLOWED_COLUMNS:
+        raise ValueError(f"Invalid column: {order_by}")
+    if direction.upper() not in ALLOWED_DIRECTIONS:
+        raise ValueError(f"Invalid direction: {direction}")
+
+    return User.objects.order_by(
+        f"{'-' if direction.upper() == 'DESC' else ''}{order_by}"
+    )
+```
+
+---
+
+## Detection & Testing
+
+```bash
+# Automated scanning
+sqlmap -u "https://example.com/api/users?id=1" --batch
+
+# Static analysis (Python)
+bandit -r src/ -f custom
+
+# Static analysis (Java)
+spotbugs -textui build/classes
+
+# Code review keywords to search for
+grep -rn "f\".*SELECT\|f'.*SELECT\|fmt.Sprintf.*SELECT\|format.*SELECT" src/
+grep -rn "query.*\+.*\|query.*&\|query.*concat" src/
+```
+
+---
+
+## Review Checklist
+
+- [ ] All SQL queries use parameterized queries (no string interpolation)
+- [ ] ORM raw SQL methods use bound parameters, not string formatting
+- [ ] Dynamic identifiers (table/column names) validated against whitelist
+- [ ] Database user has least privilege (no DROP/ALTER for app user)
+- [ ] No SQL queries constructed from user input without parameterization
+- [ ] Static analysis tools (Bandit, SpotBugs, SonarQube) run in CI