196 lines
4.9 KiB
Markdown
196 lines
4.9 KiB
Markdown
# Shared 模块导出规范
|
||
|
||
## 导出路径组织
|
||
|
||
为了保持代码的清晰性和可维护性，shared 包的模块导出已按照功能分类组织。
|
||
|
||
### 组件模块 (Components)
|
||
|
||
```typescript
|
||
// 整体导出
|
||
import { FileUpload, DynamicFormItem } from 'shared/components'
|
||
|
||
// 单独导入（推荐）
|
||
import FileUpload from 'shared/components/FileUpload'
|
||
import DynamicFormItem from 'shared/components/DynamicFormItem'
|
||
```
|
||
|
||
**可用组件：**
|
||
- `shared/components/FileUpload` - 文件上传组件（支持 cover/dialog/content 三种模式）
|
||
- `shared/components/DynamicFormItem` - 动态表单项组件
|
||
|
||
---
|
||
|
||
### API 模块
|
||
|
||
```typescript
|
||
// 整体导出
|
||
import { api, TokenManager } from 'shared/api'
|
||
|
||
// 单独导入（推荐）
|
||
import { authAPI } from 'shared/api/auth'
|
||
import { fileAPI } from 'shared/api/file'
|
||
```
|
||
|
||
**可用 API：**
|
||
- `shared/api` - API 基础模块和 TokenManager
|
||
- `shared/api/auth` - 认证相关 API
|
||
- `shared/api/file` - 文件管理 API
|
||
|
||
---
|
||
|
||
### Utils 工具模块
|
||
|
||
```typescript
|
||
// 整体导出
|
||
import { formatFileSize, isImageFile } from 'shared/utils'
|
||
|
||
// 单独导入
|
||
import { getDeviceType, isMobile } from 'shared/utils/device'
|
||
import {
|
||
generateSimpleRoutes,
|
||
loadViewsFromStorage,
|
||
buildMenuTree
|
||
} from 'shared/utils/route'
|
||
import { formatFileSize, isImageFile } from 'shared/utils/file'
|
||
```
|
||
|
||
**可用工具：**
|
||
- `shared/utils` - 通用工具函数集合
|
||
- `shared/utils/device` - 设备检测工具
|
||
- `shared/utils/route` - 路由生成和菜单构建工具
|
||
- `generateSimpleRoutes()` - 生成简化路由（适合直接添加到 router）
|
||
- `loadViewsFromStorage()` - 从 localStorage 加载视图数据
|
||
- `buildMenuTree()` - 构建菜单树结构
|
||
- `generateRoutes()` - 生成完整路由配置
|
||
- 更多工具函数...
|
||
- `shared/utils/file` - 文件处理工具
|
||
|
||
---
|
||
|
||
### Types 类型模块
|
||
|
||
```typescript
|
||
// 整体导出
|
||
import type { LoginParam, TbSysViewDTO } from 'shared/types'
|
||
|
||
// 单独导入
|
||
import type { LoginParam, LoginDomain } from 'shared/types/auth'
|
||
import type { TbSysFileDTO } from 'shared/types/file'
|
||
import type { SysUserVO, SysConfigVO } from 'shared/types/sys'
|
||
```
|
||
|
||
**可用类型：**
|
||
- `shared/types` - 所有类型的统一导出
|
||
- `shared/types/base` - 基础类型（BaseVO, BaseDTO 等）
|
||
- `shared/types/auth` - 认证相关类型
|
||
- `shared/types/file` - 文件相关类型
|
||
- `shared/types/sys` - 系统相关类型
|
||
|
||
---
|
||
|
||
## 向后兼容性
|
||
|
||
为了保持向后兼容，旧的导入路径仍然可用（但不推荐）：
|
||
|
||
```typescript
|
||
// ❌ 旧路径（不推荐，但仍可用）
|
||
import FileUpload from 'shared/FileUpload'
|
||
import { authAPI } from 'shared/authAPI'
|
||
import { fileAPI } from 'shared/fileAPI'
|
||
|
||
// ✅ 新路径（推荐）
|
||
import FileUpload from 'shared/components/FileUpload'
|
||
import { authAPI } from 'shared/api/auth'
|
||
import { fileAPI } from 'shared/api/file'
|
||
```
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 使用明确的路径
|
||
|
||
```typescript
|
||
// ✅ 推荐：路径清晰，便于理解
|
||
import FileUpload from 'shared/components/FileUpload'
|
||
import { authAPI } from 'shared/api/auth'
|
||
|
||
// ❌ 不推荐：路径模糊
|
||
import FileUpload from 'shared/FileUpload'
|
||
```
|
||
|
||
### 2. 按需导入
|
||
|
||
```typescript
|
||
// ✅ 推荐：只导入需要的模块
|
||
import { formatFileSize } from 'shared/utils/file'
|
||
|
||
// ❌ 不推荐：导入整个模块
|
||
import * as utils from 'shared/utils'
|
||
```
|
||
|
||
### 3. 使用类型导入
|
||
|
||
```typescript
|
||
// ✅ 推荐：明确标识类型导入
|
||
import type { LoginParam } from 'shared/types/auth'
|
||
import { authAPI } from 'shared/api/auth'
|
||
|
||
// ❌ 不推荐：混合导入
|
||
import { LoginParam, authAPI } from 'shared/types'
|
||
```
|
||
|
||
---
|
||
|
||
## 添加新模块
|
||
|
||
如果需要添加新的导出模块，请按照以下步骤：
|
||
|
||
1. **在 vite.config.ts 中添加导出**
|
||
```typescript
|
||
exposes: {
|
||
'./components/YourComponent': './src/components/yourcomponent/YourComponent.vue'
|
||
}
|
||
```
|
||
|
||
2. **在 shared.d.ts 中添加类型声明**
|
||
```typescript
|
||
declare module 'shared/components/YourComponent' {
|
||
import { DefineComponent } from 'vue'
|
||
const YourComponent: DefineComponent<{}, {}, any>
|
||
export default YourComponent
|
||
}
|
||
```
|
||
|
||
3. **更新此文档**
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: TypeScript 报错找不到模块？
|
||
A: 尝试以下方法：
|
||
1. 重启 TypeScript 语言服务器（VS Code: `Ctrl+Shift+P` → Restart TS Server）
|
||
2. 确认 `shared.d.ts` 文件已正确更新
|
||
3. 检查 shared 包是否已正确构建
|
||
|
||
### Q: 运行时找不到模块？
|
||
A: 确保：
|
||
1. shared 包已启动（`npm run dev` 在 shared 目录）
|
||
2. `vite.config.ts` 中的 exposes 配置正确
|
||
3. Module Federation 配置正确加载
|
||
|
||
### Q: 如何查看所有可用模块？
|
||
A: 查看 `packages/shared/vite.config.ts` 的 `exposes` 配置
|
||
|
||
---
|
||
|
||
## 更新日志
|
||
|
||
### 2025-12-12
|
||
- ✅ 重新组织导出路径，使用清晰的分类前缀
|
||
- ✅ 添加向后兼容性支持
|
||
- ✅ 更新类型声明文件
|
||
- ✅ 添加更多常用模块导出
|