aiquery2/web

@peace/template_front_client

基于 React.18 + Vite.4 预置 Antd.5 的客户端（web）

简洁

本项目以核心包@peace/react_client封装服务内容。

以服务端渲染（SSR）为核心，提供日常工作所需的变量配置、路由配置、跨平台数据请求、统一资源管理、工具函数预置等相关内容。

使用

使用前可参阅下方 目录结构 了解项目结构

启动服务

确保 Node.js 和 npm 已安装。

npm start

建议使用 vscode 的 运行和调试（F5）快捷键启动服务，更可方便配置环境变量

项目配置

项目配置文件位于 config.cjs 文件，可根据实际需求进行配置。

配置内容均已在文件中预置和注释说明，可根据实际需求进行修改。

• 关键配置（*）
  • vite：Vite 相关配置 https://vitejs.cn/vite5-cn/config/
    • envPrefix：环境变量前缀，此前缀的环境变量将会被注入到 window.env 中
    • server：
      • alias: 别名配置（框架预置了一下别名以供调用）
        • @u：工具集目录
        • @comps：公共组件目录
        • @assets：静态资源目录

功能模块编写sections

模块化设计，以功能模块为单位进行编写。

模块应该在 client/src/sections 目录下创建

目录结构如下：

模块
├── actions            // Redux actions
├── components         // 组件
├── container          // 容器
├── index.js           // 模块入口文件
└── router.js          // [!]路由文件

路由配置router.js

路由文件以对象形式配置，兼顾路由导航及 Menu 主菜单、面包屑等信息配置

.eg

import { HomeOutlined, ApartmentOutlined, } from "@ant-design/icons";
import Index from "./container";

export default {
  type: "inner",                         // 路由类型 （'inner' 出现在 layout 布局内 | 'outer' layout 布局外，内容占满页面全部）
  route: {
    key: "home",                         // 路由 key
    path: "home",                        // 路由
    component: Index,                    // 路由对应组件
    label: "Home",                       // 导航栏或面包屑显示的名称 
    icon: <HomeOutlined />,              // 导航栏图标
    nav: true,                           // 是否显示在左侧 Sider - Menu 导航栏
    auth: ["admin"],                     // 访问权限 key
    children: [                          // 子路由
        // { ... 重复以上配置 },
    ],
  },
};

Redux actions

框架使用 Redux 进行状态管理，以 actions 为基础，提供 reducer 和 store 等内容。

对于数据请求内容，根据需要可编写 action 以存储‘状态’并使用

• 编写action

  // actions/auth.js
  import { basicAction, apiTable } from "@u"
  
  const login = basicAction.post('/login', {
    reducerName: "user"                   // 存储状态的 reducer 名称
  });
  
  export default { login }
  

  basicAction 为框架多次封装的 action（基于@peace/react_client - request，更多参数可参考相关目录），基于此方法可免于编写reducer

  所有 action 需在 入口文件index.js 中暴露,以集中至 state.global 方便调用

  // actions/index.js
  import actions from "./auth";
  
  export default {
      ...actions
  }
  

• 使用action

  在 container 或 components 等地方使用 action时：

  import { useDispatch, useSelector } from "react-redux";
  
  export default function login (){
    const dispatch = useDispatch();                               // 获取 dispatch
  
    const actions = useSelector(state => state.global.actions);   // 获取所有 actions
                                                                  // 使用 useSelector 可以获取所有 actions 的值
    dispatch(actions.login({                                      // 调用 action
        body: {},
      })).then(res => {
        const { success, data } = res.payload;                    // 从 payload 中获取数据
        /**
         * success: true,                                         // 请求是否成功
         * data: {}                                               // 请求返回的数据
         */
      });
  }
  

  除 dispatch(action()).then() 获取 action 的返回值外，还可以以一下方式获取：

  import { useDispatch, useSelector } from "react-redux";
  
  export default function login (){
    const dispatch = useDispatch();                                
    const actions = useSelector(state => state.global.actions);    
    dispatch(actions.login())
  
    // ...
  
    const { success, data, error, loading } = useSelector(state => state.user);   // state.user 是因为 action 定义了 reducerName = "user"          
                                                                                  // 返回值包括 success, data, error, loading 
  }
  

组件 components

• 定义：
  • 组件是一个 UI 逻辑的最小单位，通常专注于如何呈现内容（即外观）。
  • 无状态组件（Stateless Components）较常见，它们通常只接收 props，不直接管理状态。

容器 container

• 定义
  • 容器是负责 业务逻辑和数据管理 的组件，通常连接应用的状态（如 Redux store）并将数据传递给组件。
  • 容器通常管理状态、数据流、API 调用等复杂逻辑。

模块入口index.js

模块入口文件需暴露指定内容以便于Layout进行渲染

import route from './router'
import actions from './actions'

