ai-developer-skill-os 8.1.7 → 8.1.9

package/.agents/skills/qk-code-review/references/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/.agents/skills/qk-code-review/references/cross-cutting/performance-review-guide.md

@@ -0,0 +1,387 @@
+# Hướng dẫn Review Hiệu năng (Performance Review Guide)
+
+Bí kíp đánh giá hiệu năng toàn diện, bao phủ từ Frontend, Backend, Database, Độ phức tạp thuật toán (Algorithm complexity) cho đến hiệu năng API.
+
+## Mục lục
+
+- [Hiệu năng Frontend (Core Web Vitals)](#hiệu-năng-frontend-core-web-vitals)
+- [Hiệu năng JavaScript](#hiệu-năng-javascript)
+- [Quản lý Bộ nhớ (Memory Management)](#quản-lý-bộ-nhớ)
+- [Hiệu năng Database](#hiệu-năng-database)
+- [Hiệu năng API](#hiệu-năng-api)
+- [Độ phức tạp Thuật toán](#độ-phức-tạp-thuật-toán)
+- [Checklist Đánh giá Hiệu năng](#checklist-đánh-giá-hiệu-năng)
+- [Anti-pattern Hiệu suất cấp thấp](#anti-pattern-hiệu-suất-cấp-thấp)
+
+---
+
+## Hiệu năng Frontend (Core Web Vitals)
+
+### Các chỉ số cốt lõi (Core Vitals 2024)
+
+| Chỉ số | Tên đầy đủ | Mục tiêu | Ý nghĩa |
+|------|------|--------|------|
+| **LCP** | Largest Contentful Paint | ≤ 2.5s | Thời gian render phần tử lớn nhất trên màn hình |
+| **INP** | Interaction to Next Paint | ≤ 200ms | Độ trễ phản hồi tương tác (Thay thế FID từ 2024) |
+| **CLS** | Cumulative Layout Shift | ≤ 0.1 | Độ giật / Xê dịch layout cộng dồn |
+| **FCP** | First Contentful Paint | ≤ 1.8s | Thời gian render nội dung đầu tiên |
+| **TBT** | Total Blocking Time | ≤ 200ms | Tổng thời gian Main Thread bị block |
+
+### Tối ưu LCP
+
+```html
+<!-- ❌ Lazy load hình ảnh LCP - Làm chậm nội dung quan trọng -->
+<img src="hero.jpg" loading="lazy" />
+
+<!-- ✅ Load ngay lập tức hình ảnh LCP -->
+<img src="hero.jpg" fetchpriority="high" />
+
+<!-- ❌ Định dạng ảnh cũ, nặng -->
+<img src="hero.png" />  <!-- File PNG quá to -->
+
+<!-- ✅ Dùng định dạng hiện đại + Responsive -->
+<picture>
+  <source srcset="hero.avif" type="image/avif" />
+  <source srcset="hero.webp" type="image/webp" />
+  <img src="hero.jpg" alt="Hero" />
+</picture>
+```
+
+**Checklist LCP:**
+- [ ] Phần tử LCP có được set `fetchpriority="high"` không?
+- [ ] Đã dùng định dạng WebP/AVIF chưa?
+- [ ] Có Server-Side Rendering (SSR) hoặc Static Site Generation (SSG) không?
+- [ ] CDN đã cấu hình đúng chưa?
+
+### Tối ưu FCP
+
+```html
+<!-- ❌ CSS chặn render (Render-blocking) -->
+<link rel="stylesheet" href="all-styles.css" />
+
+<!-- ✅ Inline CSS quan trọng (Critical CSS) + Load bất đồng bộ phần còn lại -->
+<style>/* Critical CSS cho màn hình đầu tiên */</style>
+<link rel="preload" href="styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'" />
+
+<!-- ❌ Font chữ chặn render -->
+@font-face {
+  font-family: 'CustomFont';
+  src: url('font.woff2');
+}
+
+<!-- ✅ Tối ưu hiển thị Font -->
+@font-face {
+  font-family: 'CustomFont';
+  src: url('font.woff2');
+  font-display: swap;  /* Dùng font hệ thống trước, load xong sẽ tráo đổi */
+}
+```
+
+### Tối ưu INP
+
+```javascript
+// ❌ Long task block Main Thread
+button.addEventListener('click', () => {
+  // Thao tác đồng bộ tốn 500ms
+  processLargeData(data);
+  updateUI();
+});
+
+// ✅ Chia nhỏ Long task
+button.addEventListener('click', async () => {
+  // Trả lại quyền điều khiển cho Main Thread
+  await scheduler.yield?.() ?? new Promise(r => setTimeout(r, 0));
+
+  // Xử lý từng lô nhỏ (chunk)
+  for (const chunk of chunks) {
+    processChunk(chunk);
+    await scheduler.yield?.();
+  }
+  updateUI();
+});
+
+// ✅ Đẩy tính toán nặng sang Web Worker
+const worker = new Worker('heavy-computation.js');
+worker.postMessage(data);
+worker.onmessage = (e) => updateUI(e.data);
+```
+
+### Tối ưu CLS
+
+```css
+/* ❌ Hình ảnh/Video không có kích thước cố định */
+img { width: 100%; }
+
+/* ✅ Đặt trước không gian (Aspect ratio) */
+img {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+
+/* ❌ Nội dung động gây đẩy layout (Shift) */
+.ad-container { }
+
+/* ✅ Dự phòng chiều cao cố định */
+.ad-container {
+  min-height: 250px;
+}
+```
+
+---
+
+## Hiệu năng JavaScript
+
+### Code Splitting & Lazy Loading
+
+```javascript
+// ❌ Load toàn bộ code một lúc
+import { HeavyChart } from './charts';
+import { PDFExporter } from './pdf';
+
+// ✅ Tải ngầm theo nhu cầu (On-demand / Lazy)
+const HeavyChart = lazy(() => import('./charts'));
+const PDFExporter = lazy(() => import('./pdf'));
+
+// ✅ Chia code theo Route (Route-based splitting)
+const routes = [
+  { path: '/dashboard', component: lazy(() => import('./pages/Dashboard')) }
+];
+```
+
+### Tối ưu kích thước Bundle (Bundle Size)
+
+```javascript
+// ❌ Import nguyên cả cái thư viện bự
+import _ from 'lodash';
+import moment from 'moment';
+
+// ✅ Import đích danh hàm cần dùng
+import debounce from 'lodash/debounce';
+import { format } from 'date-fns';
+
+// ❌ Tránh việc không dùng Tree Shaking
+export default { fn1() {}, fn2() {} }; // fn2 không xài cũng bị gom vào bundle
+
+// ✅ Export đích danh để hỗ trợ Tree Shaking
+export function fn1() {}
+export function fn2() {}
+```
+
+### Tối ưu Render danh sách (List Rendering)
+
+```javascript
+// ❌ Render hàng ngàn DOM Node cùng lúc
+function List({ items }) {
+  return (
+    <ul>
+      {items.map(item => <li key={item.id}>{item.name}</li>)}
+    </ul>
+  );
+}
+
+// ✅ Dùng Virtual List (Cuộn ảo) - Chỉ render phần đang nhìn thấy trên màn hình
+import { FixedSizeList } from 'react-window';
+
+function VirtualList({ items }) {
+  return (
+    <FixedSizeList height={400} itemCount={items.length} itemSize={35}>
+      {({ index, style }) => <div style={style}>{items[index].name}</div>}
+    </FixedSizeList>
+  );
+}
+```
+
+---
+
+## Quản lý Bộ nhớ (Memory Management)
+
+### Các dạng rò rỉ bộ nhớ (Memory Leaks) điển hình
+
+**1. Quên gỡ Event Listener**
+```javascript
+// ❌ Unmount nhưng Event vẫn chạy
+useEffect(() => { window.addEventListener('resize', handleResize); }, []);
+
+// ✅ Cleanup Event Listener
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+  return () => window.removeEventListener('resize', handleResize);
+}, []);
+```
+
+**2. Quên xóa Timer (Interval/Timeout)**
+```javascript
+// ✅ Luôn luôn clearInterval
+useEffect(() => {
+  const timer = setInterval(fetchData, 5000);
+  return () => clearInterval(timer);
+}, []);
+```
+
+**3. Rò rỉ qua Closure**
+```javascript
+// ❌ Closure giữ lại tham chiếu mảng khổng lồ không cần thiết
+function createHandler() {
+  const largeData = new Array(1000000).fill('x');
+  return function handler() { console.log(largeData.length); }; // Giữ luôn nguyên cái mảng
+}
+
+// ✅ Chỉ giữ lại giá trị thực sự cần
+function createHandler() {
+  const largeData = new Array(1000000).fill('x');
+  const length = largeData.length;  // Chỉ lưu cái số đếm
+  return function handler() { console.log(length); };
+}
+```
+
+**4. Rò rỉ qua Connection (WebSocket/SSE)**
+- Luôn gọi `ws.close()` trong hàm cleanup.
+
+---
+
+## Hiệu năng Database
+
+### Vấn đề N+1 Queries
+> Xem chi tiết tại [N+1 Queries Checklist](n-plus-one-queries.md)
+
+```python
+# ❌ N+1
+users = User.objects.all()  # 1 Query
+for user in users:
+    print(user.profile.bio)  # N Queries
+
+# ✅ Eager Loading
+users = User.objects.select_related('profile').all()  # 2 Queries
+```
+
+### Tối ưu Index (Chỉ mục)
+
+```sql
+-- ❌ Full table scan (Quét toàn bảng)
+SELECT * FROM orders WHERE status = 'pending';
+
+-- ✅ Đánh Index
+CREATE INDEX idx_orders_status ON orders(status);
+
+-- ❌ Lỗi mất Index: Chạy Hàm trên cột
+SELECT * FROM users WHERE YEAR(created_at) = 2024;
+
+-- ✅ Đổi thành Range Query để xài được Index
+SELECT * FROM users WHERE created_at >= '2024-01-01' AND created_at < '2025-01-01';
+
+-- ❌ Lỗi mất Index: LIKE '%...' (Có dấu % ở đầu)
+SELECT * FROM products WHERE name LIKE '%phone%';
+```
+
+### Tối ưu Query
+
+```sql
+-- ❌ Dùng SELECT * lấy những cột không cần thiết
+SELECT * FROM users WHERE id = 1;
+
+-- ✅ Chỉ select các cột thực sự cần
+SELECT id, name, email FROM users WHERE id = 1;
+
+-- ❌ Lấy cả bảng siêu to mà không có LIMIT
+SELECT * FROM logs WHERE type = 'error';
+
+-- ✅ Luôn có Phân trang (Pagination/LIMIT)
+SELECT * FROM logs WHERE type = 'error' LIMIT 100 OFFSET 0;
+```
+
+---
+
+## Hiệu năng API
+
+### Phân trang (Pagination)
+Tuyệt đối KHÔNG BAO GIỜ trả về nguyên cái Array không giới hạn (Unbounded Array). Luôn luôn nhận vào `page` và `limit` (max 100).
+
+### Caching (Bộ nhớ đệm)
+```javascript
+// ✅ Dùng Redis
+const cached = await redis.get(cacheKey);
+if (cached) return JSON.parse(cached);
+
+// ✅ Cấu hình HTTP Cache Headers
+res.set({
+  'Cache-Control': 'public, max-age=86400',  // 24 giờ
+  'ETag': 'abc123',
+});
+```
+
+### Nén phản hồi (Response Compression)
+```javascript
+// ✅ Kích hoạt Gzip / Brotli
+const compression = require('compression');
+app.use(compression());
+```
+
+### Giới hạn Tốc độ (Rate Limiting)
+- Bảo vệ API bằng cách giới hạn số lượng request từ 1 IP/User trong khoảng thời gian nhất định.
+
+---
+
+## Độ phức tạp Thuật toán (Algorithm Complexity)
+
+| Độ phức tạp | Ký hiệu | Ý nghĩa | 10 record | 1000 record | Ví dụ |
+|--------|------|-------|-------|---------|------|
+| **O(1)** | Constant | Cố định | 1 | 1 | Hash map (Dict/Map) / Tra cứu Index |
+| **O(log n)**| Logarithmic | Tăng rất chậm | 3 | 10 | Tìm kiếm nhị phân |
+| **O(n)** | Linear | Tuyến tính | 10 | 1000 | Vòng lặp for 1 cấp |
+| **O(n log n)**| Linearithmic | Hơi tốn | 33 | 10000 | Sort (Sắp xếp) |
+| **O(n²)** | Quadratic | Rất tốn kém | 100 | 1.000.000 | Vòng lặp lồng nhau (Nested loops) |
+
+### Nhận diện O(n²) trong Code Review
+
+```javascript
+// ❌ O(n²) - Gọi includes() bên trong vòng lặp for
+function removeDuplicates(arr) {
+  const result = [];
+  for (const item of arr) {
+    if (!result.includes(item)) {  // .includes() là O(n)
+      result.push(item);
+    }
+  }
+  return result;
+}
+
+// ✅ O(n) - Dùng Set (Cấu trúc dữ liệu O(1) tra cứu)
+function removeDuplicates(arr) {
+  return [...new Set(arr)];
+}
+```
+
+```javascript
+// ❌ O(n) - Dùng find() bừa bãi
+function getUser(id) {
+  return users.find(u => u.id === id);  // Duyệt mảng từ đầu tới cuối
+}
+
+// ✅ O(1) - Biến mảng thành Map để tra cứu siêu tốc
+const userMap = new Map(users.map(u => [u.id, u]));
+function getUser(id) {
+  return userMap.get(id);
+}
+```
+
+---
+
+## Anti-pattern Hiệu suất cấp thấp
+
+### Làm việc thừa (Unnecessary repetitive work)
+- Đọc file `config.json` bên trong vòng lặp thay vì đọc 1 lần đưa ra ngoài.
+- Gọi lại cùng 1 câu lệnh DB Query nhiều lần trong 1 Request.
+
+### Bỏ lỡ cơ hội chạy Song song (Missed Concurrency)
+- Đợi 2 cái Promise độc lập nhau một cách tuần tự (`await A; await B`).
+- Hãy dùng `Promise.all([A, B])` hoặc `Task.WhenAll()`.
+
+### Bùng nổ Dữ liệu không giới hạn (Unbounded data structures)
+```python
+# ❌ Cache vào Dictionary mút mùa không bao giờ đầy, gây Out of Memory (OOM)
+_cache = {}
+
+# ✅ Dùng LRU Cache có giới hạn max size
+from functools import lru_cache
+@lru_cache(maxsize=128)
+```