@linyjs/plugin-docs 0.0.13

package/docs/best-practices/error-handling.md

@@ -0,0 +1,462 @@
+# 错误处理
+
+本指南提供 linyjs 插件开发中的错误处理最佳实践。
+
+## 为什么需要错误处理？
+
+- 🛡️ **提高应用稳定性** - 防止未捕获的错误导致整个应用崩溃
+- 🎯 **改善用户体验** - 提供有意义的错误信息而不是技术细节
+- 🔍 **便于调试** - 记录详细的错误日志帮助定位问题
+- ✅ **可靠性保证** - 确保关键业务流程能够优雅降级
+
+## 服务端错误处理
+
+### 基础错误处理
+
+```typescript
+handler: async (params, ctx) => {
+  try {
+    // 业务逻辑
+    const data = await fetchData();
+    return { success: true, data };
+  } catch (error) {
+    console.error('Error:', error);
+    return {
+      status: 500,
+      data: { error: 'Internal server error' }
+    };
+  }
+}
+```
+
+### 分类错误处理
+
+```typescript
+handler: async (params, ctx) => {
+  try {
+    // 输入验证错误
+    if (!params.body.email) {
+      return {
+        status: 400,
+        data: { error: 'Email is required' }
+      };
+    }
+
+    // 业务逻辑错误
+    const user = await findUser(params.body.email);
+    if (!user) {
+      return {
+        status: 404,
+        data: { error: 'User not found' }
+      };
+    }
+
+    // 权限错误
+    if (!hasPermission(user, 'admin')) {
+      return {
+        status: 403,
+        data: { error: 'Insufficient permissions' }
+      };
+    }
+
+    return { success: true, data: user };
+  } catch (error) {
+    // 系统错误
+    console.error('Database error:', error);
+    return {
+      status: 500,
+      data: { error: 'Internal server error' }
+    };
+  }
+}
+```
+
+### 自定义错误类
+
+```typescript
+// 定义自定义错误类
+class ValidationError extends Error {
+  constructor(message: string, public field?: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+class AuthorizationError extends Error {
+  constructor(message: string = 'Unauthorized') {
+    super(message);
+    this.name = 'AuthorizationError';
+  }
+}
+
+// 在处理器中使用
+handler: async (params, ctx) => {
+  try {
+    if (!isValidEmail(params.body.email)) {
+      throw new ValidationError('Invalid email format', 'email');
+    }
+
+    // ...业务逻辑
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      return {
+        status: 400,
+        data: { error: error.message, field: error.field }
+      };
+    }
+
+    if (error instanceof AuthorizationError) {
+      return {
+        status: 403,
+        data: { error: error.message }
+      };
+    }
+
+    // 处理未知错误
+    return {
+      status: 500,
+      data: { error: 'Internal server error' }
+    };
+  }
+}
+```
+
+### 全局错误处理中间件
+
+```typescript
+import type { IMiddlewareService } from '@linyjs/server-module-interface';
+
+class ErrorHandlingMiddleware implements IMiddlewareService {
+  async process(payload: any, ctx: any, next: () => Promise<any>) {
+    try {
+      return await next();
+    } catch (error) {
+      // 记录错误日志
+      ctx.logger?.error('Unhandled error:', error);
+
+      // 统一错误响应格式
+      return {
+        status: 500,
+        data: {
+          error: 'Internal server error',
+          requestId: ctx.requestId
+        }
+      };
+    }
+  }
+}
+
+export const errorMiddlewareDef = {
+  serviceTag: 'errorMiddleware',
+  serviceImpl: ErrorHandlingMiddleware,
+  meta: { usageType: 'middleware' }
+};
+
+// 在所有路由中使用
+{
+  middlewares: ['errorMiddleware'],
+  handler: async () => {
+    // 安全执行，错误会被中间件捕获
+  }
+}
+```
+
+## 客户端错误处理
+
+### 基本错误边界
+
+```typescript
+import React from 'react';
+
+// 错误边界组件
+class ErrorBoundary extends React.Component<
+  { children: React.ReactNode },
+  { hasError: boolean; error?: Error }
+> {
+  constructor(props: { children: React.ReactNode }) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error: Error) {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+    console.error('Component error:', error, errorInfo);
+    // 发送错误报告到服务器
+    this.reportError(error, errorInfo);
+  }
+
+  reportError = (error: Error, errorInfo: React.ErrorInfo) => {
+    // 报告错误到监控系统
+    fetch('/api/error-report', {
+      method: 'POST',
+      body: JSON.stringify({
+        message: error.message,
+        stack: error.stack,
+        componentStack: errorInfo.componentStack
+      })
+    });
+  };
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <div className="error-fallback">
+          <h2>Something went wrong.</h2>
+          <p>We're sorry for the inconvenience.</p>
+          <button onClick={() => window.location.reload()}>
+            Refresh Page
+          </button>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
+
+// 使用错误边界
+function App() {
+  return (
+    <ErrorBoundary>
+      <MyPluginComponent />
+    </ErrorBoundary>
+  );
+}
+```
+
+### 异步操作错误处理
+
+```typescript
+function SafeComponent() {
+  const [data, setData] = useState(null);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  const fetchData = async () => {
+    setLoading(true);
+    setError(null);
+
+    try {
+      const response = await fetch('/api/data');
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+
+      const result = await response.json();
+      setData(result);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Unknown error');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchData();
+  }, []);
+
+  if (loading) {
+    return <div>Loading...</div>;
+  }
+
+  if (error) {
+    return (
+      <div className="error-message">
+        <h3>Error loading data</h3>
+        <p>{error}</p>
+        <button onClick={fetchData}>Retry</button>
+      </div>
+    );
+  }
+
+  return <div>{/* 正常显示数据 */}</div>;
+}
+```
+
+### 自定义 Hook 错误处理
+
+```typescript
+import { useState, useCallback } from 'react';
+
+interface FetchState<T> {
+  data: T | null;
+  error: string | null;
+  loading: boolean;
+}
+
+function useSafeFetch<T>() {
+  const [state, setState] = useState<FetchState<T>>({
+    data: null,
+    error: null,
+    loading: false
+  });
+
+  const fetchData = useCallback(async (url: string, options?: RequestInit) => {
+    setState({ data: null, error: null, loading: true });
+
+    try {
+      const response = await fetch(url, options);
+
+      if (!response.ok) {
+        throw new Error(`Request failed: ${response.statusText}`);
+      }
+
+      const data = await response.json();
+      setState({ data, error: null, loading: false });
+      return data;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      setState({ data: null, error: message, loading: false });
+      throw error;
+    }
+  }, []);
+
+  return {
+    ...state,
+    fetchData
+  };
+}
+
+// 使用自定义 Hook
+function DataComponent() {
+  const { data, error, loading, fetchData } = useSafeFetch<any>();
+
+  useEffect(() => {
+    fetchData('/api/users');
+  }, [fetchData]);
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error}</div>;
+
+  return <div>{JSON.stringify(data)}</div>;
+}
+```
+
+### 全局错误处理
+
+```typescript
+// 设置全局错误处理器
+window.addEventListener('error', (event) => {
+  console.error('Global error:', event.error);
+
+  // 发送错误报告
+  fetch('/api/error-report', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      message: event.error?.message,
+      filename: event.filename,
+      lineno: event.lineno,
+      colno: event.colno,
+      stack: event.error?.stack
+    })
+  });
+});
+
+// 处理未处理的 Promise 拒绝
+window.addEventListener('unhandledrejection', (event) => {
+  console.error('Unhandled promise rejection:', event.reason);
+
+  // 发送错误报告
+  fetch('/api/error-report', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      type: 'unhandledrejection',
+      reason: event.reason?.toString(),
+      stack: event.reason?.stack
+    })
+  });
+
+  event.preventDefault();
+});
+```
+
+## 错误处理最佳实践
+
+### 1. 错误分类
+
+```typescript
+// 定义错误类型
+enum ErrorType {
+  VALIDATION = 'VALIDATION',
+  NOT_FOUND = 'NOT_FOUND',
+  UNAUTHORIZED = 'UNAUTHORIZED',
+  FORBIDDEN = 'FORBIDDEN',
+  INTERNAL = 'INTERNAL',
+  NETWORK = 'NETWORK',
+  TIMEOUT = 'TIMEOUT'
+}
+
+interface AppError {
+  type: ErrorType;
+  message: string;
+  code?: string;
+  details?: any;
+}
+```
+
+### 2. 错误日志记录
+
+```typescript
+// 服务端日志记录
+class LoggingService {
+  constructor(private logger: ILogger) {}
+
+  logError(error: Error, context?: any) {
+    this.logger.error('Application error', {
+      message: error.message,
+      stack: error.stack,
+      name: error.name,
+      context,
+      timestamp: new Date().toISOString()
+    });
+  }
+
+  logApiError(error: Error, request: any) {
+    this.logger.error('API error', {
+      message: error.message,
+      method: request.method,
+      url: request.url,
+      userAgent: request.headers['user-agent'],
+      ip: request.ip
+    });
+  }
+}
+```
+
+### 3. 用户友好的错误消息
+
+```typescript
+// 错误消息映射
+const ERROR_MESSAGES = {
+  'User not found': 'The requested user could not be found',
+  'Invalid email format': 'Please provide a valid email address',
+  'Insufficient permissions': 'You do not have permission to perform this action',
+  'Internal server error': 'Something went wrong. Please try again later'
+};
+
+function getUserFriendlyError(error: string): string {
+  return ERROR_MESSAGES[error as keyof typeof ERROR_MESSAGES] || error;
+}
+```
+
+## 完整示例
+
+查看错误处理实践:
+
+- 📁 [Blog Plugin 示例](../../examples/blog-plugin/) - 完整的错误处理实现
+- 📁 [Hello World 示例](../../examples/hello-world/) - 基础错误处理
+
+## 相关文档
+
+- 📝 [命名规范](./naming-conventions.md)
+- ⚡ [性能优化](./performance.md)
+- 🔒 [安全性](./security.md)
+
+---
+
+**上一篇**: [ServiceDef 代码风格规范](./service-definition.md) | **下一篇**: [性能优化](./performance.md)