Stooland Docs

Appearance

Vue前端API集成规范 ​

本文档定义前端调用后端API的标准流程、响应处理和注意事项

一、Request封装机制 ​

1.1 核心文件 ​

位置：web/src/api/base/request.js

1.2 Axios配置 ​

javascript
const instance = axios.create({
  baseURL: import.meta.env.VITE_BASE_API,  // ⚠️ 使用 import.meta.env
  timeout: 1200000,
  withCredentials: true
})

1.3 请求拦截器 ​

javascript
instance.interceptors.request.use(config => {
    // 自动注入Token
    config.headers['token'] = getToken()
    config.headers['Authorization'] = `Bearer ${token}`
    config.headers['client-type'] = CLIENT_TYPE_WEB
    
    // 签名
    config.headers['requesttimestamp'] = timeStamp
    config.headers['sign'] = Rsa(timeStamp)
    
    return config
})

1.4 响应拦截器（⚠️ 关键） ​

javascript
instance.interceptors.response.use(response => {
    const res = response.data
    
    // 错误检查
    if (hasError(res)) {
        return Promise.reject(error)
    }
    
    // ⚠️ 自动返回 responseData，不是完整响应
    return res.responseData
})

二、API方法定义规范 ​

2.1 文件位置 ​

路径：web/src/api/xxx.js

2.2 GET请求 ​

javascript
import request from '@/api/base/request'

/**
 * 获取批次列表
 * @param {Object} params - { page: number, page_size: number, status: string }
 */
export function getBatchList(params) {
  return request({
    url: '/common/midjourney/batch/list',
    method: 'get',
    params  // query参数
  })
}

2.3 POST请求 ​

javascript
/**
 * 删除批次
 * @param {Object} data - { batch_id: string }
 */
export function deleteBatch(data) {
  return request({
    url: '/common/midjourney/batch/delete',
    method: 'post',
    data    // body参数
  })
}

三、Vue组件调用规范 ​

3.1 导入API方法 ​

javascript
import { getBatchList, deleteBatch } from '@/api/midjourney.js'

3.2 调用示例 ​

javascript
// ✅ 正确：直接获取responseData
const list = await getBatchList({ page: 1, page_size: 20 })
console.log(list)  // 直接是业务数据

// ❌ 错误：多层访问
const data = response.data.responseData  // 错误！
const data = response.responseData       // 错误！

3.3 错误处理 ​

javascript
try {
  const result = await apiMethod()
  // 成功处理
} catch (error) {
  // 拦截器已统一处理错误
  console.error('操作失败', error)
}

四、关键机制详解 ​

4.1 响应数据自动解包 ​

后端返回:

json
{
  "responseHeader": {
    "returnCode": 0,
    "message": "操作成功"
  },
  "responseData": {
    "list": [...],
    "total": 100
  }
}

前端接收:

javascript
const data = await apiMethod()
// data = { list: [...], total: 100 }
// ⚠️ 已自动提取 responseData 内容

4.2 HTTPS自动升级 ​

在HTTPS页面下，响应中的 http:// 链接自动升级为 https://

javascript
// HTTPS页面下
res.responseData = upgradeUrlsDeep(res.responseData)

五、环境变量规范 ​

5.1 Vite环境变量访问 ​

javascript
// ❌ 错误：Vite不支持 process.env
process.env.VITE_BASE_API

// ✅ 正确：必须使用 import.meta.env
import.meta.env.VITE_BASE_API

5.2 常用环境变量 ​

变量名说明示例
VITE_BASE_API后端API地址http://localhost/api
VITE_QINIU_IMAGE_HOST七牛图片域名https://img.example.com

5.3 配置文件位置 ​

  • .env.development - 开发环境
  • .env.production - 生产环境

六、路径别名配置 ​

6.1 Vite配置 ​

javascript
// vite.config.ts
resolve: {
  alias: {
    '@': path.resolve(__dirname, 'src')
  }
}

6.2 使用示例 ​

javascript
// ✅ 使用别名
import request from '@/api/base/request'
import { getBatchList } from '@/api/midjourney.js'

// 实际路径
// @/api/xxx → web/src/api/xxx

七、命名约定 ​

类型规范示例
API方法camelCasegetBatchList, deleteBatch
Vue组件PascalCaseMidjourneyTool.vue
变量/函数camelCaseuploadFileList, handleSubmit
常量UPPER_SNAKE_CASECLIENT_TYPE_WEB

八、常见错误 ​

❌ 错误1：重复解析响应 ​

javascript
// 错误
const data = response.data.responseData

✅ 正确 ​

javascript
const data = await apiMethod()  // 已自动解包

❌ 错误2：使用 process.env ​

javascript
// 错误
const apiUrl = process.env.VITE_BASE_API

✅ 正确 ​

javascript
const apiUrl = import.meta.env.VITE_BASE_API

❌ 错误3：手动检查 returnCode ​

javascript
// 不需要
if (response.returnCode === 0) { ... }

✅ 正确 ​

javascript
// 拦截器已处理，成功直接获取数据，失败自动reject
const data = await apiMethod()

九、示例参考 ​

9.1 完整API文件 ​

参考：web/src/api/midjourney.js

9.2 Vue组件调用 ​

参考：web/src/views/tool/MidjourneyTool.vue

十、Element Plus 组件 API 规范 ​

10.1 Button 组件 ​

type 属性（v3.0.0 废弃 text） ​

vue
<!-- ❌ 错误：v3.0.0 中废弃 -->
<el-button type="text">按钮</el-button>

<!-- ✅ 正确：使用 link -->
<el-button link>按钮</el-button>

警告示例:

ElementPlusError: [props] [API] type.text is about to be deprecated in version 3.0.0, please use link instead.

size 属性 ​

合法值："", "default", "small", "large"

vue
<!-- ❌ 错误 -->
<el-button size="mini">按钮</el-button>

<!-- ✅ 正确 -->
<el-button size="small">按钮</el-button>

10.2 Tag 组件 ​

size 属性 ​

合法值："", "default", "small", "large"

vue
<!-- ❌ 错误：mini 已废弃 -->
<el-tag size="mini">标签</el-tag>

<!-- ✅ 正确 -->
<el-tag size="small">标签</el-tag>

警告示例:

Invalid prop: validation failed for prop "size". 
Expected one of ["", "default", "small", "large"], got value "mini".

10.3 Radio 组件 ​

label vs value（v3.0.0 调整） ​

vue
<!-- ❌ 错误：label 作为 value 将废弃 -->
<el-radio-group v-model="selected">
  <el-radio :label="true">选项A</el-radio>
  <el-radio :label="false">选项B</el-radio>
</el-radio-group>

<!-- ✅ 正确：使用 value 属性 -->
<el-radio-group v-model="selected">
  <el-radio :value="true">选项A</el-radio>
  <el-radio :value="false">选项B</el-radio>
</el-radio-group>

警告示例:

ElementPlusError: [el-radio] [API] label act as value is about to be deprecated in version 3.0.0, please use value instead.

10.4 迁移检查清单 ​

升级到 Element Plus v3 前，全局搜索：

bash
# 搜索 type="text"
grep -r 'type="text"' web/src

# 搜索 size="mini"
grep -r 'size="mini"' web/src

# 搜索 :label=
grep -r ':label=' web/src/components

10.5 参考文档 ​

文档维护: 修改本文档后，建议同步更新AI Memory以保持一致性