@doubao-apps/ai 0.0.26 → 0.0.27

package/dist/contexts/doubao-apps-dev/.ai/guides/best-practices.md

@@ -0,0 +1,571 @@
+# 最佳实践
+
+Doubao Apps SDK 框架的最佳开发实践和代码规范。
+
+---
+
+## 🎯 核心原则
+
+### SOLID 原则
+
+1. **单一职责原则**（Single Responsibility）
+   - 每个组件只负责一个功能
+   - 函数保持简洁，只做一件事
+
+2. **开闭原则**（Open/Closed）
+   - 对扩展开放，对修改关闭
+   - 使用组合而非修改现有代码
+
+3. **依赖倒置原则**（Dependency Inversion）
+   - 依赖抽象而非具体实现
+   - 通过 props 传递依赖
+
+### DRY 原则
+
+**Don't Repeat Yourself** - 避免重复代码
+
+```tsx
+// ✅ 好的做法 - 抽取公共逻辑
+const useUserData = () => {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(false);
+
+  const fetchUser = async () => {
+    setLoading(true);
+    try {
+      const data = await api.getUser();
+      setUser(data);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return { user, loading, fetchUser };
+};
+
+// 在多个组件中复用
+function ProfilePage() {
+  const { user, loading } = useUserData();
+  // ...
+}
+```
+
+```tsx
+// ❌ 不好的做法 - 重复代码
+function ProfilePage() {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(false);
+
+  const fetchUser = async () => {
+    setLoading(true);
+    try {
+      const data = await api.getUser();
+      setUser(data);
+    } finally {
+      setLoading(false);
+    }
+  };
+  // ...
+}
+
+function SettingsPage() {
+  // 完全相同的代码又写一遍
+  const [user, setUser] = useState(null);
+  // ...
+}
+```
+
+---
+
+## 📂 项目组织
+
+### 目录结构
+
+```
+src/
+├── pages/           # 页面组件
+│   └── home/
+│       ├── index.tsx
+│       ├── index.scss
+│       └── components/  # 页面私有组件
+│           └── Header.tsx
+├── widgets/         # Widget 组件
+│   └── weather-card/
+│       ├── index.tsx
+│       └── index.scss
+├── components/      # 公共组件
+│   ├── Button/
+│   │   ├── index.tsx
+│   │   └── index.scss
+│   └── Loading/
+│       ├── index.tsx
+│       └── index.scss
+├── hooks/           # 自定义 Hooks
+│   ├── useAuth.ts
+│   └── useData.ts
+├── utils/           # 工具函数
+│   ├── format.ts
+│   └── validate.ts
+├── constants/       # 常量定义
+│   └── index.ts
+├── types/           # 类型定义
+│   └── index.ts
+└── app.ts          # 应用入口
+```
+
+### 文件命名规范
+
+```
+✅ 好的命名：
+- UserProfile.tsx        (组件：PascalCase)
+- useAuth.ts            (Hook：camelCase with use prefix)
+- formatDate.ts         (工具函数：camelCase)
+- API_BASE_URL.ts       (常量：UPPER_SNAKE_CASE)
+
+❌ 不好的命名：
+- userprofile.tsx
+- UseAuth.ts
+- Format-Date.ts
+- apibaseurl.ts
+```
+
+---
+
+##  最佳实践
+
+### 组件设计
+
+#### 保持组件简洁
+
+```tsx
+// ✅ 好的做法 - 单一职责
+function UserAvatar({ url, size = 'medium' }: Props) {
+  return (
+    <image
+      className={`user-avatar user-avatar--${size}`}
+      src={url}
+    />
+  );
+}
+
+function UserCard({ user }: Props) {
+  return (
+    <view className="user-card">
+      <UserAvatar url={user.avatar} size="large" />
+      <text>{user.name}</text>
+    </view>
+  );
+}
+```
+
+```tsx
+// ❌ 不好的做法 - 组件过于复杂
+function UserCard({ user }: Props) {
+  return (
+    <view className="user-card">
+      {/* 太多内联逻辑 */}
+      <image
+        src={user.avatar}
+        style={{
+          width: user.isVip ? '120rpx' : '80rpx',
+          height: user.isVip ? '120rpx' : '80rpx',
+          borderRadius: user.isVip ? '60rpx' : '40rpx',
+          border: user.isVip ? '2px solid gold' : 'none'
+        }}
+      />
+      <text>{user.name}</text>
+      {user.isVip && <text>VIP</text>}
+      {/* 更多复杂逻辑... */}
+    </view>
+  );
+}
+```
+
+#### 使用 TypeScript 类型
+
+```tsx
+// ✅ 好的做法 - 完整的类型定义
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  avatar?: string;
+}
+
+interface UserCardProps {
+  user: User;
+  onPress?: (userId: string) => void;
+}
+
+function UserCard({ user, onPress }: UserCardProps) {
+  return (
+    <view onClick={() => onPress?.(user.id)}>
+      <text>{user.name}</text>
+    </view>
+  );
+}
+```
+
+### Hooks 使用
+
+#### 自定义 Hooks
+
+```tsx
+// ✅ 好的做法 - 封装复杂逻辑
+function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => clearTimeout(handler);
+  }, [value, delay]);
+
+  return debouncedValue;
+}
+
+// 使用
+function SearchPage() {
+  const [query, setQuery] = useState('');
+  const debouncedQuery = useDebounce(query, 500);
+
+  useEffect(() => {
+    if (debouncedQuery) {
+      performSearch(debouncedQuery);
+    }
+  }, [debouncedQuery]);
+
+  return <input value={query} onInput={e => setQuery(e.detail.value)} />;
+}
+```
+
+#### useMemo 和 useCallback
+
+```tsx
+// ✅ 好的做法 - 优化性能
+function DataList({ items, filter }: Props) {
+  // 缓存计算结果
+  const filteredItems = useMemo(() => {
+    return items.filter(item => item.type === filter);
+  }, [items, filter]);
+
+  // 稳定函数引用
+  const handleItemClick = useCallback((id: string) => {
+    console.log('Clicked:', id);
+  }, []);
+
+  return (
+    <view>
+      {filteredItems.map(item => (
+        <ItemCard key={item.id} item={item} onClick={handleItemClick} />
+      ))}
+    </view>
+  );
+}
+```
+
+---
+
+## 🎨 样式最佳实践
+
+### SCSS 组织
+
+```scss
+// ✅ 好的做法 - 使用变量和嵌套
+$primary-color: #1890ff;
+$spacing-unit: 8rpx;
+$border-radius: 8rpx;
+
+.user-card {
+  padding: $spacing-unit * 2;
+  border-radius: $border-radius;
+  background: #ffffff;
+
+  &__header {
+    display: flex;
+    align-items: center;
+    margin-bottom: $spacing-unit * 3;
+  }
+
+  &__title {
+    font-size: 32rpx;
+    color: $primary-color;
+    font-weight: bold;
+  }
+
+  &--highlighted {
+    border: 2rpx solid $primary-color;
+  }
+}
+```
+
+### BEM 命名规范
+
+```scss
+// Block__Element--Modifier
+
+.card { }                    // Block
+.card__header { }            // Element
+.card__body { }              // Element
+.card--featured { }          // Modifier
+.card__header--large { }     // Element Modifier
+```
+
+### 响应式设计
+
+```scss
+// ✅ 使用 rpx 单位
+.container {
+  padding: 32rpx;           // 响应式单位
+  font-size: 28rpx;
+}
+
+// ❌ 避免使用固定 px
+.container {
+  padding: 16px;            // 不会响应屏幕尺寸
+  font-size: 14px;
+}
+```
+
+---
+
+## 🚀 性能优化
+
+### 避免不必要的渲染
+
+```tsx
+// ✅ 好的做法 - 使用 useMemo
+function ParentComponent({ items }: Props) {
+  const processedData = useMemo(() => {
+    return items.map(item => ({
+      ...item,
+      computed: expensiveCalculation(item)
+    }));
+  }, [items]);
+
+  return <ExpensiveComponent data={processedData} />;
+}
+```
+
+### 列表渲染优化
+
+```tsx
+// ✅ 好的做法 - 使用唯一稳定的 key
+function ItemList({ items }: Props) {
+  return (
+    <list>
+      {items.map(item => (
+        <list-item key={item.id}>  {/* 使用唯一 ID */}
+          <ItemCard item={item} />
+        </list-item>
+      ))}
+    </list>
+  );
+}
+
+// ❌ 不好的做法 - 使用 index 作为 key
+function ItemList({ items }: Props) {
+  return (
+    <list>
+      {items.map((item, index) => (
+        <list-item key={index}>  {/* 列表顺序改变会有问题 */}
+          <ItemCard item={item} />
+        </list-item>
+      ))}
+    </list>
+  );
+}
+```
+
+---
+
+## 🔒 错误处理
+
+### Try-Catch 使用
+
+```tsx
+// ✅ 好的做法 - 完整的错误处理
+async function fetchData() {
+  try {
+    setLoading(true);
+    setError(null);
+
+    const response = await api.getData();
+    setData(response);
+  } catch (error) {
+    // 记录错误
+    console.error('Failed to fetch data:', error);
+
+    // 设置用户友好的错误信息
+    if (error.code === 'NETWORK_ERROR') {
+      setError('网络连接失败，请检查您的网络');
+    } else if (error.code === 'AUTH_ERROR') {
+      setError('您的登录已过期，请重新登录');
+    } else {
+      setError('数据加载失败，请稍后重试');
+    }
+
+    // 可选：上报错误到监控系统
+    reportError(error);
+  } finally {
+    setLoading(false);
+  }
+}
+```
+
+### 边界情况处理
+
+```tsx
+// ✅ 好的做法 - 处理各种边界情况
+function DataDisplay({ data }: { data?: Data[] }) {
+  // 处理 undefined
+  if (!data) {
+    return <LoadingView />;
+  }
+
+  // 处理空数组
+  if (data.length === 0) {
+    return <EmptyView message="暂无数据" />;
+  }
+
+  // 正常展示
+  return (
+    <view>
+      {data.map(item => (
+        <ItemCard key={item.id} item={item} />
+      ))}
+    </view>
+  );
+}
+```
+
+---
+
+## 📱 用户体验
+
+### 加载状态
+
+```tsx
+// ✅ 好的做法 - 提供清晰的加载反馈
+function DataPage() {
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(true);
+
+  if (loading) {
+    return (
+      <view className="loading-container">
+        <loading-spinner />
+        <text>加载中...</text>
+      </view>
+    );
+  }
+
+  return <DataView data={data} />;
+}
+```
+
+### 错误反馈
+
+```tsx
+// ✅ 好的做法 - 提供可操作的错误提示
+function ErrorView({ error, onRetry }: Props) {
+  return (
+    <view className="error-container">
+      <image src="/assets/error-icon.png" className="error-icon" />
+      <text className="error-message">{error}</text>
+      <button className="retry-button" onClick={onRetry}>
+        重试
+      </button>
+    </view>
+  );
+}
+```
+
+### 交互反馈
+
+```tsx
+// ✅ 好的做法 - 提供即时反馈
+function SubmitButton({ onSubmit }: Props) {
+  const [submitting, setSubmitting] = useState(false);
+
+  const handleSubmit = async () => {
+    setSubmitting(true);
+    try {
+      await onSubmit();
+      showToast({ message: '提交成功' });
+    } catch (error) {
+      showToast({ message: '提交失败，请重试' });
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <button
+      className="submit-button"
+      onClick={handleSubmit}
+      disabled={submitting}
+    >
+      {submitting ? '提交中...' : '提交'}
+    </button>
+  );
+}
+```
+
+---
+
+## 📝 代码注释
+
+### 何时添加注释
+
+```tsx
+// ✅ 好的做法 - 解释"为什么"，而不是"是什么"
+function calculateDiscount(price: number, userLevel: string): number {
+  // VIP 用户享受额外 10% 折扣（业务需求）
+  if (userLevel === 'VIP') {
+    return price * 0.9;
+  }
+
+  return price;
+}
+
+// ❌ 不好的做法 - 注释重复代码
+function calculateDiscount(price: number, userLevel: string): number {
+  // 如果用户等级是 VIP
+  if (userLevel === 'VIP') {
+    // 返回价格乘以 0.9
+    return price * 0.9;
+  }
+
+  // 返回原价
+  return price;
+}
+```
+
+### JSDoc 注释
+
+```tsx
+/**
+ * 格式化日期为 YYYY-MM-DD 格式
+ * @param date - 要格式化的日期对象
+ * @param separator - 分隔符，默认为 '-'
+ * @returns 格式化后的日期字符串
+ * @example
+ * formatDate(new Date('2024-01-15')) // '2024-01-15'
+ * formatDate(new Date('2024-01-15'), '/') // '2024/01/15'
+ */
+function formatDate(date: Date, separator: string = '-'): string {
+  // 实现...
+}
+```
+
+---
+
+## 🔗 相关文档
+
+- [开发规则](../rules/dos-and-donts.md)
+- [组件开发完整指南](./component-development.md)
+- [性能优化](./performance-optimization.md)
+- [故障排查](./troubleshooting.md)