# 數據 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 就配置完成了。線上與本地差異不大,比較大的區別是線上在控制臺內看不到接口請求日志。
- 項目介紹
- 常見問題
- 開發環境準備
- 環境準備
- 啟動項目
- 切換Vue3路由
- 項目配置詳細說明
- 上線部署
- 快速構建&部署
- Docker鏡像啟動
- 項目配置
- 菜單配置
- 菜單緩存
- 積木報表菜單配置
- 首頁配置
- 國際化
- 菜單國際化
- 組件注冊
- 項目規范
- 跨域處理
- 樣式庫
- 圖標生成
- package依賴介紹
- 菜單TAB風格
- 備份文檔
- 詳細構建和配置
- 構建部署1.0
- 切換Mock接口
- 原生路由(作廢)
- 原生菜單(作廢)
- 頁面開啟緩存(作廢)
- 環境準備1.0
- 數據 mock&聯調
- UI組件
- Form 表單組件
- Table 表格
- Modal 彈窗
- Drawer 抽屜組件
- Icon 圖標組件
- Button 按鈕
- 更多基礎組件
- JSelectUser選擇用戶 ?
- JSelectPosition崗位選擇 ?
- JSelectDept部門選擇 ?
- JCheckbox ?
- JImportModal 列表導入彈窗組件
- JInput特殊查詢組件 ?
- JPopup彈窗選擇組件 ?
- JTreeSelect樹形下拉框 (異步加載) ?
- JAreaSelect 省市縣級聯組件
- JDictSelectTag 字典標簽 ?
- JEllipsis 超長截取顯示組件 ?
- JUpload 上傳組件 ?
- JEasyCron 定時表達式選擇組件 ?
- JInputPopup 多行輸入窗口組件 ?
- JSwitch 開關選擇組件 ?
- JTreeDict 分類字典樹形下拉組件 ?
- JSelectInput 可輸入下拉框 ?
- JEditor 富文本編輯器 ?
- JMarkdownEditor Markdown編輯器 ?
- JSearchSelect 字典表的搜索組件 ?
- JSelectUserByDept 根據部門選擇用戶 ?
- JVxeTable
- 組件配置文檔
- 自定義組件
- 封裝自定義組件
- 自定義組件增強
- 多級聯動配置
- 使用示例
- 常見問題解答
- JAreaLinkage 省市縣聯動組件 ?
- JCategorySelect 分類字典樹 ?
- JImageUpload 圖片上傳 ?
- JSelectMultiple 下拉多選 ?
- JSelectRole 選擇角色 ?
- JFormContainer 表單組件禁用 ?
- SuperQuery 高級查詢
- UserSelect 高級用戶選擇組件
- Basic
- Page
- Authority
- PopConfirmButton
- CollapseContainer
- ScrollContainer
- LazyContainer
- CodeEditor
- JsonPreview
- CountDown
- ClickOutSide
- CountTo
- Cropper
- Description
- FlowChart
- Upload
- Tree
- Excel
- Qrcode
- Markdown
- Loading
- Tinymce
- Time
- StrengthMeter
- Verify
- Transition
- VirtualScroll
- ContextMenu
- Preview
- Loading
- 前端權限
- 表單權限
- 顯隱控制 ?
- 禁用控制 ?
- 列表權限
- 按鈕權限控制
- 列字段顯隱控制
- 行編輯組件權限
- 顯隱控制
- 禁用控制
- 代碼生成
- Online在線代碼生成
- GUI代碼生成
- 代碼生成模板介紹
- vue3和vue3Native詳細說明
- 深入開發
- 定義Form新組件
- 自定義列表查詢
- 自定義表單布局
- 開發筆記
- 組件權限控制
- 使用Antd Vue原生Form
- 自定義圖表組件
- 自定義渲染函數
- 如何編寫mock接口
- 緩存用法
- 精簡版代碼制作
- 微前端(qiankun)集成
- 前端小技巧
- 表單整體禁用
- 彈框內下拉框錯位
- 界面如何設置響應式
- 抽屜(Drawer)寬度自適應
- 生成菜單腳本
- Online表單
- Online常見問題
- Online表單配置
- 配置參數說明
- 系統標準字段
- 表單類型-主子表|樹表
- 自定義查詢配置
- Online表單風格
- Online表單刪除說明
- Online聯合查詢配置
- online表單視圖功能說明
- Online表單開啟評論
- Online表單控件介紹
- 常用基礎控件
- 高級關聯記錄
- Online表單控件配置
- 基本配置
- 控件擴展配置
- 默認值表達式
- 自定義查詢配置
- 字段href
- 默認值(填值規則)
- 導入導出自定義規則
- Online表單權限配置
- 字段權限配置與授權
- 按鈕權限配置與授權
- 數據權限配置與授權
- 聯合查詢數據權限規則說明
- 在線增強
- 自定義按鈕
- SQL增強
- JS增強
- 按鈕觸發JS增強
- 列表Api
- 列表操作列前置事件
- 表單Api
- beforeSubmit事件
- loaded事件
- 表單值改變事件【單表/主表】
- 表單值改變事件【從表】
- 表單值改變事件【從改主】
- 控制字段顯示與隱藏
- js增強實現下拉聯動
- js增強控制下拉樹數據
- JS增強 觸發彈窗
- JS增強 http請求
- JS增強 方法定義
- 對接表單設計器后需注意
- JAVA增強
- 快速開始
- Online java增強 導入
- Online java增強 導出
- Online java增強 查詢
- Online Java增強 http-api
- 表單類
- 列表類
- 其他功能示例
- 導入數據庫表支持排除表
- 通過字段Href實現三級聯動
- excel數據導入支持校驗
- Online報表
- Online報表配置
- 配置成菜單
- 其他功能
- 推送消息
- ISO 8601書寫格式
- 系統消息跳轉至詳情表單
- 菜單【批量申請(自定義)】功能說明
- Online自動化測試
- online AI自動化測試數據制作
- Online AI自動化測試數據制作
- Online AI模型測試用例功能詳情
- JAVA后臺功能
- saas多租戶切換
- 新功能實現saas租戶隔離
- 第三方集成
- 敲敲云集成釘釘