43 篇系统实战:uni-app 从入门到架构师成长之路
编者按 :本系列文章基于一个真实的企业级 uni-app
项目,从架构设计、组件封装、请求处理、多端适配到状态管理,全面分享了大前端开发的最佳实践。每篇文章都包含完整的代码实现和生产环境验证的经验总结。
关键词:uni-app;企业级架构;Vue3;TypeScript;最佳实践
📚 系列文章概览
本系列共包含 43 篇 精品文章,涵盖企业级 uni-app 应用的各个关键方面,从基础入门到架构师成长路径的完整体系:
📖 文章列表
基础入门篇(第 1-10 篇)
- 专栏导读与学习路线 - 系列介绍、技术栈概览、学习建议
- UniApp 项目创建完全指南 - HBuilderX、项目创建、环境配置
- Vue 3 + TypeScript 快速上手 - Composition API、TS 基础语法
- uView UI 集成完全指南 - uView 安装、组件使用、主题定制
- 基于 Vue3 + TypeScript + uni-app 的多端企业级应用架构设计与实践 - 整体架构设计、技术选型理由
- UniApp Vue3 TypeScript 实战项目结构 - 目录组织、命名规范、模块化设计
- uni-app 工程化配置实战 - ESLint、Prettier、Vite 构建优化
- 开发调试技巧 - HBuilderX 调试、浏览器 DevTools、真机调试
- Pinia 状态管理基础 - Pinia Store 定义、基本使用
- uni-app 路由系统与导航详解 - 路由基础、页面跳转、导航守卫
核心技能篇(第 11-25 篇)
- uni-app 请求封装最佳实践 - luch-request 封装、拦截器、错误处理
- uni-app API 接口加密实战 - AES+SM4 国密算法、签名验证、安全传输
- 文件上传下载专项 - 图片上传、文件下载、进度控制、断点续传
- uni-app 组件封装实战:图片上传组件 - 组件设计、预览、裁剪、压缩
- uni-app 复杂表单设计实战 - 动态表单、表单验证、数据提交
- uni-app 自定义 Hook 实战 - Composition API、逻辑复用
- uni-app 高级 Hook 实战 - 防抖节流、触摸手势、函数锁
- uni-app 工具函数封装实战 - 加密解密、数据处理、金额转换
- uni-app 枚举类型与常量管理实战 - TypeScript 枚举、字典映射、国际化
- uni-app 组件化开发实战 - 基础组件、业务组件、复杂选择器
- uni-app 审批流程组件封装 - 流程图绘制、节点配置、状态管理
- uni-app 审批流程组件实战 - 高级审批、会签、或签、可视化工作流
- uni-app 多端适配实战 - 样式适配、条件编译、平台差异处理
- uni-app 多端设备检测与适配实战 - 客户端识别、环境判断、兼容性处理
- WebSocket 实时通信完全指南 - 连接管理、消息收发、心跳机制、断线重连
进阶提升篇(第 26-35 篇)
- uni-app 状态管理实战:Pinia + 自定义 Cache - Pinia 模块化、持久化、Token 管理
- uni-app 权限管理系统实战:RBAC 模型设计 - RBAC 模型、按钮级权限、动态菜单
- uni-app 权限管理实战:RBAC 实现 - 权限数据结构、自定义指令、动态菜单控制
- uni-app 微信生态集成实战 - 公众号 OAuth2、微信支付、JS-SDK、社交分享
- uni-app 数据可视化实战:ECharts - ECharts 集成、差旅费用统计、数据卡片
- 小程序性能优化专项指南 - 页面渲染优化、数据包大小、网络优化、内存管理
- 长列表优化与虚拟滚动 - 虚拟列表原理、实现方案、性能对比
- 图片优化完全指南 - 懒加载、WebP 格式、CDN 加速、压缩策略
- uni.storage 封装与最佳实践 - 封装、数据持久化、缓存策略
- 单元测试与 E2E 测试完全指南 - Vitest 配置、组件测试、Cypress e2e 测试
实战案例篇(第 36-43 篇)
- 多端打包与发布流程完整指南 - 多端打包配置、证书签名、应用市场上架、CI/CD
- 电商小程序实战 - 商品模块完整实现 - 商品列表、详情页、SKU 选择器
- 电商小程序实战 - 购物车与订单完整实现 - 购物车管理、订单创建、支付集成
- OA 审批系统实战 - 完整工作流实现 - 多级审批、工作流引擎、表单设计
- uni-app 工作流引擎实战:BPMN 审批系统 - 流程设计器、节点配置、状态机
- UniApp + Pinia 完整状态管理解决方案 - Pinia 深入原理、插件生态、最佳实践
- 微前端架构实践 - qiankun 框架完整指南 - qiankun 框架、子应用拆分、状态共享
- 社交应用实战 - 即时聊天完整实现 - WebSocket、消息推送、会话管理
🎯 技术栈总览
json
{
"framework": {
"name": "Vue 3",
"version": "3.4.21",
"features": [
"Composition API",
"Reactivity System",
"Teleport"
]
},
"platform": {
"name": "uni-app",
"version": "3.0.0",
"targets": [
"H5",
"MP-WEIXIN",
"APP-PLUS",
"MP-ALIPAY"
]
},
"language": {
"name": "TypeScript",
"version": "4.7.4"
},
"buildTool": {
"name": "Vite",
"version": "5.2.8"
},
"stateManagement": {
"name": "Pinia",
"version": "2.0.36 + pinia-plugin-persistedstate"
},
"http": {
"library": "luch-request",
"version": "3.1.1"
},
"ui": {
"library": "uView UI 2.0.36 + ColorUI",
"customComponents": true
},
"css": {
"library": "TailwindCSS 3.1.8 + SCSS"
},
"testing": {
"unit": "Jest 29.7.0 + @vue/test-utils",
"e2e": "Cypress 13.6.0"
},
"quality": {
"eslint": "8.57.0",
"prettier": "3.2.0",
"typescript": "vue-tsc"
}
}
🔧 网络与通信
HTTP 请求:luch-request 3.1.1 + Axios
实时通信:WebSocket + uni.createWebSocket()
文件上传:uni.uploadFile + 分片上传
数据缓存:uni.storage + IndexedDB
📊 测试与质量
单元测试:Jest 29.7.0 + @vue/test-utils
E2E 测试:Cypress 13.6.0
代码质量:ESLint 8.57.0 + Prettier 3.2.0
类型检查:TypeScript 4.7.4 + vue-tsc
🚀 部署与运维
CI/CD:GitHub Actions + GitLab CI
容器化:Docker + docker-compose
监控:Sentry + 神策分析
性能:Lighthouse + Performance API
📱 多端平台
小程序:微信小程序 3.4.2 + 支付宝小程序
H5:响应式 Web + PWA
App:iOS + Android (原生渲染)
🏗️ 架构设计亮点
1. 分层架构设计
🛠️ 工具层 Helpers & Adapters
Helpers
辅助函数
Adapters
适配器
🔌 接口层 API Modules + Request Wrapper
API Modules
接口模块
Request Wrapper
请求封装
💾 状态层 Pinia Stores + Cache
Pinia Stores
状态管理
Cache
缓存机制
⚙️ 逻辑层 Composables & Custom Hooks
Composables
组合式函数
Custom Hooks
自定义 Hooks
🧩 组件层 Base & Business Components
Base Components
基础组件
Business Components
业务组件
📄 页面层 Pages & Layout
Pages
页面
Layout
布局
2. 模块化设计
src/
├── api/ # API 接口层(按业务模块划分)
│ ├── admin/ # 后台管理
│ ├── bpm/ # 流程管理
│ └── expense/ # 费用管理
├── components/ # 公共组件库
│ ├── image-upload/ # 图片上传
│ ├── approval-process/# 审批流程
│ └── person-selector/ # 人员选择器
├── stores/ # 状态管理
│ ├── user.ts # 用户状态
│ └── app.ts # 应用状态
├── hooks/ # 组合式函数
│ ├── useDict.ts # 字典管理
│ └── useCopy.ts # 复制功能
└── utils/ # 工具函数
├── request.ts # 请求封装
└── platform.ts # 平台适配
3. 核心特色与优势
🔐 安全体系
国密算法加密
- ✅ AES + SM4 双重加密保障
- ✅ 请求参数加密传输
- ✅ 响应数据解密处理
- ✅ 密钥安全管理
Token 管理机制
- ✅ 自动刷新 Token
- ✅ 过期自动处理
- ✅ 无感知续期
- ✅ 多端同步登录状态
权限控制体系
- ✅ 路由守卫拦截
- ✅ 按钮级权限控制
- ✅ 动态菜单生成
- ✅ RBAC 模型完整实现
数据安全防护
- ✅ uni.storage 加密存储
- ✅ 敏感数据脱敏
- ✅ XSS 防护
- ✅ CSRF 防护
⚡ 性能优化
分包加载策略
- ✅ 主包体积 < 2MB
- ✅ 按需加载子包
- ✅ 首屏速度提升 60%
请求优化方案
- ✅ 请求缓存机制
- ✅ 防抖节流控制
- ✅ 取消重复请求
- ✅ 预加载关键数据
渲染优化技术
- ✅ 虚拟列表长列表优化
- ✅ 图片懒加载
- ✅ WebP 格式转换
- ✅ CDN 加速分发
构建优化
- ✅ Tree Shaking 移除无用代码
- ✅ 按需导入组件
- ✅ 压缩优化
- ✅ 打包速度提升
📱 多端兼容
一套代码多端运行
- ✅ H5、小程序、APP 全面支持
- ✅ 条件编译精准控制
- ✅ 平台差异自动处理
样式自适应
- ✅ rpx 单位自动适配
- ✅ 安全区域适配
- ✅ 响应式布局
- ✅ 主题定制
API 适配层
- ✅ 统一 API 封装
- ✅ 平台特性检测
- ✅ 优雅降级方案
- ✅ 原生插件集成
🛠️ 工程化体系
代码规范
- ✅ ESLint 代码检查
- ✅ Prettier 代码格式化
- ✅ TypeScript 类型约束
- ✅ Git Hooks 提交检查
自动化流程
- ✅ Husky Git Hooks
- ✅ CI/CD 自动化部署
- ✅ 自动化测试
- ✅ 一键打包发布
开发体验
- ✅ Vite 快速热更新
- ✅ Devtools 调试工具
- ✅ vConsole 移动端调试
- ✅ 错误监控与上报
🧪 质量保障
单元测试
- ✅ Jest 测试框架
- ✅ Vue Test Utils 组件测试
- ✅ 测试覆盖率统计
- ✅ 核心逻辑全覆盖
E2E 测试
- ✅ Cypress 端到端测试
- ✅ 用户流程模拟
- ✅ 跨浏览器测试
- ✅ 自动化回归测试
代码质量
- ✅ 代码审查流程
- ✅ 静态代码分析
- ✅ 性能监控
- ✅ 错误追踪
4. 企业级实战项目
💼 电商小程序矩阵
商品模块
- ✅ 商品列表分页加载
- ✅ 商品详情展示
- ✅ SKU 选择器
- ✅ 规格参数对比
购物车系统
- ✅ 店铺分组管理
- ✅ 批量操作
- ✅ 价格实时计算
- ✅ 库存校验
订单流程
- ✅ 订单创建
- ✅ 微信支付集成
- ✅ 物流跟踪
- ✅ 订单状态管理
🏢 OA 审批系统
表单引擎
- ✅ 动态表单生成
- ✅ 表单验证规则
- ✅ 数据联动
- ✅ 历史数据填充
工作流引擎
- ✅ BPMN 2.0 标准
- ✅ 可视化流程设计
- ✅ 多级审批配置
- ✅ 会签、或签支持
审批中心
- ✅ 待办事项提醒
- ✅ 已办事项查询
- ✅ 我发起的审批
- ✅ 审批意见填写
💬 社交应用
即时聊天
- ✅ WebSocket 实时通信
- ✅ 消息类型丰富(文本、图片、语音、视频)
- ✅ 心跳机制保活
- ✅ 断线重连
会话管理
- ✅ 会话列表展示
- ✅ 置顶会话
- ✅ 免打扰设置
- ✅ 未读消息计数
朋友圈
- ✅ 动态发布
- ✅ 评论互动
- ✅ 点赞功能
- ✅ 图片预览
🔀 微前端架构
主应用集成
- ✅ qiankun 框架搭建
- ✅ 路由整合
- ✅ 状态共享机制
- ✅ 样式隔离
子应用拆分
- ✅ Vue 子应用
- ✅ React 子应用
- ✅ UniApp 子应用
- ✅ 独立开发部署
通信机制
- ✅ Props 传递
- ✅ CustomEvent 事件
- ✅ GlobalState 全局状态
- ✅ 跨应用通信
📦 核心组件与实战案例
1. 图片上传组件
企业级特性:
- ✅ 多端适配(H5/小程序/APP)
- ✅ 自动压缩、尺寸校验
- ✅ 预览、删除、拖拽排序
- ✅ 进度显示、失败重试
- ✅ 裁剪功能、水印添加
使用示例:
vue
<template>
<image-upload
v-model="images"
:max-count="9"
:max-size="5"
:auto-upload="true"
@success="handleSuccess"
/>
</template>
2. 审批流程组件
可视化工作流:
- ✅ 时间线展示
- ✅ 多状态支持(待审批、通过、拒绝等)
- ✅ 节点类型丰富(发起人、审批人、抄送人)
- ✅ 审批意见、头像展示
- ✅ 底部操作栏、弹窗输入
- ✅ 会签、或签配置
使用示例:
vue
<template>
<approval-process
:process_instance_id="processId"
types="travel"
@approve="handleApprove"
@reject="handleReject"
/>
</template>
3. 人员选择器
多功能选择:
- ✅ 单选/多选模式
- ✅ 搜索过滤
- ✅ 已选人员展示
- ✅ 部门筛选
- ✅ 自定义数据源
- ✅ 组织架构树
4. 复杂表单系统
动态表单引擎:
- ✅ 表单配置化
- ✅ 动态验证规则
- ✅ 字段联动
- ✅ 条件渲染
- ✅ 历史数据填充
5. WebSocket 实时通信
即时消息:
- ✅ 连接管理封装
- ✅ 心跳机制保活
- ✅ 断线重连策略
- ✅ 消息队列处理
- ✅ 离线消息同步
6. 权限控制指令
按钮级权限:
vue
<template>
<!-- 按钮权限 -->
<button v-permission="['admin:edit']">编辑</button>
<!-- 角色权限 -->
<button v-role="['manager']">审批</button>
<!-- 数据权限 -->
<view v-data-permission="userId">敏感数据</view>
</template>
7. 请求拦截器
统一处理:
typescript
// 请求拦截器
http.interceptors.request.use((config) => {
// 添加 Token
config.header['Authorization'] = `Bearer ${token}`;
// 添加租户 ID
config.header['TENANT-ID'] = tenantId;
// 参数加密
if (config.data) {
config.data = wrapEncryption(config.data);
}
return config;
});
// 响应拦截器
http.interceptors.response.use((response) => {
// 响应解密
if (response.data?.encryption) {
response.data = decrypt(response.data.encryption);
}
// 错误处理
if (response.data.code !== 0) {
handleError(response);
}
return response.data;
});
8. 状态管理封装
Pinia + Cache 混合存储:
typescript
export const useUserStore = defineStore('userStore', {
state: () => ({
userInfo: null,
token: null,
roles: [],
}),
getters: {
isLogin: (state) => !!state.token,
nickname: (state) => state.userInfo?.nickname,
},
actions: {
async getUser() {
const {data} = await getUserCenter();
this.userInfo = data.sysUser;
},
logout() {
this.token = null;
this.userInfo = null;
cache.clear();
},
},
persist: {
key: 'user-store',
paths: ['token'],
},
});
🔧 请求封装亮点
1. 拦截器系统
typescript
// 请求拦截器
http.interceptors.request.use((config) => {
// 添加 Token
config.header['Authorization'] = `Bearer ${token}`;
// 添加租户 ID
config.header['TENANT-ID'] = tenantId;
// 参数加密
if (config.data) {
config.data = wrapEncryption(config.data);
}
return config;
});
// 响应拦截器
http.interceptors.response.use((response) => {
// 响应解密
if (response.data?.encryption) {
response.data = decrypt(response.data.encryption);
}
// 错误处理
if (response.data.code !== 0) {
handleError(response);
}
return response.data;
});
2. 文件上传
typescript
// 多端适配的上传方法
const uploadFile = async (filePath: string) => {
// #ifdef H5
return await uploadFileForH5(filePath);
// #endif
// #ifdef MP-WEIXIN
return await request.uploadFile({filePath});
// #endif
// #ifdef APP-PLUS
return await request.uploadFile({filePath});
// #endif
};
3. 错误处理
typescript
// 统一错误处理
try {
await fetchData();
} catch (error) {
switch (error.statusCode) {
case 401:
// Token 过期,跳转登录
break;
case 403:
// 无权限
break;
case 500:
// 服务器错误
break;
}
}
🎨 多端适配技巧
1. 条件编译
vue
<template>
<view>
<!-- #ifdef H5 -->
<div>H5 专属内容</div>
<!-- #endif -->
<!-- #ifdef MP-WEIXIN -->
<view>小程序专属内容</view>
<!-- #endif -->
<!-- #ifdef APP-PLUS -->
<view>APP 专属内容</view>
<!-- #endif -->
</view>
</template>
2. 样式适配
scss
.container {
// rpx 单位自适应
width: 750rpx;
padding: 32rpx;
// 安全区域适配
padding-bottom: calc(32rpx + env(safe-area-inset-bottom));
// H5 专属样式
/* #ifdef H5 */
backdrop-filter: blur(20px);
/* #endif */
// 小程序专属样式
/* #ifdef MP-WEIXIN */
background: rgba(255, 255, 255, 0.9);
/* #endif */
}
3. API 适配
typescript
// 根据平台选择不同实现
export function getLocation() {
// #ifdef MP-WEIXIN
return wx.getLocation({type: 'gcj02'});
// #endif
// #ifdef H5
return navigator.geolocation.getCurrentPosition();
// #endif
// #ifdef APP-PLUS
return plus.maps.getCurrentPosition();
// #endif
}
📊 状态管理实践
1. 用户状态
typescript
export const useUserStore = defineStore('userStore', {
state: () => ({
userInfo: null,
token: null,
roles: [],
}),
getters: {
isLogin: (state) => !!state.token,
nickname: (state) => state.userInfo?.nickname,
},
actions: {
async getUser() {
const {data} = await getUserCenter();
this.userInfo = data.sysUser;
},
logout() {
this.token = null;
this.userInfo = null;
cache.clear();
},
},
persist: {
key: 'user-store',
paths: ['token'],
},
});
2. 应用状态
typescript
export const useAppStore = defineStore('appStore', {
state: () => ({
theme: 'light',
language: 'zh-CN',
isLoading: false,
}),
actions: {
toggleTheme() {
this.theme = this.theme === 'light' ? 'dark' : 'light';
},
showLoading(text: string) {
this.isLoading = true;
uni.showLoading({title: text});
},
},
});
🚀 性能优化实践
1. 分包加载
json
{
"pages": [
// 主包(<2MB)
{
"path": "pages/index/index"
},
{
"path": "pages/login/login"
}
],
"subPackages": [
{
"root": "pages/expense",
"pages": [
{
"path": "my_application/list"
},
{
"path": "cost_reporting/index"
}
]
}
]
}
2. 请求缓存
typescript
const cache = new Map();
const getCachedData = async (key: string, fn: () => Promise<any>) => {
const cached = cache.get(key);
if (cached && Date.now() - cached.timestamp < 300000) {
return cached.data;
}
const data = await fn();
cache.set(key, {data, timestamp: Date.now()});
return data;
};
3. 虚拟列表
vue
<!-- 小程序使用官方虚拟列表 -->
<recycler-viewer :list-data="listData" :row-height="100">
<view slot="row" slot-scope="{ item }">
{{ item.name }}
</view>
</recycler-viewer>
📖 学习建议与路线规划
🎯 对于初学者
建议按以下路线系统学习,预计 16-20 周(每周投入 10-15 小时):
第一阶段:基础入门(2-3 周)
重点掌握:
- 先看 专栏导读与学习路线,了解整体架构
- 学习 UniApp 项目创建完全指南,搭建开发环境
- 掌握 Vue 3 + TypeScript 基础语法
- 完成 uView UI 集成,快速上手组件开发
- 深入理解 项目架构设计 和 工程化配置
实践目标:创建一个简单的 Demo 项目
第二阶段:核心技能(4-5 周)
重点突破:
- 学习 请求封装,理解拦截器机制
- 掌握 状态管理 Pinia,学会数据流转
- 实践 自定义 Hook,提升代码复用能力
- 深入研究 组件开发,封装通用组件
- 掌握 多端适配技巧,实现一套代码多端运行
实践目标:完成一个小型电商小程序
第三阶段:进阶提升(3-4 周)
深度提升:
- 学习 权限系统设计,掌握 RBAC 模型
- 实践 性能优化,提升用户体验
- 掌握 WebSocket 实时通信,开发聊天功能
- 学习 单元测试,保障代码质量
实践目标:开发一个 OA 审批系统
第四阶段:实战案例(4-5 周)
综合实战:
- 电商小程序完整项目(商品、购物车、订单)
- 社交应用开发(即时聊天、朋友圈)
- 微前端架构实践,掌握大型项目管理
实践目标:独立完成企业级项目开发
🚀 对于有经验的开发者
可以按需查阅专题,快速提升:
🔧 组件开发专题
- 图片上传组件
- 复杂表单设计
- 审批流程组件
- 组件化开发实战
⚡ 性能优化专题
- 小程序性能优化
- 长列表虚拟滚动
- 图片优化完全指南
- 请求缓存策略
🔐 安全与权限专题
- API 加密与签名
- RBAC 权限系统设计
- Token 管理机制
💡 架构提升专题
- 高级 Hook 封装
- 枚举值管理
- 状态管理进阶
- 微信生态集成
- 微前端架构
🧪 测试与质量专题
- 单元测试与 E2E 测试
- 代码规范最佳实践
- CI/CD自动化部署
🎓 学习收获与能力提升
通过本系列 43 篇文章的系统学习,你将获得:
💪 硬实力提升
✅ 架构设计能力
- 掌握企业级应用架构设计方法
- 学会分层架构、模块化设计
- 能够独立设计可扩展、可维护的系统
✅ 技术深度
- Vue 3 Composition API 深入理解
- TypeScript 类型系统熟练运用
- uni-app 多端开发精通
- 性能优化原理与实践
✅ 工程化能力
- 建立完善的工程化思维
- 掌握自动化测试方法
- 熟悉 CI/CD流程
- 代码规范和质量控制
✅ 实战经验
- 电商小程序完整项目经验
- OA 审批系统开发经验
- 社交应用实时通信实现
- 微前端架构实践经验
🌟 软实力提升
✅ 问题解决能力
- 建立完整的问题诊断思维
- 掌握多种调试工具使用
- 能够快速定位和解决问题
✅ 学习能力
- 形成系统化学习方法
- 培养技术敏感度
- 保持持续学习习惯
✅ 沟通协作能力
- 代码注释和文档编写能力
- 团队协作开发经验
- Code Review 能力提升
🎯 职业发展助力
💼 求职竞争力
- ✅ 掌握企业需要的实战技能
- ✅ 具备中高级开发能力
- ✅ 有完整的项目经验
- ✅ 薪资提升 30%-50%
📈 技术影响力
- ✅ 建立完整的技术知识体系
- ✅ 能够在团队分享技术经验
- ✅ 参与开源项目贡献
- ✅ 撰写技术博客提升影响力
🚀 职业晋升
- ✅ 向高级开发工程师发展
- ✅ 向技术专家方向进阶
- ✅ 向架构师角色转型
- ✅ 向技术管理岗位迈进
📮 互动与交流
如果文章对你有帮助,欢迎:
- 👍 点赞:支持作者持续输出
- ⭐ 收藏:方便日后查阅
- 💬 评论:提出你的问题和建议
- 📢 分享:让更多人受益
📝 版权声明
本系列文章均为 CSDN 博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。
作者 :资深前端开发工程师
专注领域 :大前端技术架构与企业级应用开发
联系方式:可通过 CSDN 私信联系
最后的话:技术之路,学无止境。希望本系列文章能成为你 uni-app 开发路上的良师益友。如果你觉得有用,请不吝点赞支持!🙏