前后端接口文档规范

一、约定接口一般包括如下数据：

1. 当前接口的路径？ 如 /auth/login

2. 当前接口提交数据的类型是什么?

   • GET获取数据
   • POST提交数据
   • PATCH修改数据，部分修改
   • DELETE 删除数据
   • PUT 修改数据，整体替换原有数据

3. 参数类型格式，比如JSON格式，还是 application/x-www-form-urlencoded的数据

4. 参数字段，及限制条件(例如其返回的手机号必须是9位，开头为1)

5. 返回成功的数据格式

6. 返回失败的数据格式

二、认证相关

下面我们将和后端做一下接口约定（下面举出一个用户注册的例子，便于理解）

功能：用户注册

提交参数：

• 参数类型: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"})来调用此接口.