docs: 添加工具函数组织规则
- CLAUDE.md: 新增第 15 条规则,禁止在业务包中二次导出通用函数 - CODING_RULES.md: 添加详细的错误/正确示例和 @aitu/utils 函数列表
This commit is contained in:
1 parent
9edca2414e
commit
6abdcad300
2 files changed
+45
No files matched your search
@@ -143,6 +143,7 @@ Service Worker (后台执行)
|
||||
12. **共享模块设计**:相似功能提取到 `*-core.ts` 核心模块,通过配置类型区分行为
|
||||
13. **同名模块隔离**:多个同名模块有独立全局状态,确保从正确的模块路径导入
|
||||
14. **工作区初始化**:`getCurrentBoard()` 返回 `null` 但 `hasBoards()` 为 `true` 时,必须自动选择第一个画板,不能只在 "无画板" 时创建新画板
|
||||
15. **工具函数组织**:通用工具函数放 `@aitu/utils`,使用时直接导入,禁止在业务包中二次导出
|
||||
|
||||
### Service Worker 规则
|
||||
|
||||
|
||||
@@ -313,6 +313,50 @@ if (params) {
|
||||
**相关文件**:
|
||||
- `packages/drawnix/src/utils/image-split-core.ts` - 图片拆分核心模块
|
||||
|
||||
#### 工具函数组织与导入
|
||||
|
||||
**场景**: 项目中有通用工具函数需要在多个包之间共享
|
||||
|
||||
❌ **错误示例**:
|
||||
```typescript
|
||||
// packages/drawnix/src/utils/common.ts
|
||||
// 错误:在业务包中二次导出通用函数
|
||||
import { generateId, sanitizeObject } from '@aitu/utils';
|
||||
export { generateId, sanitizeObject }; // ❌ 二次导出
|
||||
|
||||
// packages/drawnix/src/services/some-service.ts
|
||||
// 错误:从业务包导入通用函数
|
||||
import { generateId } from '../utils/common'; // ❌ 间接导入
|
||||
```
|
||||
|
||||
✅ **正确示例**:
|
||||
```typescript
|
||||
// packages/drawnix/src/services/some-service.ts
|
||||
// 正确:直接从 @aitu/utils 导入
|
||||
import { generateId, sanitizeObject } from '@aitu/utils'; // ✅ 直接导入
|
||||
|
||||
// packages/drawnix/src/utils/common.ts
|
||||
// 正确:只保留业务特有的函数
|
||||
import { IS_APPLE, PlaitBoard, toImage } from '@plait/core';
|
||||
|
||||
export const boardToImage = (board: PlaitBoard) => { // ✅ Plait 特有
|
||||
return toImage(board, { fillStyle: 'transparent' });
|
||||
};
|
||||
```
|
||||
|
||||
**原因**:
|
||||
- 二次导出会造成依赖链混乱,增加包体积
|
||||
- 修改工具函数时难以追踪所有使用位置
|
||||
- 直接导入语义更清晰,IDE 跳转更准确
|
||||
|
||||
**`@aitu/utils` 包含的通用函数**:
|
||||
- ID 生成:`generateId()`, `generateUUID()`
|
||||
- 日期格式化:`formatDate()`, `formatDuration()`, `formatFileSize()`
|
||||
- DOM 操作:`download()`, `copyToClipboard()`
|
||||
- 安全工具:`sanitizeObject()`, `sanitizeUrl()`, `getSafeErrorMessage()`
|
||||
- 字符串处理:`truncate()`, `capitalize()`, `toKebabCase()`
|
||||
- 异步工具:`debounce()`, `throttle()`
|
||||
|
||||
### React 组件规范
|
||||
- 使用函数组件和 Hooks
|
||||
- 使用 `React.memo` 优化重渲染
|
||||
|
||||
Reference in new issue
Block a user