Gitcx框架文档

后端接口联调，必看

# 如何快速编写完成后端接口

• 第 1 步: 本地启动一个最原始的带 mock 的项目，退回到登录页，打开浏览器控制台，开始模拟登录，此时你可以在浏览器 network（网络）中看到/login、/userInfo、/logout的 json 格式和参数

• 第 2 步：开始完整照着 network 编写后端接口，使用 postman 测试通过（注意 postman 支持跨域而浏览器不支持，故需要先配置好对应的后端跨域）

• 第 3 步：修改src/confing/net.config.js里面的 baseURL 即可

• 第 4 步：如需使用进阶方案，采用后端路由，请详见【路由配置】模块

# 如何连接后端接口

• 注意直接连接方案与代理连接方案互斥，建议使用方案 1

方案 1：直接连接方案（记得后端配置跨域）

/**
 * @description 导出网络配置
 **/
module.exports = {
  // 默认的接口地址，开发环境和生产环境都会走/vab-mock-server
  // 正式项目可以选择自己配置成需要的接口地址，如"https://api.xxx.com"
  // 问号后边代表开发环境，冒号后边代表生产环境
  baseURL:
    process.env.NODE_ENV === "development"
      ? "/vab-mock-server"
      : "/vab-mock-server",
};

# 项目开发必要接口

本项目需要三个必要的接口，联调前务必保证这登录接口、用户信息接口、退出接口无问题，请注意application/x-www-form-urlencoded;charset=UTF-8与 application/json;charset=UTF-8请求的区别，具体可在src/config/settings.js 中配置， 注意：除登录接口外其他接口连接后端后携带 token，格式如下Authorization: Bearer admin-token-24ba1FFF-AcC8-f0AE-ECea-A1EE12d712Ae-后端在登陆时返回给你的token字符串

登录接口 /login（post 请求） application/json;charset=UTF-8 请求参数（默认格式）

{
  "username": "admin",
  "password": "123456"
}

返回格式：（必须严格按照此格式，不能为空这里返回的 token 会在今后所有的接口中自动通过 headers 的 Authorization 携带到后端，后端注意接收并处理跨域问题）

{
  "code": 200,
  "msg": "success",
  "data": {
    "token": "admin-accessToken-xxxxxx"
  }
}

用户信息接口 /userInfo（get 请求）

此接口默认会通过 headers 将 Authorization（token）传递到后端，后端根据 headers 判断用户所包含的权限，并返回相应的数据即可

返回格式：（必须严格按照此格式，不能为空）

rbac 文档 (opens new window)

2021 年 8 月 31 日后版本，更符合 rbac 规范

{
  "code": 200,
  "msg": "success",
  "data": {
    "username": "admin",
    "roles": ["Admin"],
    "permissions": ["read:system", "write:system", "delete:system"],
    "avatar": "https://i.gtimg.cn/club/item/face/img/2/16022_100.gif"
  }
}

2021 年 8 月 31 日前版本，可根据路由 name 匹配

{
  "code": 200,
  "msg": "success",
  "data": {
    "roles": ["admin"], // 一个用户可包含多个角色如["admin","editor","XXXX"]，必须返回，如小项目用不到角色权限请返回 ["admin"]
    "ability": ["READ", "WRITE", "DELETE"], // 不区分页面写法：如果用不到rabc精细化权限可以不返回，建议返回
    "ability": [
      "index-READ",
      "index-WRITE",
      "index-DELETE",
      "role-READ",
      "role-WRITE",
      "role-DELETE",
      "goods-READ",
      "goods-WRITE",
      "goods-DELETE",
      "页面name-READ",
      "页面name-WRITE",
      "页面name-DELETE"
    ], // 区分页面写法：建议把路由页面的name当做前缀来区分精细化权限，建议区分
    "username": "admin", // 用户名，必须返回
    "avatar": "https://i.gtimg.cn/club/item/face/img/8/15918_100.gif" // 头像，必须返回
  }
}

退出接口 /logout（get 请求）

此接口默认会通过 headers 将 Authorization（token）传递到后端，后端根据 headers 判断用户所包含的权限，退出对应的账号即可

返回格式

{
  "code": 200,
  "msg": "success"
}

其余可配置关闭的接口，如顶部的搜索、通知接口请自行查看mock/controller下的示例 注意：2021 年 4 月 15 日起，接口风格将改为 restful 的规范

# 前端请求示例

强烈建议：所有请求放到 src/api 文件夹下

// post请求示例
import request from "@/utils/request";

export function getList(data) {
  return request({
    url: "/table/list",
    method: "post",
    data,
  });
}

// get请求示例
import request from "@/utils/request";

export function getList(params) {
  return request({
    url: "/table/list",
    method: "get",
    params,
  });
}

# 前端请求约定

请求中会在 headers 中自动传入 token，格式如下Authorization: Bearer admin-token-24ba1FFF-AcC8-f0AE-ECea-A1EE12d712Ae-后端在登陆时返回给你的token字符串

/*表格中请求参数约定*/
{
  "pageNo": 1, //页数
  "pageSize": 10 //每页条数
}

# 后端返回 JSON 数据的约定（2021 年 4 月 15 日前版本）

{
  "code": 200,//成功的状态码
  "msg": "success",//提示信息
  "totalCount": 238,//总条数（表格中用到，其它接口可以不返回）
  "data": [{}，{}，{}]//返回数据
}

# resultful 的规范，后端返回 JSON 数据的约定（2021 年 4 月 15 日后版本）

{
  "code": 200, //成功的状态码
  "msg": "success", //提示信息
  "data": { //返回数据
      "list": [{}，{}，{}], //返回数组
      "total": 238, //总条数（表格中用到，其它接口可以不返回）
  }
}

# 旧项目如果不想使用新版 resultful 的规范

2021 年 4 月 15 日前版本，请使用 zx-templates 代码生成机

第 1 步：安装依赖

cnpm  i zx-templates -D

第 2 步：修改项目根目录plopfile.js文件为以下内容

const viewGenerator = require('zx-templates/view/prompt')
const curdGenerator = require('zx-templates/curd/prompt')
const componentGenerator = require('zx-templates/component/prompt')
const mockGenerator = require('zx-templates/mock/prompt')
const vuexGenerator = require('zx-templates/vuex/prompt')

module.exports = (plop) => {
  plop.setGenerator('view', viewGenerator)
  plop.setGenerator('curd', curdGenerator)
  plop.setGenerator('component', componentGenerator)
  plop.setGenerator('mock&api', mockGenerator)
  plop.setGenerator('vuex', vuexGenerator)
}

# 后端返回 code 的约定

常用的 code：200-正常 500-错误提示用 401-回到登录页用 402-刷新 token 用

  200: '服务器成功返回请求数据', //常用
  201: '新建或修改数据成功',
  202: '一个请求已经进入后台排队(异步任务)',
  204: '删除数据成功',
  400: '发出信息有误',
  401: '用户没有权限(令牌失效、用户名、密码错误、登录过期)', //常用
  402: '令牌过期', //常用
  403: '用户得到授权，但是访问是被禁止的',
  404: '访问资源不存在',
  406: '请求格式不可得',
  410: '请求资源被永久删除，且不会被看到',
  500: '服务器发生错误', //常用
  502: '网关错误',
  503: '服务不可用，服务器暂时过载或维护',
  504: '网关超时',

跨域配置