@doubao-apps/ai 0.0.33 → 0.0.34

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

@@ -1,571 +0,0 @@
-# 最佳实践
-
-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)