hg-lvke-web

前端开发

1. 脚手架创建前端项目流程

• 研发网登录前端框架（www.h2018.dev-nb.com, cacpuser/Cacpuser1!@），进入“CACP开发助手”；
• 应用登记(切换菜单到“应用登记注册”)；

• 脚手架创建及下载（切换菜单到“应用脚手架”），选择已登记应用，创建前端脚手架（系统缩写-模块缩写-web）并下载；

2. 前端结构说明

|── public                                  // 公共资源
│   ├── config.js                           // 项目部署后使用此配置，本地开发无需关注
│   ├── favicon.ico                         // 项目favicon小图标

├── src                                     // 源代码
│   ├── apis                                // 所有 HTTP 请求
│   │   ├── user.ts                         //（根据业务模块命名，和 /views/* 一一对应）
│   │   ├── authority.ts                    // 根据用户获取角色与权限
│   │   ├── frame.ts                        // 获取用户信息
│   ├── assets                              // 图片样式等静态资源
|   ├── components                          // 公共组件
|   ├── directives                          // 通用指令封装
│   │   ├── index.ts                        // directives文件整合入口
│   │   ├── permission.ts                   // 校验页面功能权限方法
|   ├── hooks                               // 公共方法封装
|   ├── plugins                             // 插件配置
│   │   ├── index.ts                        // 插件文件整合入口
│   │   ├── icon.ts                         // cacp/svg-icons图标全局注册
│   ├── router                              // 路由
│   │   ├── app-router.ts                   // 根据项目大小调整，项目模块少可以集中在app-router.ts里面配置，反之（根据业务模块命名，和 /views/* 一一对应）
│   │   ├── index.ts                        // 路由入口
│   ├── stores                              // 全局 store 管理
│   │   ├── index.ts                        // store文件整合入口
│   │   ├── core.ts                         // 获取用户信息
│   │   ├── pinia.ts                        // pinia配置
│   ├── types                               // TS类型定义
│   │   ├── user.ts                         //（根据业务模块命名，和 /views/* 一一对应）
│   ├── utils                               // 全局公用方法
│   │   ├── authhelper.ts                   // 401报错消息发送给门户框架，以及框架处理
│   │   ├── frame.ts                        // 监听门户发送过来的用户信息消息，以及监听cookie消息
│   │   ├── http.ts                         // 调用不同应用接口服务，全url访问
│   │   ├── request.ts                      // 全局 http 请求方法封装，调用相同应用接口服务，相对路径
│   ├── views                               // 页面视图
│   │   ├── user                            // 响应路由切换的 vue 组件（根据业务模块命名，和 /apis/* 一一对应）
│   │   ├── ErrorView                       // 错误页面
│   │   ├── HomeView                        // 首页
│   ├── App.vue                             // 入口vue
│   ├── main.ts                             // vue 入口加载组件初始化等
│   ├── config.ts                           // 自定义配置，本地开发与后台接口联调参数配置
├── vite.config.ts                          // vite配置
├── .gitignore                              // 文件提交忽略配置
├── .prettierrc.json                        // 代码格式化配置
├── nginx.conf                              // ng配置，部署后生效
├── node_version                            // node版本设置，部署后生效
├── Dockerfile                              // 项目部署X86环境Dockerfile配置，部署后生效
├── Dockerfile-arm                          // 项目部署arm环境Dockerfile配置，部署后生效
└── package.json                            // 包配置
└── package-lock.json                       // 包下载地址，误删除tsf-consul-template-docker-x86.tar
└── tsf-consul-template-docker-x86.tar      // X86环境tsf配置，部署后生效
└── tsf-consul-template-docker-arm.tar      // arm环境tsf配置，部署后生效

3. 脚手架启动

3.1 运行脚手架

• 在根目录执行命令 npm install （只在项目第一次运行时执行项目依赖安装）；
• 在根目录下执行 npm run dev；
• 在浏览器打开http://localhost:8080/查看运行的项目；
• 脚手架支持热更新，运行中更新代码后保存，自动操作触发热更新；

3.2 技术栈

• 前端总体技术架构与开发规范基于：Vue3+Vuerouter+Pinia+ElementPlus+Axios+ES6+Node.js；
• 技术架构及开发规范：http://web-dev.rd.domain.com/
• css预处理器建议使用less npm install less less-loader ； 备注：如果旧项目中使用sass，执行npm install sass sass-loader，node-sass已弃用；