export default {
   route: route,
   actions: actions,
}

模块使用

模块内容需在 client/src/app.jsx 中引用并挂载至 Layout 组件

// ...
import Auth from "./sections/auth";
// ...
<Layout sections={[Auth]}/>

工具集 utils

工具集在 client/src/utils 目录下；

工具集内提供了一些常用的工具函数，如 api.js、parseProcessData.js 等。

• api.js：提供了 api 路由 map，可根据实际需求进行配置并多处使用；一般 action 中建议直接写入 api 路由，以方便管理。
• parseProcessData.js：提供了项企表单数据解析能力。
• index.js：工具集入口文件，暴露所有工具函数。
  • apiRequest: 在入口文件中暴露了 apiRequest 方法，适用于本项目的二次封装，用于请求数据，可根据实际需求进行配置。

构建

项目提供了 Docker 构建配置文件 Dockerfile 和 Jenkins 构建配置文件 jenkinsfile，根据实际需求进行修改配置。

核心包 @peace/react_client

核心包除提供封装的核心内容外，还暴露了一些常用功能：

request

基于 superagent 封装的请求方法，使用方式上更接近直觉；

class 构造，使用前需实例化

• 实例化

  import { message } from 'antd'
  import { request } from "@peace/react_client";
  
  const apiRequest = new request({
    proxy: '/_api',                        // 代理前缀 与 `config.cjs` 中的 `proxy` 保持一致 才可生效
    userKey: 'user',                       // session 中的用户键值，用于拼接 token，默认为 `user`，session中没有也不影响使用
    message: message,                      // 全局提示组件，用于提示请求结果（如果需要）
    interceptor: (res, err) => {           // 拦截器，用于处理请求结果，两参数互斥出现
        if (err) {
          if (err?.status === 401) {
              window.location.replace('/signin');
              sessionStorage.clear()
          }
          return err
        }
        return res
    }
  })
  

• 使用

  apiRequest[method](route,{
    body: {},                             // 请求体
    query: {},                            // 请求参数
    params: {},                           // 请求路径参数
    header: {},                           // 请求头
    timeout: 3000,                        // 超时时间
    tipSuccess:'',                           // 成功提示                       
    tipFail:'',                              // 失败提示                 
    tip:'',                                  // 提示(成功 & 失败)
  }).then(res => {
    const { success, data } = res;        // 请求结果
  })
  

Redux 相关

basicAction

构造 action 的主要工具，可直接使用，无需编写 reducer；可参考目录 'Redux actions'；

basicReducer

聚合项目中所有的 action，统一生成匹配 reducer [redux 切片]的工具；

createSlice

创建一个 redux 切片（reducer）；

导出自 @reduxjs/toolkit，Redux 官方包；

createStore

创建一个 redux store；

导出自 @reduxjs/toolkit，Redux 官方包；

目录结构

├── .vscode                            // vscode 相关配置
|   ├── launch.json                    // 启动命令配置，包含环境变量
|   └── settings.json
├── client
│   ├── assets                         // 静态资源文件夹
│   ├── entry                          // 服务渲染入口
│   ├── src                            // 源码
│   │   ├── components                 // 公共组件
│   │   |   ├── errorBoundary.jsx      // [预置]错误拦截组件
│   │   |   ├── index.js               // 入口文件
│   │   |   └── upload.jsx             // [预置]上传组件
│   │   ├── layout                     // 布局
│   │   |   ├── components             // 布局组件
│   │   |   ├── container              // 容器
│   │   |   ├── middleWare             // 
│   │   |   └── index.jsx              // 入口文件
│   │   ├── sections                   // [!]功能模块
│   │   |   └── auth                   // 认证模块  
│   │   |       ├── actions            // Redux actions
│   │   |       ├── components         // 组件
│   │   |       ├── container          // 容器
│   │   |       ├── index.js           // 模块入口文件
│   │   |       └── router.js          // [!]路由文件
│   │   ├── utils                      // 工具集
│   │   |   ├── api.js                 // api 路由 map
│   │   |   ├── index.js               // 入口文件
│   │   |   └── parseProcessData.js    // [预置]项企表单数据解析
│   │   ├── app.js                     // 次级入口
│   │   └── app.less                   // 全局样式
│   └── index.js                       // 项目入口
├── server                             // ssr 服务端
│   ├── controllers                    // 控制器             
│   ├── index.js                       // 入口文件
│   └── routes.js                      // 路由文件
├── .editorconfig                      // 代码风格配置
├── .gitignore                         // git 忽略配置
├── .npmrc                             // npm 配置
├── config.cjs                         // 项目配置
├── Dockerfile                         // Docker 构建配置
├── index.html                         // 模板文件
├── jenkinsfile                        // Jenkins 构建配置
├── package.json                          
├── README.md                          // 项目说明