Ubuntu
263 lines
7.4 KiB
Markdown
263 lines
7.4 KiB
Markdown
# wanandroid Uniapp 项目 - 模块化重构说明
|
||
|
||
## 项目概述
|
||
|
||
本项目是基于Uniapp框架开发的wanandroid客户端应用，已按照软件工程原则进行了模块化重构，提高了代码的可维护性、可复用性和可扩展性。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
uniapp/
|
||
├── common/ # 公共资源
|
||
│ ├── api/ # API接口管理
|
||
│ │ ├── home.api.js # 首页模块API
|
||
│ │ └── project.api.js # 项目模块API
|
||
│ ├── utils/ # 工具函数
|
||
│ │ ├── request.js # 统一请求工具
|
||
│ │ └── common.js # 通用工具函数
|
||
│ ├── constants/ # 常量定义
|
||
│ │ └── app.constants.js # 应用常量
|
||
│ └── config/ # 配置文件
|
||
│ └── api.config.js # API配置
|
||
├── components/ # 公共组件
|
||
│ ├── common/ # 通用组件
|
||
│ │ ├── loading.vue # 加载组件
|
||
│ │ └── empty-state.vue # 空状态组件
|
||
│ ├── home/ # 首页专用组件
|
||
│ │ └── banner.vue # Banner轮播组件
|
||
│ └── project/ # 项目模块专用组件
|
||
│ └── category-tabs.vue # 分类标签组件
|
||
├── pages/ # 页面
|
||
│ ├── home/ # 首页模块
|
||
│ │ └── index.vue # 首页页面（已重构）
|
||
│ ├── project/ # 项目模块
|
||
│ │ ├── project.vue # 项目列表页面（已重构）
|
||
│ │ └── project-detail/ # 项目详情
|
||
│ ├── wxarticle/ # 公众号模块
|
||
│ ├── tree/ # 体系模块
|
||
│ └── mine/ # 我的模块
|
||
├── static/ # 静态资源
|
||
│ ├── images/
|
||
│ ├── icons/
|
||
│ └── fonts/
|
||
└── store/ # 状态管理（待实现）
|
||
```
|
||
|
||
## 模块化设计原则
|
||
|
||
### 1. 单一职责原则
|
||
- 每个模块/组件只负责一个特定的功能
|
||
- API管理、UI组件、业务逻辑分离
|
||
|
||
### 2. 高内聚低耦合
|
||
- 相关功能集中管理（如首页所有API在`home.api.js`中）
|
||
- 模块间通过清晰的接口通信
|
||
|
||
### 3. 可复用性
|
||
- 提取公共组件（Loading、EmptyState等）
|
||
- 工具函数统一管理
|
||
- 配置集中管理
|
||
|
||
### 4. 可维护性
|
||
- 清晰的目录结构
|
||
- 统一的代码规范
|
||
- 完善的错误处理
|
||
|
||
## 已完成的模块
|
||
|
||
### 1. 首页模块 (`/pages/index/index.vue`)
|
||
- **功能**：Banner轮播、文章列表、搜索热词
|
||
- **组件**：HomeBanner、CommonLoading、EmptyState
|
||
- **API**：`home.api.js`（统一管理首页所有API）
|
||
- **特性**：
|
||
- 下拉刷新、上拉加载
|
||
- 图片懒加载
|
||
- 回到顶部功能
|
||
- 完善的错误处理
|
||
|
||
### 2. 项目模块 (`/pages/project/project.vue`)
|
||
- **功能**：项目分类、项目列表、项目搜索
|
||
- **组件**：ProjectCategoryTabs、CommonLoading、EmptyState
|
||
- **API**：`project.api.js`（统一管理项目所有API）
|
||
- **特性**：
|
||
- 分类标签切换
|
||
- 项目网格布局
|
||
- 点赞、收藏、查看源码
|
||
- 项目状态标识（NEW、HOT）
|
||
|
||
## 公共组件
|
||
|
||
### 1. CommonLoading (`components/common/loading.vue`)
|
||
- 统一的加载动画组件
|
||
- 支持自定义文本和样式
|
||
- 支持全屏和局部加载
|
||
|
||
### 2. EmptyState (`components/common/empty-state.vue`)
|
||
- 空状态提示组件
|
||
- 支持自定义图标、标题、描述
|
||
- 支持操作按钮
|
||
|
||
### 3. HomeBanner (`components/home/banner.vue`)
|
||
- Banner轮播组件
|
||
- 支持自动播放、循环播放
|
||
- 支持点击事件和跳转
|
||
|
||
### 4. ProjectCategoryTabs (`components/project/category-tabs.vue`)
|
||
- 项目分类标签组件
|
||
- 支持水平滚动
|
||
- 选中状态指示器
|
||
|
||
## API管理
|
||
|
||
### 统一请求工具 (`common/utils/request.js`)
|
||
- 封装`uni.request`，提供统一的错误处理
|
||
- 支持请求拦截器和响应拦截器
|
||
- 支持GET、POST、PUT、DELETE方法
|
||
- 自动处理加载状态
|
||
|
||
### API配置 (`common/config/api.config.js`)
|
||
- 统一管理所有API接口地址
|
||
- 按模块分组管理
|
||
- 支持环境配置
|
||
|
||
### 模块化API (`common/api/`)
|
||
- 每个模块有独立的API管理文件
|
||
- 提供完整的业务方法
|
||
- 统一的数据处理逻辑
|
||
|
||
## 工具函数 (`common/utils/common.js`)
|
||
- 时间格式化（相对时间、绝对时间）
|
||
- 防抖和节流函数
|
||
- 深度克隆
|
||
- 安全属性访问
|
||
- 文件大小格式化
|
||
- 剪贴板操作
|
||
|
||
## 常量定义 (`common/constants/app.constants.js`)
|
||
- 应用信息
|
||
- 存储键名
|
||
- 页面路由
|
||
- 事件名称
|
||
- 错误码和错误消息
|
||
- 颜色配置
|
||
- 字体配置
|
||
- 动画配置
|
||
|
||
## 使用示例
|
||
|
||
### 在页面中使用API
|
||
```javascript
|
||
// 导入API
|
||
import { getHomeData } from '@/common/api/home.api.js'
|
||
|
||
// 使用API
|
||
async loadData() {
|
||
try {
|
||
const homeData = await getHomeData(this.currentPage)
|
||
this.bannerList = homeData.bannerList
|
||
this.articleList = homeData.articleList
|
||
} catch (error) {
|
||
console.error('加载数据失败:', error)
|
||
}
|
||
}
|
||
```
|
||
|
||
### 在页面中使用组件
|
||
```vue
|
||
<template>
|
||
<!-- 使用公共组件 -->
|
||
<common-loading :visible="loading" />
|
||
<empty-state v-if="isEmpty" @action="refreshData" />
|
||
|
||
<!-- 使用模块组件 -->
|
||
<home-banner :banner-list="bannerList" @click="handleBannerClick" />
|
||
</template>
|
||
|
||
<script>
|
||
import CommonLoading from '@/components/common/loading.vue'
|
||
import EmptyState from '@/components/common/empty-state.vue'
|
||
import HomeBanner from '@/components/home/banner.vue'
|
||
|
||
export default {
|
||
components: {
|
||
CommonLoading,
|
||
EmptyState,
|
||
HomeBanner
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
### 使用工具函数
|
||
```javascript
|
||
import { formatRelativeTime, debounce } from '@/common/utils/common.js'
|
||
|
||
// 格式化时间
|
||
const relativeTime = formatRelativeTime(timestamp)
|
||
|
||
// 防抖处理
|
||
const debouncedSearch = debounce(this.handleSearch, 500)
|
||
```
|
||
|
||
## 后续开发建议
|
||
|
||
### 1. 状态管理
|
||
- 实现Vuex或Pinia进行全局状态管理
|
||
- 管理用户信息、主题设置等全局状态
|
||
|
||
### 2. 更多模块开发
|
||
- 公众号模块 (`wxarticle`)
|
||
- 体系模块 (`tree`)
|
||
- 我的模块 (`mine`)
|
||
|
||
### 3. 性能优化
|
||
- 图片懒加载优化
|
||
- 列表虚拟滚动
|
||
- 数据缓存策略
|
||
|
||
### 4. 功能扩展
|
||
- 搜索功能
|
||
- 用户登录/注册
|
||
- 文章收藏
|
||
- 夜间模式
|
||
|
||
### 5. 测试
|
||
- 单元测试
|
||
- 集成测试
|
||
- E2E测试
|
||
|
||
## 开发规范
|
||
|
||
### 1. 命名规范
|
||
- 组件：大驼峰命名，如`HomeBanner`
|
||
- 文件：小写字母+连字符，如`home-banner.vue`
|
||
- 变量：小驼峰命名，如`articleList`
|
||
- 常量：大写字母+下划线，如`API_CONFIG`
|
||
|
||
### 2. 代码组织
|
||
- 每个文件不超过500行
|
||
- 每个函数不超过50行
|
||
- 使用ES6+语法
|
||
- 添加必要的注释
|
||
|
||
### 3. 错误处理
|
||
- 所有异步操作都要有错误处理
|
||
- 用户友好的错误提示
|
||
- 错误日志记录
|
||
|
||
### 4. 性能考虑
|
||
- 避免不必要的重渲染
|
||
- 合理使用计算属性和侦听器
|
||
- 图片优化和懒加载
|
||
|
||
## 总结
|
||
|
||
本次重构按照软件工程原则，将项目从简单的页面堆砌重构为模块化、组件化的架构。新的架构具有以下优势：
|
||
|
||
1. **可维护性**：清晰的目录结构和模块划分
|
||
2. **可复用性**：公共组件和工具函数
|
||
3. **可扩展性**：易于添加新功能和模块
|
||
4. **可靠性**：统一的错误处理和API管理
|
||
5. **一致性**：统一的代码规范和设计模式
|
||
|
||
这种架构为后续的功能扩展和维护提供了良好的基础。 |