@linyjs/plugin-docs 0.1.0

package/docs/best-practices/performance.md

@@ -0,0 +1,532 @@
+# 性能优化
+
+本指南提供 linyjs 插件开发中的性能优化最佳实践。
+
+## 为什么需要性能优化？
+
+- ⚡ **提升用户体验** - 减少加载时间和响应时间
+- 💰 **降低资源消耗** - 节省服务器和客户端计算资源
+- 📱 **提高移动端体验** - 在资源受限设备上保持流畅
+- 🎯 **增加用户留存** - 快速响应的应用更容易获得用户喜爱
+
+## 客户端性能优化
+
+### 懒加载组件
+
+```typescript
+// 延迟加载重型组件
+registry.register({
+  id: 'heavy-widget',
+  position: 'admin-dashboard',
+  component: () => {
+    const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
+    return (
+      <React.Suspense fallback={<div>Loading...</div>}>
+        <HeavyComponent />
+      </React.Suspense>
+    );
+  }
+});
+```
+
+### 避免不必要的重渲染
+
+```typescript
+// 使用 React.memo 避免不必要的重渲染
+import { memo } from 'react';
+
+const ExpensiveComponent = memo(({ data }: { data: any }) => {
+  // 复杂计算...
+  return <div>{/* ... */}</div>;
+});
+
+// 使用 useMemo 缓存计算结果
+import { useMemo } from 'react';
+
+function DataList({ items }: { items: any[] }) {
+  const sortedItems = useMemo(() => {
+    return [...items].sort((a, b) => a.name.localeCompare(b.name));
+  }, [items]);
+
+  return (
+    <ul>
+      {sortedItems.map(item => (
+        <li key={item.id}>{item.name}</li>
+      ))}
+    </ul>
+  );
+}
+
+// 使用 useCallback 缓存函数
+import { useCallback } from 'react';
+
+function InteractiveComponent() {
+  const handleClick = useCallback(() => {
+    console.log('Button clicked');
+  }, []);
+
+  return <button onClick={handleClick}>Click me</button>;
+}
+```
+
+### 优化状态管理
+
+```typescript
+// 避免频繁的状态更新
+function OptimizedComponent() {
+  const [data, setData] = useState<any[]>([]);
+
+  // ❌ 避免：批量操作中的多次状态更新
+  const badApproach = () => {
+    items.forEach(item => {
+      setData(prev => [...prev, item]); // 多次更新
+    });
+  };
+
+  // ✅ 推荐：单次状态更新
+  const goodApproach = () => {
+    setData(prev => [...prev, ...items]); // 单次更新
+  };
+
+  return <div>{/* ... */}</div>;
+}
+
+// 使用批处理更新
+import { unstable_batchedUpdates } from 'react-dom';
+
+function BatchUpdateExample() {
+  const [count, setCount] = useState(0);
+  const [data, setData] = useState([]);
+
+  const batchUpdate = () => {
+    unstable_batchedUpdates(() => {
+      setCount(prev => prev + 1);
+      setData(prev => [...prev, 'new item']);
+    });
+  };
+
+  return <button onClick={batchUpdate}>Batch Update</button>;
+}
+```
+
+### 图片和资源优化
+
+```typescript
+// 延迟加载图片
+function LazyImage({ src, alt }: { src: string; alt: string }) {
+  return (
+    <img
+      src={src}
+      alt={alt}
+      loading="lazy"
+      width="300"
+      height="200"
+    />
+  );
+}
+
+// 响应式图片
+function ResponsiveImage() {
+  return (
+    <picture>
+      <source
+        media="(max-width: 768px)"
+        srcSet="/images/mobile-version.jpg"
+      />
+      <source
+        media="(min-width: 769px)"
+        srcSet="/images/desktop-version.jpg"
+      />
+      <img src="/images/fallback.jpg" alt="Responsive content" />
+    </picture>
+  );
+}
+```
+
+## 服务端性能优化
+
+### 数据库查询优化
+
+```typescript
+// ✅ 推荐：使用索引和投影
+class OptimizedArticleService {
+  constructor(private mongodb: IMongoDBService) {}
+
+  async getArticles() {
+    const db = this.mongodb.getDb();
+    const collection = db.collection('articles');
+
+    // 使用索引字段查询
+    return collection
+      .find({
+        status: 'published',
+        createdAt: { $gte: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000) }
+      })
+      .project({
+        title: 1,
+        excerpt: 1,
+        createdAt: 1,
+        // 只选择需要的字段
+      })
+      .sort({ createdAt: -1 })
+      .limit(10)
+      .toArray();
+  }
+
+  // 添加索引
+  async createIndexes() {
+    const db = this.mongodb.getDb();
+    const collection = db.collection('articles');
+
+    await collection.createIndex({ status: 1, createdAt: -1 });
+    await collection.createIndex({ title: 'text', content: 'text' });
+  }
+}
+```
+
+### 缓存策略
+
+```typescript
+// 简单的内存缓存
+class CachedService {
+  private cache = new Map<string, { data: any; timestamp: number }>();
+  private TTL = 5 * 60 * 1000; // 5分钟
+
+  async getData(key: string, fetcher: () => Promise<any>) {
+    const cached = this.cache.get(key);
+    const now = Date.now();
+
+    // 检查缓存是否有效
+    if (cached && (now - cached.timestamp) < this.TTL) {
+      return cached.data;
+    }
+
+    // 获取新数据
+    const data = await fetcher();
+    this.cache.set(key, { data, timestamp: now });
+
+    return data;
+  }
+
+  clearCache() {
+    this.cache.clear();
+  }
+}
+
+// 在处理器中使用缓存
+handler: async (params) => {
+  const cachedService = new CachedService();
+
+  return await cachedService.getData('articles', async () => {
+    // 实际的数据获取逻辑
+    return await fetchArticles();
+  });
+}
+```
+
+### 异步处理
+
+```typescript
+// 处理耗时操作
+class AsyncProcessingService {
+  async processLargeDataset() {
+    // 分页处理大数据集
+    const BATCH_SIZE = 100;
+    let processed = 0;
+    let hasMore = true;
+
+    while (hasMore) {
+      const batch = await this.getBatchData(processed, BATCH_SIZE);
+
+      if (batch.length === 0) {
+        hasMore = false;
+        break;
+      }
+
+      // 并行处理批次
+      await Promise.all(
+        batch.map(item => this.processItem(item))
+      );
+
+      processed += batch.length;
+
+      // 避免阻塞事件循环
+      await new Promise(resolve => setTimeout(resolve, 1));
+    }
+
+    return { processed };
+  }
+
+  private async getBatchData(offset: number, limit: number) {
+    // 获取数据批次
+    const db = this.mongodb.getDb();
+    return db.collection('items')
+      .find()
+      .skip(offset)
+      .limit(limit)
+      .toArray();
+  }
+
+  private async processItem(item: any) {
+    // 处理单个项目
+    return new Promise(resolve => {
+      setTimeout(() => {
+        // 模拟处理
+        resolve(item);
+      }, 10);
+    });
+  }
+}
+```
+
+### 连接池和复用
+
+```typescript
+// MongoDB 连接复用
+class DatabaseService {
+  private static instance: DatabaseService;
+  private db: any;
+
+  private constructor() {
+    // 私有构造函数
+  }
+
+  static getInstance(): DatabaseService {
+    if (!DatabaseService.instance) {
+      DatabaseService.instance = new DatabaseService();
+    }
+    return DatabaseService.instance;
+  }
+
+  async getConnection() {
+    if (!this.db) {
+      // 初始化连接
+      this.db = await connectToDatabase();
+    }
+    return this.db;
+  }
+}
+```
+
+## 网络优化
+
+### 压缩和最小化
+
+```typescript
+// 服务端启用压缩
+handler: async (params, ctx) => {
+  const data = await getData();
+
+  // 启用 Gzip 压缩
+  ctx.response.setHeader('Content-Encoding', 'gzip');
+  ctx.response.setHeader('Content-Type', 'application/json');
+
+  return data;
+}
+
+// 客户端请求优化
+async function fetchOptimizedData() {
+  const response = await fetch('/api/data', {
+    headers: {
+      'Accept-Encoding': 'gzip, deflate',
+      'Accept': 'application/json'
+    },
+    // 避免不必要的预检请求
+    mode: 'cors',
+    credentials: 'same-origin'
+  });
+
+  return response.json();
+}
+```
+
+### 请求批处理和缓存
+
+```typescript
+// 请求批处理
+class BatchRequestService {
+  private requests: Map<string, Promise<any>> = new Map();
+
+  async batchRequest<T>(key: string, fetcher: () => Promise<T>): Promise<T> {
+    // 如果已有相同请求，复用
+    if (this.requests.has(key)) {
+      return this.requests.get(key);
+    }
+
+    const promise = fetcher().finally(() => {
+      // 请求完成后清理
+      this.requests.delete(key);
+    });
+
+    this.requests.set(key, promise);
+    return promise;
+  }
+}
+
+// 使用批处理服务
+const batchService = new BatchRequestService();
+
+// 多个组件可能同时请求相同数据
+const data = await batchService.batchRequest('user-profile', async () => {
+  return await fetch('/api/user/profile').then(res => res.json());
+});
+```
+
+## 构建优化
+
+### 代码分割
+
+```typescript
+// 动态导入实现代码分割
+const AdminDashboard = lazy(() => import('./components/AdminDashboard'));
+const UserSettings = lazy(() => import('./components/UserSettings'));
+
+// 路由级别的代码分割
+function App() {
+  return (
+    <Router>
+      <Suspense fallback={<LoadingSpinner />}>
+        <Routes>
+          <Route path="/admin" element={<AdminDashboard />} />
+          <Route path="/settings" element={<UserSettings />} />
+        </Routes>
+      </Suspense>
+    </Router>
+  );
+}
+```
+
+### Tree Shaking
+
+```typescript
+// 推荐：只导出需要的功能
+export const utils = {
+  formatDate: (date: Date) => date.toLocaleDateString(),
+  formatCurrency: (amount: number) => `$${amount.toFixed(2)}`
+};
+
+// 推荐：分别导出每个功能
+export function formatDate(date: Date) {
+  return date.toLocaleDateString();
+}
+
+export function formatCurrency(amount: number) {
+  return `$${amount.toFixed(2)}`;
+}
+
+// 导入时只引入需要的功能
+import { formatDate } from './utils';
+```
+
+## 性能监控
+
+### 客户端性能监控
+
+```typescript
+// 监控关键性能指标
+function monitorPerformance() {
+  // 首次内容绘制 (FCP)
+  new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+      console.log('FCP:', entry.startTime);
+      // 发送到监控服务
+      reportMetric('fcp', entry.startTime);
+    }
+  }).observe({ entryTypes: ['paint'] });
+
+  // 最大内容绘制 (LCP)
+  new PerformanceObserver((list) => {
+    const entries = list.getEntries();
+    const lastEntry = entries[entries.length - 1];
+    console.log('LCP:', lastEntry.startTime);
+    reportMetric('lcp', lastEntry.startTime);
+  }).observe({ entryTypes: ['largest-contentful-paint'] });
+}
+
+function reportMetric(name: string, value: number) {
+  fetch('/api/metrics', {
+    method: 'POST',
+    body: JSON.stringify({ name, value, timestamp: Date.now() })
+  });
+}
+```
+
+### 服务端性能监控
+
+```typescript
+// 监控请求处理时间
+class PerformanceMiddleware implements IMiddlewareService {
+  async process(payload: any, ctx: any, next: () => Promise<any>) {
+    const startTime = Date.now();
+
+    try {
+      const result = await next();
+      const duration = Date.now() - startTime;
+
+      // 记录性能指标
+      this.recordMetric('request-duration', duration, {
+        method: ctx.request?.method,
+        path: ctx.request?.url
+      });
+
+      return result;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+
+      // 记录错误指标
+      this.recordMetric('request-error-duration', duration, {
+        error: error.message,
+        method: ctx.request?.method,
+        path: ctx.request?.url
+      });
+
+      throw error;
+    }
+  }
+
+  private recordMetric(name: string, value: number, tags: any) {
+    console.log(`[PERF] ${name}: ${value}ms`, tags);
+    // 发送到监控系统
+  }
+}
+```
+
+## 性能优化检查清单
+
+### 开发阶段
+
+- ✅ 启用 React 开发工具检测不必要重渲染
+- ✅ 使用 Chrome DevTools 分析性能瓶颈
+- ✅ 监控组件渲染时间
+- ✅ 检查包大小（bundle size）
+
+### 构建阶段
+
+- ✅ 启用代码分割
+- ✅ 配置 Tree Shaking
+- ✅ 压缩静态资源
+- ✅ 生成 Source Maps
+
+### 部署阶段
+
+- ✅ 启用 Gzip/Brotli 压缩
+- ✅ 配置 CDN 缓存
+- ✅ 使用 HTTP/2
+- ✅ 启用服务端缓存
+
+## 完整示例
+
+查看性能优化实践:
+
+- 📁 [Analytics Plugin 示例](../../examples/analytics-plugin/) - 性能监控实现
+- 📁 [Blog Plugin 示例](../../examples/blog-plugin/) - 数据库查询优化
+
+## 相关文档
+
+- 📝 [命名规范](./naming-conventions.md)
+- ⚠️ [错误处理](./error-handling.md)
+- 🔒 [安全性](./security.md)
+
+---
+
+**上一篇**: [错误处理](./error-handling.md) | **下一篇**: [安全性](./security.md)