十年磨剑终成锋，一朝破竹势如虹
纸上得来终觉浅，绝知此事要躬行
10w级企业内部系统前端架构，几十个知名企业中后台实践
## 🔊 支持多端
**PC端web前端架构：Vue3+Pinia+Vite+TS+Element-plus，项目地址：[获取地址](https://www.wit-ui.com/pricing.html) 不开源**
**移动端跨平台前端架构：Uniapp+Vue3+Pinia+Vite+TS+WotDesignUni+TuniaoUI 支持VScode编辑器开发，项目地址：https://gitee.com/wit-ui/wit-app.git 开源**
**Electron桌面应用前端架构：Electron+Vue3+Pinia+Vite+TS+Element-plus，项目地址：[获取地址](https://www.wit-ui.com/pricing.html) 不开源**
**Nwjs桌面应用（支持XP系统）前端架构：Nwjs+Vue2+Vuex+Vite+js+Element-ui，项目地址：[获取地址](https://www.wit-ui.com/pricing.html) 不开源**
**[开发文档官方网址：https://www.wit-ui.com](https://www.wit-ui.com)**
## 🔊 安装说明
```bash
# win10安装node：node-v16.18.1-x64.msi(https://nodejs.org/download/release/v16.18.1/node-v16.18.1-x64.msi)
# vscode中文版插件：Chinese (Simplified)（必须安装）
# vscode快速生成语法糖模板: element-plus-helper（vue页面中输入vab-指令即可快速生成语法糖模板/输入el-快速生成代码）（必须安装）
# vscode代码校验: Eslint（必须安装）
# css编译时格式校验: stylelint（必须安装）
# vue3 Ts格式化:Vue - Official（必须安装）
# import 引入自动补全:Auto Import（必须安装）
# 自动补全 html 标签:Auto Close Tag（推荐安装）
# 自动重命名 html 标签:Auto Rename Tag（推荐安装）
# 查看你引入的依赖模块大小:Import Cost（可不安装）
# 查查看 git 提交历史:Git History（可不安装）
# 克隆项目
git clone https://www.gitee.com/wit-ui/wit-app.git
# 安装pnpm
npm install -g pnpm
# 安装依赖（pnpm、yarn、cnpm、npm均可，推荐用pnpm或cnpm）
pnpm i
# 本地h5开发
npm run dev:h5
# 本地app开发
npm run dev:app
# 本地h5生产打包
npm run build:h5
# 本地app生产打包
npm run build:app
# npm删除缓存
npm cache clean --force
# pnpm查看缓存路径
pnpm store path
# pnpm删除缓存
pnpm store prune
```
## 🔊 代码目录结构
```
├── .github # 自动化 ci 配置（可删除）
├── .vscode # vscode 配置（不可删除）
├── node_modules # 项目依赖模块
├── src
│ ├── api # API 服务模块
│ ├── components # 本地组件库
│ │ ├── witIcon # 自定义阿里图标库图标组件
│ │ ├── witStatusBar # 状态栏组件
│ │ ├── witTabbar # 自定义底部tabar组件
│ │ └── ...
│ ├── hooks # 全局hooks函数 包括$baseConfirmCenter全局弹窗组件/$baseMessageTop全局弱提示组件等
│ ├── hybrid # 本地html文件
│ ├── interceptors # 拦截器 包括请求拦截、登录拦截、路由拦截等权限控制功能
│ ├── layouts # 自定义底部tabar时，页面公用部分框架
│ │ ├── default.vue # 默认公用部分框架
│ │ ├── demo.vue # demo公用部分框架
│ │ └── tabbar.vue # 自定义tabbar公用部分框架
│ ├── pages # 页面
│ │ ├── error # 包括403/404/500/503页面，配合拦截器使用
│ │ ├── index # 首页
│ │ ├── login # 登录
│ │ ├── my # 我的
│ │ ├── news # 消息
│ │ └── test # 开发测试组件页面
│ ├── static # 本地静态资源
│ ├── store # pinia数据状态管理
│ │ ├── modules # pinia 数据模块集合
│ │ │ ├── common # 公用数据模块
│ │ │ ├── systemConfig # 系统配置模块
│ │ │ └── user # 用户信息模块
│ │ └── index # pinia数据模块化组合成一个主模块
│ ├── style # 公用样式 更改第三方组件样式
│ ├── types # 公用类型 存放自动生成的auto-import.d.ts/components.d.ts/uni-pages.d.ts等.d.ts文件，无须重复引用
│ ├── uni_modules # 第三方组件存放
│ ├── utils # ts 工具
│ │ ├── dict.ts # 获取字典方法
│ │ ├── encrypt.ts # 三级等保登录加密方法
│ │ ├── index.ts # 暴露基本方法
│ │ ├── platform.ts # 判断平台
│ │ ├── request.ts # 请求数据方法封装，类似axios请求封装
│ │ ├── validate.ts # 基本正则表达式表单校验
│ │ ├── witModal.ts # 全局modal-模态框方法
│ │ └── witNotify.ts # 全局notify-消息通知方法
│ ├── App.vue # 入口vue文件
│ ├── main.ts # # 入口ts文件
│ ├── manifest.json # 全局配置文件，由manifest.config.ts文件生成，无须手动更改自动生成
│ ├── pages.json # # 路由文件，由pages.config.ts文件生成，无须手动更改自动生成
│ ├── uni.scss # 全局css变量
│ └── wit.css # 全局第三方组件库css变量
├── .env # 全局接口域名配置文件，包括appid等
├── .env.development # 开发环境变量
├── .env.production # 生成环境变量
├── .env.test # 测试环境变量
├── .eslintrc.js # eslint 配置项
├── .gitignore # 排除提交git项
├── package.json # node启动配置
├── manifest.config.ts # 全局配置文件
├── pages.config.ts # 路由配置文件
├── index.html # 入口页
├── tsconfig.json # ts配置文件
└── vite.config.ts # vite 配置
```
## 🔊 后端返回 code 的约定
- 常用的 code：200-正常 500-错误提示用 401-回到登录页用 402-刷新 token 用
```bash
200: '服务器成功返回请求数据', //常用
201: '新建或修改数据成功',
202: '一个请求已经进入后台排队(异步任务)',
204: '删除数据成功',
400: '发出信息有误',
401: '用户没有权限(令牌失效、用户名、密码错误、登录过期)', //常用
402: '令牌过期', //常用
403: '用户得到授权，但是访问是被禁止的',
404: '访问资源不存在',
406: '请求格式不可得',
410: '请求资源被永久删除，且不会被看到',
500: '服务器发生错误', //常用
502: '网关错误',
503: '服务不可用，服务器暂时过载或维护',
504: '网关超时',
```
## 🔊 tsconfig.json 详解
```bash
"incremental": true, // TS编译器在第一次编译之后会生成一个存储编译信息的文件，第二次编译会在第一次的基础上进行增量编译，可以提高编译的速度
"tsBuildInfoFile": "./buildFile", // 增量编译文件的存储位置
"diagnostics": true, // 打印诊断信息
"target": "ES5", // 目标语言的版本
"module": "CommonJS", // 生成代码的模板标准
// 默认值 target === "es3" or "es5" ?"commonjs" : "es6"
"outFile": "./app.js", // 将多个相互依赖的文件生成一个文件，可以用在AMD模块中，
// 即开启时应设置"module": "AMD",
//target 为 es6 时: ["dom", "es6", "dom.iterable", "scripthost"]
"allowJS": true, // 允许编译器编译JS，JSX文件
"checkJs": true, // 允许在JS文件中报错，通常与allowJS一起使用
"outDir": "./dist", // 指定输出目录
"rootDir": "./", // 指定输出文件目录(用于输出)，用于控制输出目录结构
"declaration": true, // 生成声明文件，开启后会自动生成声明文件
"declarationDir": "./file", // 指定生成声明文件存放目录
"emitDeclarationOnly": true, // 只生成声明文件，而不会生成js文件
"sourceMap": true, // 生成目标文件的sourceMap文件
"inlineSourceMap": true, // 生成目标文件的inline SourceMap，//inline SourceMap会包含在生成的js文件中
"declarationMap": true, // 为声明文件生成sourceMap
"typeRoots": [], // 声明文件目录，默认时node_modules/@types
"types": [], // 加载的声明文件包
//如果指定了某个值， 她会在 typeRoots 下找这个包，找到了就只加载这个包
"removeComments":true, // 删除注释
"noEmit": true, // 不输出文件,即编译后不会生成任何js文件
"noEmitOnError": true, // 发送错误时不输出任何文件
"noEmitHelpers": true, // 不生成helper函数，减小体积，需要额外安装，常配合importHelpers一起使用
"importHelpers": true, // 通过tslib引入helper函数，文件必须是模块
"downlevelIteration": true, // 降级遍历器实现，如果目标源是es3/5，那么遍历器会有降级的实现
"strict": true, // 开启所有严格的类型检查
"alwaysStrict": true, // 在代码中注入'use strict'
"noImplicitAny": true, // 不允许隐式的any类型
"strictNullChecks": true, // 不允许把null、undefined赋值给其他类型的变量
"strictFunctionTypes": true, // 不允许函数参数双向协变
"strictPropertyInitialization": true, // 类的实例属性必须初始化
"strictBindCallApply": true, // 严格的bind/call/apply检查
"noImplicitThis": true, // 不允许this有隐式的any类型s
"noUnusedLocals": true, // 检查只声明、未使用的局部变量(只提示不报错)
"noUnusedParameters": true, // 检查未使用的函数参数(只提示不报错)
"noFallthroughCasesInSwitch": true, // 防止switch语句贯穿(即如果没有break语句后面不会执行)
"noImplicitReturns": true, //每个分支都会有返回值
"esModuleInterop": true, // 允许export=导出，由import from 导入
"allowUmdGlobalAccess": true, // 允许在模块中全局变量的方式访问umd模块
"moduleResolution": "node", // 模块解析策略，ts默认用node的解析策略，即相对的方式导入
"baseUrl": "./", // 解析非相对模块的基地址，默认是当前目录
"paths": { // 路径映射，相对于baseUrl
// 如使用jq时不想使用默认版本，而需要手动指定版本，可进行如下配置
"jquery": ["node_modules/jquery/dist/jquery.min.js"]
},
"rootDirs": ["src","out"], // 将多个目录放在一个虚拟目录下，用于运行时，
//即编译后引入文件的位置可能发生变化，
//这也设置可以虚拟src和out在同一个目录下，不用再去改变路径也不会报错
"listEmittedFiles": true, // 打印输出文件
"listFiles": true , // 打印编译的文件(包括引用的声明文件)
"jsx":"Preserve" //在 .tsx 中支持 JSX ：React 或 Preserve
"jsxFactory":"" //默认值 React.createElement 。 jsx 设置为 React 时使用的创建函数
"lib": [ // 编译过程中需要引入的库文件的列表
"es5",
"es2015",
"es2016",
"es2017",
"es2018",
"dom"
]
},
// 指定一个匹配列表（属于自动指定该路径下的所有ts相关文件）
"include": [
"src/**/*"
],
// 指定一个排除列表（include的反向操作）
"exclude": [
"demo.ts"
],
// 指定哪些文件使用该配置（属于手动一个个指定文件）
"files": [
"demo.ts"
]
```
## 🔊 提高网站加载速度
nginx 配置：vim /etc/nginx/nginx.conf
```bash
#是否启动gzip压缩,on代表启动,off代表开启
gzip on;
#需要压缩的常见静态资源
gzip_types text/plain application/javascript application/x-javascript text/css application/xml text/javascript application/x-httpd-php image/jpeg image/gif image/png;
#由于nginx的压缩发生在浏览器端而微软的ie6很坑爹,会导致压缩后图片看不见所以该选
项是禁止ie6发生压缩
gzip_disable "MSIE [1-6]\.";
#如果文件大于1k就启动压缩
gzip_min_length 1k;
#以16k为单位,按照原始数据的大小以4倍的方式申请内存空间,一般此项不要修改
gzip_buffers 4 16k;
#压缩的等级,数字选择范围是1-9,数字越小压缩的速度越快,消耗cpu就越大
gzip_comp_level 2;
#引导的在/etc/nginx/conf.d目录下所有后缀为.conf的子配置文件
include /etc/nginx/conf.d/*.conf;
```
```bash
nginx -t
nginx -s reload
```
## 🔊 样式scoped
强烈建议使用 scoped ，父组件的样式将不会渗透到子组件中。不过一个子组件的根节点会同时受其父组件的 scoped CSS 和子组件的 scoped CSS 的影响。这样设计是为了让父组件可以从布局的角度出发，调整其子组件根元素的样式。
```bash
#通过深度选择器自定义子组件样式
```
## 🔊 如何快速编写完成后端接口
- 第 1 步: 本地启动一个最原始的带 mock 的项目，退回到登录页，打开浏览器控制台，开始模拟登录，此时你可以在浏览器 network（网络）中看到/login、/userInfo、/logout的 json 格式和参数
- 第 2 步：开始完整照着 network 编写后端接口，使用 postman 测试通过（注意 postman 支持跨域而浏览器不支持，故需要先配置好对应的后端跨域）
- 第 3 步：修改src/interceptors/request.ts里面的 baseURL 即可
- 第 4 步：如需使用进阶方案，采用后端路由，请详见【路由配置】模块
## 🔊 如何连接后端接口
- 直接连接方案（记得后端配置跨域）
修改位置.env里面VITE_APP_BASE_URL参数
```bash
/**
* @description 导出网络配置
**/
.env文件中VITE_APP_BASE_URL='https://apifoxmock.com/m1/4593503-4242983-default'
```
## 🔊 项目开发必要接口
本项目需要三个必要的接口，联调前务必保证这登录接口、用户信息接口、退出接口无问题，请注意application/x-www-form-urlencoded;charset=UTF-8与 application/json;charset=UTF-8请求的区别，具体可在src/interceptors/request.ts 中配置，注意：除登录接口外其他接口连接后端后携带 token，格式如下Authorization: Bearer admin-token-24ba1FFF-AcC8-f0AE-ECea-A1EE12d712Ae-后端在登陆时返回给你的token字符串
- 登录接口 /login（post 请求） application/json;charset=UTF-8 请求参数（默认格式）
```bash
{
"username": "admin",
"password": "123456"
}
```
返回格式：（必须严格按照此格式，不能为空这里返回的 token 会在今后所有的接口中自动通过 headers 的 Authorization 携带到后端，后端注意接收并处理跨域问题）
```bash
{
"code": 200,
"msg": "success",
"data": {
"token": "admin-accessToken-xxxxxx"
}
}
```
用户信息接口 /userInfo（get 请求）
此接口默认会通过 headers 将 Authorization（token）传递到后端，后端根据 headers 判断用户所包含的权限，并返回相应的数据即可
- 返回格式：（必须严格按照此格式，不能为空）
[rbac 文档](https://auth0.com/docs/manage-users/access-control/sample-use-cases-role-based-access-control)
```bash
{
"code": 200,
"msg": "success",
"data": {
"username": "admin",
"roles": ["Admin"],
"permissions": ["read:system", "write:system", "delete:system"],
"avatar": "https://i.gtimg.cn/club/item/face/img/2/16022_100.gif"
}
}
```
退出接口 /logout（get 请求）
此接口默认会通过 headers 将 Authorization（token）传递到后端，后端根据 headers 判断用户所包含的权限，退出对应的账号即可
- 返回格式
```bash
{
"code": 200,
"msg": "success"
}
```
- 其余可配置关闭的接口，如顶部的搜索、通知接口请自行查看mock/controller下的示例
- 接口风格将都是 restful 的规范
## 🔊 前端请求示例
- 强烈建议：所有请求放到 src/api 文件夹下
```bash
// post请求示例
import request from "@/utils/request";
export function getList(data) {
return request({
url: "/table/list",
method: "post",
data,
});
}
```
```bash
// get请求示例
import request from "@/utils/request";
export function getList(params) {
return request({
url: "/table/list",
method: "get",
params,
});
}
```
## 🔊 前端请求约定
- 请求中会在 headers 中自动传入 token，格式如下Authorization: Bearer admin-token-24ba1FFF-AcC8-f0AE-ECea-A1EE12d712Ae-后端在登陆时返回给你的token字符串
```bash
/*表格中请求参数约定*/
{
"pageNum": 1, //页数
"pageSize": 10 //每页条数
}
```
resultful 的规范，后端返回 JSON 数据的约定
```bash
{
"code": 200, //成功的状态码
"msg": "success", //提示信息
"data": { //返回数据
"list": [{}，{}，{}], //返回数组
"total": 238, //总条数（表格中用到，其它接口可以不返回）
}
}
```
## 🔊 后端返回 code 的约定
- 常用的 code：200-正常 500-错误提示用 401-回到登录页用 402-刷新 token 用
```bash
200: '服务器成功返回请求数据', //常用
201: '新建或修改数据成功',
202: '一个请求已经进入后台排队(异步任务)',
204: '删除数据成功',
400: '发出信息有误',
401: '用户没有权限(令牌失效、用户名、密码错误、登录过期)', //常用
402: '令牌过期', //常用
403: '用户得到授权，但是访问是被禁止的',
404: '访问资源不存在',
406: '请求格式不可得',
410: '请求资源被永久删除，且不会被看到',
500: '服务器发生错误', //常用
502: '网关错误',
503: '服务不可用，服务器暂时过载或维护',
504: '网关超时',
```
## 🔊 同道中人交流群
