# 接口配置和使用

本框架接口配置存放于 src/api 目录，目前已存在 meter.js、article.js 等示例接口文件，供开发者参考。

TIP

每个接口文件表示按类别或模块组织的接口集合。

# 一个标准的接口文件

import request from '@/utils/request'
// 引入默认接口服务配置
const { default: host } = require('./host.js')

// 接口方法 getMeterList
export function getMeterList (query) {
  return request({
    // 接口名 meter/list
    url: host + '/meter/list',
    method: 'get',
    params: query
  })
}

// 其他接口方法
// …

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

request是对异步请求库 axios (opens new window) 的封装，设置了拦截器，开发者暂不需要了解。

上例中，包含 request、host 和接口方法三个方面。一般情况下不需要配置 request。

# 全局接口服务配置

public/config/host.js 是生产环境下全局接口配置文件。

$host = {
  // 默认接口服务
  default: 'http://localhost:3000/abc-api',
  // 其他接口服务，接口名可自定义
  otherOne: 'http://localhost:3000/def-api'

  // 还可以配置更多其他接口服务
  // …
}

1
2
3
4
5
6
7
8
9

src/api/host.js 是开发演示环境下全局接口配置文件。

const host = {
  // 开发环境
  development: {
    // 默认接口服务
    default: '/mock',
    // 其他接口服务，接口名可自定义
    otherOne: '/mock'

    // 同生产环境的 host.js 一样，还可以配置更多其他接口服务
    // …
  },
  // 演示环境
  staging: {
    // 默认接口服务
    default: '/mock',
    // 其他接口服务，接口名可自定义
    otherOne: '/mock'

    // 同生产环境的 host.js 一样，还可以配置更多其他接口服务
    // …
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 引入服务接口地址

开发者可以根据需要灵活地引入配置好的接口服务地址。

// 引入默认接口服务配置
const { default: host } = require('./host.js')
console.info(host)

1
2
3

// 引入其他接口服务配置
const { otherOne: host1 } = require('./host.js')
console.info(host1)

const { otherTwo: host2 } = require('./host.js')
console.info(host2)

1
2
3
4
5
6

// 全部引入
const host = require('./host.js')
console.info(host.default)
console.info(host.otherOne)

1
2
3
4

# Mock 服务

Mock Server

你可能已经注意到 src/api/host.js 配置中，development 属性的值为 /mock, 它指向了该框架内置的 Mock Server，其将同本框架开发调试环境一同启动。

Mock Server 用于模拟服务器响应，位于 mock 目录，包含了 mock 服务配置、模拟接口等文件。你可以参考现有的模拟接口文件 meter-demo.js、article.js 等，新建需要的模拟接口。

在 src/api/article.js 等接口配置文件中，你可能会注意到有的接口名写为 /mock/article/list，即包含 /mock 前缀，这表示该接口不依赖 host.js 配置的接口服务，而是直接指向 Mock Server。

Mock Server 文档参考：

vue-element-admin 中关于 MockServer 的说明 (opens new window) | mockjs 官方文档 (opens new window)

# 创建一个接口方法

一个典型的 get 类型接口方法如下

export function getMeterList (params) {
  // 如果有需要，开发者可以在请求发出前对 params 进行二次加工
  // params 二次加工…
  // 发出请求并返回一个 Promise
  return request({
    url: host + '/meter/list',
    method: 'get',
    params
  })
}

1
2
3
4
5
6
7
8
9
10

一个典型的 post 类型接口方法

export function createArticle (data) {
  // 如果有需要，开发者可以在请求发出前对 data 进行二次加工
  // data 二次加工…
  // 发出请求并返回一个 Promise
  return request({
    url: '/mock/article/create',
    method: 'post',
    data
  })
}

1
2
3
4
5
6
7
8
9
10

接口方法必须使用 export 关键字进行抛出。

TIP

就像上述几个例子中那样，接口方法的名称应该能够见名知意。

接口请求配置属性列表

属性名	属性说明	默认值
url	[String] 接口地址，可以是相对路径或绝对路径	无
method	[String] 请求时使用的方法 get/post/put/patch/...	get
params	[Object\|URLSearchParams] url 查询参数将通过 `?` 拼接到 url 后部发送到服务接口 get 方法一般指定使用该属性传递参数	无
data	[String\|Object\|Array\|URLSearchParams] 请求主体数据 post/put/patch 等方法需要指定该属性挂载数据	无
timeout	[Number] 请求超时的毫秒数	5000
headers	[Object] 自定义请求头	无
responseType	[string] 服务器响应的数据类型 ArrayBuffer/Blob/Document/json/text/stream	json

# 引入和使用接口方法

定义好接口，即可通过 import 关键字进行引人使用。

# 引入单个接口

开发者可以从一个接口文件引入单个接口方法。

import { fetchList } from '@/api/article.js'

const params = {
  page: 1,
  length: 20
}

// 查询文章列表
fetchList(params).then(response => {
  // 收到接口响应
  console.info(response)
}).catch(error => {
  // 接口请求失败
  console.warn(error)
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 引入多个接口

开发者可以从一个接口文件同时引入多个接口方法。

import { fetchList, fetchArticle } from '@/api/article.js'

// 查询文章列表
fetchList({
  page: 1,
  length: 20
}).then(response => {
  // 收到接口响应
  console.info(response)
}).catch(error => {
  // 接口请求失败
  console.warn(error)
})

// 查询文章详述
fetchArticle({
  id: 10001
}).then(response => {
  // 收到接口响应
  console.info(response)
}).catch(error => {
  // 接口请求失败
  console.warn(error)
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 接口返回值

目前框架内 Mock Server 模拟接口返回结构如下：

{
  code: 20000,
  data: {…},
  message: "…"
}

1
2
3
4
5

TIP

推荐该种方案。

code 编码说明

编码值	说明
20000	请求成功
50008	无效的 Token
50012	从其他设备或浏览器登陆，被下线
50014	Token 过期

TIP

该方案结构与 ENESYS 系列接口返回值结构及编码系统不一致，框架对此进行了兼容处理。

与目前 ENESYS 系列产品兼容的接口返回结构如下

// 单一数据
{
  returnCode: "0000",
  data: {…},
  returnMessage: "…"
}

// 列表数据
{
  returnCode: "0000",
  data: […],
  recordsTotal: 200,
  returnMessage: "…"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14