4. 代码提交

• 参考代码提交

5. 开发示例

5.1 开发主要涉及到的文件

根据项目实际需求开发修改以下文件：

• API定义 src/apis/*
• assets静态文件 src/assets/*
• 公共组件文件封装 src/components/*
• 通用指令封装directives src/directives/*
• 公共方法封装hooks src/hooks/*
• cacp/svg-icons图标全局注册plugins src/plugins/*
• 路由及路由组件 src/router/*
• stores文件 src/stores/*
• 类型定义types src/types/*
• 网路请求整合 src/utils/*
• VUE文件 src/views/*
• 左侧菜单配置 src/App.vue
• 请求后台服务地址 config.ts

5.2 添加功能页面

• 根据业务需求在/src/views文件夹下创建新的业务文件夹，根据业务模块添加user文件夹，相关功能页面全部写在该文件夹下，目录的层级不要太深，添加src/views/user/UserInfoView.vue

  <template>
    <div>
      <h3>人员信息</h3>
        <el-table :data="personArr">
        <el-table-column label="编号" prop="id">
        </el-table-column>
        <el-table-column label="姓名" prop="name">
        </el-table-column>
        <el-table-column label="关区号" prop="customsCode">
        </el-table-column>
      </el-table>
    </div>
</template>

<script setup lang="ts">
import { reactive } from 'vue'
import type { User } from '@/types/user'

const personArr = reactive<Array<User>>([
    { id: '1', name: '张三', customsCode: '4200', },
    { id: '2', name: '李四', customsCode: '5200', },
    { id: '3', name: '王五', customsCode: '0100', },
])

</script>

<style scoped lang="less">

</style>

• 增加路由模块src/router/app-router.ts

import type { RouteRecordRaw } from 'vue-router'

const routers: Array<RouteRecordRaw> = [
  {
    path: '/user-info',
    name: 'userInfo',
    component: () => import('@/views/user/UserInfoView.vue'),
    meta: {
      title: '用户信息',
      anonymous: true,
      keepAlive: true
    }
  },
]

export default routers

• 添加新页面路由到src/router/index.ts中。
• 路由路径要有描述性和包含关键词，路由长度越短越好，不要有太多参数。
• 路由的路径要全小写字母，连词符要用中划线(-), 不要使用下划线(_)。

import { createRouter, createWebHashHistory, RouterView } from 'vue-router'

import appRouter from './app-router'

const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    {
      path: '/',
      component: RouterView,
      children: [
        {
          path: '/',
          redirect: '/home'
        },
        {
          path: 'home',
          name: 'home',
          component: () => import('@/views/HomeView.vue'),
          meta: {
            title: '首页',
            anonymous: true,
            keepAlive: true
          }
        },
        ...appRouter
      ]
    }
  ]
})
// ...

• 向侧边栏目录添加新页面目录信息src/App.vue，侧边栏导航只在开发环境展示；

// ...
<router-link to="/user-info">
    <el-menu-item index="UserInfo">
      <el-icon><House /></el-icon>
        <span>用户信息</span>
    </el-menu-item>
</router-link>
// ...

• 用户模块效果，用户列表页面

5.3 添加接口调用

• 根据业务功能在/src/apis下创建同views中一样的同名文件/src/apis/user.ts
• 脚手架中封装了请求工具request（/src/utils/request.ts）和http(/src/utils/http.ts),采用axios的请求，增加了请求拦截和响应拦截，如果需要在请求前增加统一参数，或者响应时对数据统一处理可在此修改； 备注：request.ts调用相同应用接口服务，使用相对路径，http.ts调用不同应用接口服务，全url访问，使用绝对路径，使用场景前端与后端不是同一个服务；

import type { AxiosResponse } from 'axios'
import request from '@/utils/request'
import type { Result } from '@cacp/ui'
import type { Custom } from '@/types/user'

const contextPath = '/后端服务名'

// 关区翻译
export async function queryCustom(query: Array<String>): Promise<Result<Array<Custom>>> {
    const res: AxiosResponse<Result<Array<Custom>>> = await request.post(`${contextPath}/customs/query-customs`, query)
    return res.data
}

• 在业务页面添加api请求数据/src/views/user/UserInfoView.vue

<template>
    <div>
      <h3>人员信息</h3>
        <el-table :data="personArr">
        <el-table-column label="编号" prop="id">
        </el-table-column>
        <el-table-column label="姓名" prop="name">
        </el-table-column>
        <el-table-column label="关区号" prop="customsCode">
        </el-table-column>
        <el-table-column label="关区" prop="customsName">
        </el-table-column>
      </el-table>
    </div>
</template>

<script setup lang="ts">
import { reactive } from 'vue'
import type { User, Custom } from '@/types/user'
import type { Result } from '@cacp/ui'
import * as userInfoApis from '@/apis/user'

const personArr = reactive<Array<User>>([
    { id: '1', name: '张三', customsCode: '4200', },
    { id: '2', name: '李四', customsCode: '5200', },
    { id: '3', name: '王五', customsCode: '0100', },
])

queryCustomInfo()

async function queryCustomInfo(): Promise<void> {
  const customCodes: Array<string> = []

  for (const preson of personArr) {
    customCodes.push(preson.customsCode)
  }

  const res: Result<Array<Custom>> = await userInfoApis.queryCustom(customCodes)
  if (res.code === SuccessResultCode) {
    for (const preson of personArr) {
      for (const custom of res.data) {
        if (preson.customsCode === custom.code) {
          preson.customsName = custom.name
        }
      }
    }
  }
}
</script>

<style scoped lang="less">

</style>

5.4 本地开发代理配置

• 脚手架本地开发代理配置(src/config.ts)，通过本地代理配置，即可与后端服务（本地/云上部署后）进行接口调试；
• 前端云上环境代理采用根目录下的 nginx.conf 进行配置，保持默认即可，配置代理到 API网关 上；

5.4.1 本地前端与本地后端交互

• 配置代理与本地后端交互(src/config.ts)，备注：最新后端脚手架已解决跨域，可以直接在/src/config.ts中配置后台服务地址;

// ...
import type { CacpConfig } from '@cacp/ui'

const devConfig: CacpConfig = {
  SERVICE_ID: 'demo',
  SERVICE_NAME: 'Demo',
  SERVICE_API: 'http://10.200.**.**:24001/', // 对应本地后台服务的ip+端口
  SERVICE_PAGESIZE: 20,
  SERVICE_TIMEOUT: 10000,
  FRAME_API: 'http://app-api.dev-nb.com', // 指定环境api网关域名
  NEED_USER_AUTHORITY: true
}

const $config = (window as any).$config as CacpConfig
const { DEV } = import.meta.env
export default DEV ? devConfig : $config
// ...

    

• 配置代理与本地后端交互(vite.config.ts)，备注：涉及跨域使用此方法

// ...
server: {
  port: 8080,
  // 是否自动在浏览器打开
  open: true,
  proxy: {
    // 将'localhost:3000/api/服务名/接口名'代理到'http://10.200.**.**:24001/接口名'
    '/api/后端服务名': {
      target: 'http://10.200.**.**:24001/', // 对应本地后台服务的ip+端口
      changeOrigin: true, // 如果接口跨域，需要进行这个参数配置
      rewrite: (path) => path.replace('/api/后端服务名', '') // 来重写地址，将前缀 '/api' 转为 '/'。
    }
  }
}
// ...
    

• 为前端项目配置本地host映射，如果是windows环境，一般是在C:\Windows\System32\drivers\etc\hosts文件进行配置，如果是arm环境，一般是在\etc\hosts文件进行配置；其配置格式为127.0.0.1 local.系统缩写-模块缩写.dev-nb.com，映射域名的二级域名需要与前端框架保持一致；
• 访问 www.h2018.dev-nb.com, 并登录，新开浏览器页签访问host配置的域名，即可正常通过api网关访问云上环境部署的后台服务；

5.5 交互结果

• 如若首次访问本地页面报接口错误，属于正常现象，请根据实际开发配置/src/config.ts文件中的参数；

6. 调试

• 代码中使用console.log('res', res)

// ...
queryCustomInfo()

async function queryCustomInfo(): Promise<void> {
  const customCodes: Array<string> = []

  for (const preson of personArr) {
    customCodes.push(preson.customsCode)
  }

  const res: Result<Array<Custom>> = await userInfoApis.queryCustom(customCodes)
  console.log('res', res)
  if (res.code === SuccessResultCode) {
    for (const preson of personArr) {
      for (const custom of res.data) {
        if (preson.customsCode === custom.code) {
          preson.customsName = custom.name
        }
      }
    }
  }
}
// ...
    

• 代码中使用debugger (不推荐)，多人协同开发时，误提交debugger影响他人开发；