前后端接口文档规范
2022-06-01 本文已影响0人
晨曦的杂货铺
一、约定接口一般包括如下数据:
-
当前接口的路径? 如 /auth/login
-
当前接口提交数据的类型是什么?
-
GET
获取数据 -
POST
提交数据 -
PATCH
修改数据,部分修改 -
DELET
E 删除数据 -
PUT
修改数据,整体替换原有数据
-
-
参数类型格式,比如
JSON
格式,还是application/x-www-form-urlencoded
的数据 -
参数字段,及限制条件(例如其返回的手机号必须是9位,开头为1)
-
返回成功的数据格式
-
返回失败的数据格式
二、认证相关
下面我们将和后端做一下接口约定(下面举出一个用户注册的例子,便于理解)
功能:用户注册
提交参数:
- 参数类型:
Content-Type: application/x-www-form-urlencoded;charset=utf-8
- 参数字段
- username:用户名, 长度1到15个字符,只能是字母数字下划线中文
- password : 密码, 长度6到16个任意字符
返回的数据:
- 失败
- 状态码 400
- 返回格式 {msg: '错误原因'}
- 成功
- 状态码 200
- 返回格式
"msg": "注册成功",
"data": {
"id": 1,
"username": "sunrui",
"updatedAt": "2022-12-27T07:40:09.697Z",
"createdAt": "2022-12-27T07:40:09.697Z"
}
}
3、引入axios封装统一接口
1.我们要先安装axios, 在终端输入yarn add axios --save
,然后创建一个request.js文件,导出一个函数,当使用某个接口时,只需调用这个函数即可。
import axios from "axios"
axios.defaults.headers.post['Content-Type'] = 'application/x-www-form-urlencoded' //设置所有的post请求
axios.defaults.baseURL = ' https://note-server.hunger-valley.com' // 服务端的线上接口域名
axios.defaults.withCredentials = true //允许axios请求跨域
export default function request(url, type = "GET", data = {}) {
return new Promise((resolve, reject) => {
let option = {
url,
method: type,
validateStatus(status) {
return (status >= 200 && status < 300) || status === 400
}
}
//
if (type.toLowerCase() === 'get') {
option.params = data
} else {
option.data = data
}
axios(option).then(res => {
if (res.status === 200) {
resolve(res.data)
} else {
console.error(res.data);
reject(res.data)
}
}).catch(err => {
console.error({ msg: '网络异常' });
reject({ mag: "网络异常" })
})
})
}
2.调用注册页面的接口
request("/auth/register","post",{usrname:'sunrui',pssword:'123456'}).then(res=>{
...
}).catch(err=>{
...
})
提示:由于本接口的域名是以http://开头的,谷歌升级了安全策略,对于跨域请求如果想写入cookie,必须是https的网站才可以。对于http的网站,cookie写入总是失败。
解决办法:
在vue.config.js文件下添加如下代码
devServer: {
https: true,
}
此时浏览器输入 https://localhost:8080 ,并不能打开页面,
在当前页面用键盘输入 thisisunsafe ,就可以了
4、将接口封装成api
新建auth.js
文件,用一个统一的函数来封装我们使用的接口,当接口发生改变时,我们只需要修改此函数即可,
以下例子我们将封装一个登录,注册,注销的接口.
import request from "@/helper/request"
const URL = { //定义我们的接口
REGISTER: '/auth/register',
LOGIN: "/auth/login",
LOGOUT: "/auth/logout",
}
export default {
register({ username, password }) {
return request(URL.REGISTER, 'POST', { username, password })
},
login({ username, password }) {
return request(URL.LOGIN, 'POST', { username, password })
},
logout() {
return request(URL.LOGOUT)
},
getInfo() {
return request(URL.GET_INFO)
}
}
我们只需用register({uesrname:"sunrui",password:"123456"})
来调用此接口.