數據 mock&聯調 · JeecgBoot Vue3前端文檔

# 數據 mock&聯調 [TOC] ## 開發環境如果前端應用和后端接口服務器沒有運行在同一個主機上，你需要在開發環境下將接口請求代理到接口服務器。如果是同一個主機，可以直接請求具體的接口地址。 ### 配置開發環境時候，接口地址在項目根目錄下 [.env.development](https://github.com/vbenjs/vue-vben-admin/tree/main/.env.development) 文件配置 ```bash # vite 本地跨域代理 VITE_PROXY=[["/basic-api","http://localhost:3000"]] # 接口地址 VITE_GLOB_API_URL=/api ``` ::: tip - .env 文件中的字段如果是字符串，則無需加引號，默認全部為字符串 - VITE_PROXY 不能換行 ::: ### 跨域處理如果你在 `src/api/` 下面的接口為下方代碼，且 **.env.development** 文件配置如下注釋，則在控制臺看到的地址為 `http://localhost:3100/basic-api/login`。由于 `/basic-api` 匹配到了設置的 `VITE_PROXY`，所以上方實際是請求 **http://localhost:3000/login**，這樣同時也解決了跨域問題。（**3100**為項目端口號，**http://localhost:3000**為PROXY代理的目標地址） ```ts // .env.development // VITE_PROXY=[["/basic-api","http://localhost:3000"]] // VITE_GLOB_API_URL=/basic-api enum Api { Login = '/login', } /** * @description: 用戶登陸 */ export function loginApi(params: LoginParams) { return http.request<LoginResultModel>({ url: Api.Login, method: 'POST', params, }); } ``` ### 沒有跨域時的配置如果沒有跨域問題，可以直接忽略 **VITE_PROXY** 配置，直接將接口地址設置在 **VITE_GLOB_API_URL** ```bash # 例如接口地址為 http://localhost:3000 則 VITE_GLOB_API_URL=http://localhost:3000 ``` 如果有跨域問題，將 **VITE_GLOB_API_URL** 設置為跟 **VITE_PROXY** 內其中一個數組的第一個項一致的值即可。下方的接口地址設置為 `/basic-api`，當請求發出的時候會經過 Vite 的 proxy 代理，匹配到了我們設置的 **VITE_PROXY** 規則，將 `/basic-api` 轉化為 `http://localhost:3000` 進行請求 ```bash # 例如接口地址為 http://localhost:3000 則 VITE_PROXY=[["/basic-api","http://localhost:3000"]] # 接口地址 VITE_GLOB_API_URL=/basic-api ``` ### 跨域原理解析在 `vite.config.ts` 配置文件中，提供了 server 的 proxy 功能，用于代理 API 請求。 ```ts server: { proxy: { "/basic-api":{ target: 'http://localhost:3000', changeOrigin: true, ws: true, rewrite: (path) => path.replace(new RegExp(`^/basic-api`), ''), } }, }, ``` ::: tip 注意從瀏覽器控制臺的 Network 看，請求是 `http://localhost:3000/basic-api/xxx`，這是因為 proxy 配置不會改變本地請求的 url。 ::: ## 生產環境生產環境接口地址在項目根目錄下 [.env.production](https://github.com/vbenjs/vue-vben-admin/tree/main/.env.production) 文件配置。生產環境接口地址值需要修改 **VITE_GLOB_API_URL**，如果出現跨域問題，可以使用 nginx 或者后臺開啟 cors 進行處理 ::: tip 打包后如何進行地址修改? **VITE_GLOB\_\*** 開頭的變量會在打包的時候注入 **\_app.config.js** 文件內。在 **dist/\_app.config.js** 修改相應的接口地址后刷新頁面即可，不需要在根據不同環境打包多次，一次打包可以用于多個不同接口環境的部署。 ::: ## 接口請求在 vue-vben-admin 中: 1. 頁面交互操作； 2. 調用統一管理的 api 請求函數； 3. 使用封裝的 axios.ts 發送請求； 4. 獲取服務端返回數據 5. 更新 data；接口統一存放于 [src/api/](https://github.com/vbenjs/vue-vben-admin/tree/main/src/api) 下面管理以登陸接口為例: 在 **src/api/** 內新建模塊文件，其中參數與返回值最好定義一下類型，方便校驗。雖然麻煩，但是后續維護字段很方便。 ::: tip 類型定義文件可以抽取出去統一管理，具體參考項目 ::: ```ts import { defHttp } from '/@/utils/http/axios'; import { LoginParams, LoginResultModel } from './model/userModel'; enum Api { Login = '/login', } export function loginApi(params: LoginParams) { return defHttp.request<LoginResultModel>({ url: Api.Login, method: 'POST', params, }); } ``` ## axios 配置 **axios** 請求封裝存放于 [src/utils/http/axios](https://github.com/vbenjs/vue-vben-admin/tree/main/src/utils/http/axios) 文件夾內部除 `index.ts` 文件內容需要根據項目自行修改外，其余文件無需修改 ```js ├── Axios.ts // axios實例 ├── axiosCancel.ts // axiosCancel實例，取消重復請求 ├── axiosTransform.ts // 數據轉換類 ├── checkStatus.ts // 返回狀態值校驗 ├── index.ts // 接口返回統一處理 ``` ### index.ts 配置說明 ```ts const axios = new VAxios({ // 認證方案，例如: Bearer // https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#authentication_schemes authenticationScheme: '', // 接口超時時間單位毫秒 timeout: 10 * 1000, // 接口可能會有通用的地址部分，可以統一抽取出來 prefixUrl: prefix, headers: { 'Content-Type': ContentTypeEnum.JSON }, // 數據處理方式，見下方說明 transform, // 配置項，下面的選項都可以在獨立的接口請求中覆蓋 requestOptions: { // 默認將prefix 添加到url joinPrefix: true, // 是否返回原生響應頭比如：需要獲取響應頭時使用該屬性 isReturnNativeResponse: false, // 需要對返回數據進行處理 isTransformRequestResult: true, // post請求的時候添加參數到url joinParamsToUrl: false, // 格式化提交參數時間 formatDate: true, // 消息提示類型 errorMessageMode: 'message', // 接口地址 apiUrl: globSetting.apiUrl, // 是否加入時間戳 joinTime: true, // 忽略重復請求 ignoreCancelToken: true, }, }); ``` **transform 數據處理說明** 類型定義，見 **axiosTransform.ts** 文件 ```js export abstract class AxiosTransform { /** * @description: 請求之前處理配置 */ beforeRequestHook?: (config: AxiosRequestConfig, options: RequestOptions) => AxiosRequestConfig; /** * @description: 請求成功處理 */ transformRequestData?: (res: AxiosResponse<Result>, options: RequestOptions) => any; /** * @description: 請求失敗處理 */ requestCatch?: (e: Error) => Promise<any>; /** * @description: 請求之前的攔截器 */ requestInterceptors?: (config: AxiosRequestConfig) => AxiosRequestConfig; /** * @description: 請求之后的攔截器 */ responseInterceptors?: (res: AxiosResponse<any>) => AxiosResponse<any>; /** * @description: 請求之前的攔截器錯誤處理 */ requestInterceptorsCatch?: (error: Error) => void; /** * @description: 請求之后的攔截器錯誤處理 */ responseInterceptorsCatch?: (error: Error) => void; } ``` 項目默認 transform 處理邏輯，可以根據各自項目進行處理。一般需要更改的部分為下方代碼，見代碼注釋說明 ```js /** * @description: 數據處理，方便區分多種處理方式 */ const transform: AxiosTransform = { /** * @description: 處理請求數據。如果數據不是預期格式，可直接拋出錯誤 */ transformRequestHook: (res: AxiosResponse<Result>, options: RequestOptions) => { const { t } = useI18n(); const { isTransformResponse, isReturnNativeResponse } = options; // 是否返回原生響應頭比如：需要獲取響應頭時使用該屬性 if (isReturnNativeResponse) { return res; } // 不進行任何處理，直接返回 // 用于頁面代碼可能需要直接獲取code，data，message這些信息時開啟 if (!isTransformResponse) { return res.data; } // 錯誤的時候返回 const { data } = res; if (!data) { // return '[HTTP] Request has no return value'; throw new Error(t('sys.api.apiRequestFailed')); } // 這里 code，result，message為后臺統一的字段，需要在 types.ts內修改為項目自己的接口返回格式 const { code, result, message } = data; // 這里邏輯可以根據項目進行修改 const hasSuccess = data && Reflect.has(data, 'code') && code === ResultEnum.SUCCESS; if (hasSuccess) { return result; } // 在此處根據自己項目的實際情況對不同的code執行不同的操作 // 如果不希望中斷當前請求，請return數據，否則直接拋出異常即可 let timeoutMsg = ''; switch (code) { case ResultEnum.TIMEOUT: timeoutMsg = t('sys.api.timeoutMessage'); default: if (message) { timeoutMsg = message; } } // errorMessageMode=‘modal’的時候會顯示modal錯誤彈窗，而不是消息提示，用于一些比較重要的錯誤 // errorMessageMode='none' 一般是調用時明確表示不希望自動彈出錯誤提示 if (options.errorMessageMode === 'modal') { createErrorModal({ title: t('sys.api.errorTip'), content: timeoutMsg }); } else if (options.errorMessageMode === 'message') { createMessage.error(timeoutMsg); } throw new Error(timeoutMsg || t('sys.api.apiRequestFailed')); }, // 請求之前處理config beforeRequestHook: (config, options) => { const { apiUrl, joinPrefix, joinParamsToUrl, formatDate, joinTime = true } = options; if (joinPrefix) { config.url = `${urlPrefix}${config.url}`; } if (apiUrl && isString(apiUrl)) { config.url = `${apiUrl}${config.url}`; } const params = config.params || {}; if (config.method?.toUpperCase() === RequestEnum.GET) { if (!isString(params)) { // 給 get 請求加上時間戳參數，避免從緩存中拿數據。 config.params = Object.assign(params || {}, joinTimestamp(joinTime, false)); } else { // 兼容restful風格 config.url = config.url + params + `${joinTimestamp(joinTime, true)}`; config.params = undefined; } } else { if (!isString(params)) { formatDate && formatRequestDate(params); config.data = params; config.params = undefined; if (joinParamsToUrl) { config.url = setObjToUrlParams(config.url as string, config.data); } } else { // 兼容restful風格 config.url = config.url + params; config.params = undefined; } } return config; }, /** * @description: 請求攔截器處理 */ requestInterceptors: (config, options) => { // 請求之前處理config const token = getToken(); if (token) { // jwt token config.headers.Authorization = options.authenticationScheme ? `${options.authenticationScheme} ${token}` : token; } return config; }, /** * @description: 響應攔截器處理 */ responseInterceptors: (res: AxiosResponse<any>) => { return res; }, /** * @description: 響應錯誤處理 */ responseInterceptorsCatch: (error: any) => { const { t } = useI18n(); const errorLogStore = useErrorLogStoreWithOut(); errorLogStore.addAjaxErrorInfo(error); const { response, code, message, config } = error || {}; const errorMessageMode = config?.requestOptions?.errorMessageMode || 'none'; const msg: string = response?.data?.error?.message ?? ''; const err: string = error?.toString?.() ?? ''; let errMessage = ''; try { if (code === 'ECONNABORTED' && message.indexOf('timeout') !== -1) { errMessage = t('sys.api.apiTimeoutMessage'); } if (err?.includes('Network Error')) { errMessage = t('sys.api.networkExceptionMsg'); } if (errMessage) { if (errorMessageMode === 'modal') { createErrorModal({ title: t('sys.api.errorTip'), content: errMessage }); } else if (errorMessageMode === 'message') { createMessage.error(errMessage); } return Promise.reject(error); } } catch (error) { throw new Error(error); } checkStatus(error?.response?.status, msg, errorMessageMode); return Promise.reject(error); }, }; ``` ### 更改參數格式項目接口默認為 Json 參數格式，即 `headers: { 'Content-Type': ContentTypeEnum.JSON }`, 如果需要更改為 `form-data` 格式，更改 headers 的 `'Content-Type` 為 `ContentTypeEnum.FORM_URLENCODED` 即可 ### 多個接口地址當項目中需要用到多個接口地址時, 可以在 [src/utils/http/axios/index.ts](https://github.com/vbenjs/vue-vben-admin/tree/main/src/utils/http/axios/index.ts) 導出多個 axios 實例 ```ts // 目前只導出一個默認實例，接口地址對應的是環境變量中的 VITE_GLOB_API_URL 接口地址 export const defHttp = createAxios(); // 需要有其他接口地址的可以在后面添加 // other api url export const otherHttp = createAxios({ requestOptions: { apiUrl: 'xxx', }, }); ``` ### 刪除請求 URL 攜帶的時間戳參數如果不需要 url 上面默認攜帶的時間戳參數 `?_t=xxx` ```ts const axios = new VAxios({ requestOptions: { // 是否加入時間戳 joinTime: false, }, }); ``` ## Mock 服務 Mock 數據是前端開發過程中必不可少的一環，是分離前后端開發的關鍵鏈路。通過預先跟服務器端約定好的接口，模擬請求數據甚至邏輯，能夠讓前端開發獨立自主，不會被服務端的開發進程所阻塞。本項目使用 [vite-plugin-mock](https://github.com/vbenjs/vite-plugin-mock) 來進行 mock 數據處理。**項目內 mock 服務分本地和線上**。 ### 本地 Mock 本地 mock 采用 Node.js 中間件進行參數攔截（不采用 mock.js 的原因是本地開發看不到請求參數和響應結果）。 #### 如何新增 mock 接口如果你想添加 mock 數據，只要在根目錄下找到 mock 文件，添加對應的接口，對其進行攔截和模擬數據。在 mock 文件夾內新建文件 ::: tip 文件新增后會自動更新，不需要手動重啟，可以在代碼控制臺查看日志信息 mock 文件夾內會自動注冊，排除以\_開頭的文件夾及文件 ::: 例: ```ts import { MockMethod } from 'vite-plugin-mock'; import { resultPageSuccess } from '../_util'; const demoList = (() => { const result: any[] = []; for (let index = 0; index < 60; index++) { result.push({ id: `${index}`, beginTime: '@datetime', endTime: '@datetime', address: '@city()', name: '@cname()', 'no|100000-10000000': 100000, 'status|1': ['正常', '啟用', '停用'], }); } return result; })(); export default [ { url: '/api/table/getDemoList', timeout: 1000, method: 'get', response: ({ query }) => { const { page = 1, pageSize = 20 } = query; return resultPageSuccess(page, pageSize, demoList); }, }, ] as MockMethod[]; ``` ::: tip mock 的值可以直接使用 [mockjs](https://github.com/nuysoft/Mock/wiki) 的語法。 ::: #### 接口格式 ```ts { url: string; // mock 接口地址 method?: MethodType; // 請求方式 timeout?: number; // 延時時間 statusCode: number; // 響應狀態碼 response: ((opt: { // 響應結果 body: any; query: any; }) => any) | object; } ``` #### 參數獲取 **GET 接口：**` ({ query }) => { }` **POST 接口：**` ({ body }) => { }` #### util 說明可在 [代碼](https://github.com/vbenjs/vue-vben-admin/tree/main/mock/_util.ts) 中查看 ::: tip util 只作為服務處理結果數據使用。可以不用，如需使用可自行封裝，需要將對應的字段改為接口的返回結構 ::: #### 匹配在 `src/api` 下面，如果接口匹配到 mock，則會優先使用 mock 進行響應 ```ts import { defHttp } from '/@/utils/http/axios'; import { LoginParams, LoginResultModel } from './model/userModel'; enum Api { Login = '/login', } /** * @description: user login api */ export function loginApi(params: LoginParams) { return defHttp.request<LoginResultModel>( { url: Api.Login, method: 'POST', params, }, { errorMessageMode: 'modal', } ); } // 會匹配到上方的 export default [ { url: '/api/login', timeout: 1000, method: 'POST', response: ({ body }) => { return resultPageSuccess({}); }, }, ] as MockMethod[]; ``` #### 接口有了，如何去掉 mock 當后臺接口已經開發完成，只需要將相應的 mock 函數去掉即可。以上方接口為例，假如后臺接口 login 已經開發完成，則只需要刪除/注釋掉下方代碼即可 ```ts export default [ { url: '/api/login', timeout: 1000, method: 'POST', response: ({ body }) => { return resultPageSuccess({}); }, }, ] as MockMethod[]; ``` ### 線上 mock 由于該項目是一個展示類項目，線上也是用 mock 數據，所以在打包后同時也集成了 mock。通常項目線上一般為正式接口。項目線上 mock 采用的是 [mockjs](https://github.com/nuysoft/Mock/wiki) 進行 mock 數據模擬。 #### 線上如何開啟 mock ::: warning 注意線上開啟 mock 只適用于一些簡單的示例網站及預覽網站。**一定不要在正式的生產環境開啟！！！** ::: 1. 修改 .env.production 文件內的 `VITE_USE_MOCK` 的值為 true ```ts VITE_USE_MOCK = true; ``` 2. 在 [mock/\_createProductionServer.ts](https://github.com/vbenjs/vue-vben-admin/tree/main/mock/_createProductionServer.ts) 文件中引入需要的 mock 文件 ```ts import { createProdMockServer } from 'vite-plugin-mock/es/createProdMockServer'; const modules = import.meta.globEager('./**/*.ts'); const mockModules: any[] = []; Object.keys(modules).forEach((key) => { if (key.includes('/_')) { return; } mockModules.push(...modules[key].default); }); export function setupProdMockServer() { createProdMockServer(mockModules); } ``` 3. 在 [build/vite/plugin/mock.ts](https://github.com/vbenjs/vue-vben-admin/tree/main/build/vite/plugin/mock.ts) 里面引入 ```ts import { viteMockServe } from 'vite-plugin-mock'; export function configMockPlugin(isBuild: boolean) { return viteMockServe({ injectCode: ` import { setupProdMockServer } from '../mock/_createProductionServer'; setupProdMockServer(); `, }); } ``` ::: tip 為什么通過插件注入代碼而不是直接在 main.ts 內插入在插件內通過 `injectCode` 插入代碼，方便控制 mockjs 是否被打包到最終代碼內。如果在 main.ts 內判斷，如果關閉了 mock 功能，mockjs 也會打包到構建文件內，這樣會增加打包體積。 ::: 到這里線上 mock 就配置完成了。線上與本地差異不大，比較大的區別是線上在控制臺內看不到接口請求日志。