# phi-cloud-home

**Repository Path**: phoenix1025/phi-cloud-home

## Basic Information

- **Project Name**: phi-cloud-home
- **Description**: phi-cloud-home
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2022-04-25
- **Last Updated**: 2022-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 项目说明

## 依赖管理

本项目使用pnpm作为包的依赖管理工具，pnpm具体介绍看[pnpm document](https://pnpm.io/zh/)

下载项目后请先安装pnpm, 执行命令`npm i pnpm -g`进行安装

使用`pnpm i`进行项目依赖安装

使用`pnpm run dev`或者`npm run dev`启动项目

## 必装vscode插件

**点开插件页输入`@recommended`显示本项目推荐安装插件并全部安装**

**johnsoncodehk.volar** 此插件提供vue3语法提示支持

**mrmlnc.vscode-scss** 此插件提供项目内scss变量相关提示

**mariusalchimavicius.json-to-ts** 此插件提供JSON到TS类型的便捷转换

**dbaeumer.vscode-eslint** 此插件提供eslint规则提示

**esbenp.prettier-vscode** 此插件提供代码格式化功能, 请在vscode设置中加入以下设置，以统一代码风格

```json
{
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
}
```

## vue3写法约定

建议全程使用`<script setup>`写法以保持代码的简洁易读，具体文档参照 [vue3 setup](https://vuejs.org/api/sfc-script-setup.html#script-setup) 。

当一个组件或者一个页面的setup代码超出200行左右时，请考虑抽取hook函数进行业务相关部分的代码封装，保持入口文件逻辑代码的清晰易读。

当一个组件和hook使用过于频繁，请考虑封装成公共组件和公共hook

***如果有警告和错误请及时处理，提交代码前最起码的要求是控制台不能有警告和错误，除非是不可避免的。***

## antd相关问题

### 版本问题

目前antd的vue3支持版本已发布v3正式版, 本项目会持续跟进此v3版本，文档请参考 [antd document](https://www.antdv.com/docs/vue/introduce-cn), 目前我发现的最大改动是表格自定义插槽的改动，详情请参照 [a-table 从 v1 / v2 升级到 v3](https://www.antdv.com/components/table-cn#%E4%BB%8E-v1-v2-%E5%8D%87%E7%BA%A7%E5%88%B0-v3)

### 主题定制的问题

由于antd使用less进行样式管理，所以如果需要改变一些公共样式就需要通过修改less配置中的`modifyVars`进行更改，项目中就主题色进行了更改，具体配置见`vite.config.ts`中的`config.css.preprocessorOptions.less`

所有可修改变量参照 [antd 样式变量](https://www.antdv.com/docs/vue/customize-theme-cn#Ant-Design-Vue-%E7%9A%84%E6%A0%B7%E5%BC%8F%E5%8F%98%E9%87%8F)

由于需要减少打包的体积，所以本项目采用了按需引入antd组件进行使用的方式

***需要注意的是按需引入时需要同时引入组件的less样式，使在`modifyVars`中修改的less变量生效, 具体示例可参考`@/components/antd.ts`***

### 默认样式修改约定

如果需要全局生效，请添加样式至`@/style/base/antd.scss`。 如果只是组件内生效，请使用新写一个不带scope的style标签，用包裹组件顶部class的方式进行修改，防止样式冲突。不建议使用`:deep()`的方式进行修改，有些antd样式通过这种方式修改会没有作用，如果使用这种方式，这些样式代码有些混入业务相关样式，有些单独存放，会增加后期维护难度。

### 组件的类型

定义文件已全局引入，无需担心类型问题

`@/components/components.d.ts`此文件用来定义全局组件类型

### message的使用

一直以来message的使用总有一个通病就是，如果一个页面接口全部报错会冒出一大推message，很影响使用体验，所以我轻度封装了antd的message。

如果需要使用message请优先使用`@/utils/message.ts`内部封装的，如果需要自定义，请在使用原生message的时候配置key参数为`@/utils/message.ts`中的`msgKey`，具体写法可以参考文档或者我封装好的。

## 关于console

项目中对于console下的原生log方法进行了重写，主要作用是生产环境屏蔽一切log调试日志，我认为这些调试日志如果有必要还是需要保留的，用来帮助后期维护。但尽量在提交之前删除不必要的调试日志，**保留的调试日志尽量写明目的**。

## 关于localstorage

### 现有localStorage问题

- 原生的localStorage没有进一步的类型支持和json对象互转

- 原生的`localStorage`有很多不适应我们当前项目的地方，现在公卫项目已经有两个项目，都部署在同一域下，因为同一域下会共享`localstorage`，这就产生一个`localStorage`管理混乱的问题。

### 解决方案

所有的localstorage操作请使用`@/utils/storage.ts`中的StorageUtil类的静态方法进行操作。

进一步封装了`localStorage`, 添加了对于`localstorage`的类型支持，之后如果需要往`localStorage`添加新的信息请前往`@/utils/storage.ts`中往`Storage`接口中添加相应的字段。

为了解决多项目共用同一域的问题我为`localStorage`添加了命名空间的概念，只要使用封装的方法操作`localStorage`就不必担心不同项目命名冲突的问题，每个项目的内容都存储在不同的`key`下

## 关于axios

所有的封装逻辑都在`@/utils/request`中，返回的错误信息不需要在业务代码中进行处理，全部封装到了拦截器中。

请求返回拦截器中，将data中的数据直接返回到了业务端，由于axios默认类型定义是在data外层又包了一层请求相关的信息，这些都不需要在业务逻辑中处理，故我重写了axios的一些类型使得在配置了拦截器后业务端能得到正确的返回类型。具体定义在`@/utils/request/axios.d.ts`。

为axios添加了两个额外的配置传递。一个是isMock，用来控制是否使用mock基础地址，默认是false，一个是isAuth。用来控制是否在请求头上添加token，默认是true

## 关于网络接口函数

### 目录归类

接口按照后端服务进行归类，最多两层深度，第一层是后端服务名，第二层是服务下的各个模块文件夹，二层文件夹下放置各模块的接口定义，具体是哪个后端服务可以根据接口地址判断。

### 接口定义

**禁止将业务代码逻辑写入api接口函数**，接口函数只做一件事，那就是请求和返回数据，这样的好处就是可以高度复用定义好的接口函数，减少不必要的开发成本。

定义一个接口前，务必写好所有的请求和返回的ts类型，尽量给每个参数加上注释，不给使用方出错的机会，所有的接口地址请使用枚举类型进行归类存放，杜绝地址写错的低级错误，添加注释还可以告知使用方此地址的作用，虽然前期可能会多花一点时间，但是越往后期使用起来越可以减少沟通和维护成本。

### 代理

由于后端接口没有处理跨域问题，导致前端需要配置代理解决，代理请在`@/config/proxy.config.ts`中进行配置

## 网络请求loading状态的获取约定

每一个网络请求的loading状态是和业务逻辑无关的，在业务代码中大量的充斥此类代码会影响业务逻辑代码的书写，和后期的维护。

将全局的loading状态放到pinia中进行细粒度管理是一个好的方法，需要获取某个网络连接的状态的时候直接从全局状态管理中获取就可以了。

## 路由

由于还没有涉及到动态路由，所以这里还没有对动态路由处理。

路由这里我引入了中间件的概念，来优雅的处理路由权限的问题，在`@/router/middleware`中添加相应的中间件并导出，然后在路由的meta属性中添加`middleware`属性添加需要的拦截中间件即可，无需后续再在路由拦截器添加额外的拦截代码，分离了各种路由相关拦截逻辑，增加后期在路由权限方面的可维护性。

所有路由中间件都必须实现`MiddlewareFunction`定义，中间件的执行顺序是按照数组的顺序执行。

由于出现了此概念，所以我重写了`vue-router`的`RouteMeta`定义在原来的基础上添加了`middleware`字段的定义，防止加入不符合要求的路由中间件函数

## 公共样式

项目中加入了`reset.css`重置了浏览器默认样式

如果一个样式的值经常使用那就需要变为scss变量(`@/style/vars`), 项目中已经集成了一些ui规范上的一些公共变量

如果一组样式经常使用，可以考虑抽取成scss的mixin(`@/style/utils`)，项目中集成了一些常用mixin

这些公共scss变量和mixin已经配置在了vite中`config.css.preprocessorOptions.scss.additionalData` 无需二次引入, 如果安装了推荐插件还可以得到scss变量和mixin的提示