前后端交互接口标准.md

前后端交互接口标准

因为目前存在多个版本接口标准，对于前端的组件复用，错误处理都要写多个版本的逻辑兼容，为了减少这种没意义的工作量，希望可以统一接口返回逻辑，基于 RESTful 接口约定，和我们目前实际情况提出以下两个方案，V1为过渡方案，V2为理想方案。

V1

适用范围，修改困难的老项目

基础字段

interface CommandResult<T> {
  code: number;
  msg: string;
  data: T;
}

分页字段

interface Page<T> {
  content: T[];
  hasNextPage: boolean;
  hasPrevPage: boolean;
  pageNum: number;
  pageSize: number;
  totalPages:number;
  total: number;
}

接口

• 接口返回字段禁止为null,如果因历史原因无法规避，必须在 swagger 文档中表明

请求方式

• GET
• POST

例子

// success
{
    code:0,
    msg: "success",
    data: [],
}
// 分页 success
{
    code:0,
    msg: "success",
    data: {
        content:[],
        hasNextPage:true,
        hasPrevPage:false,
        pageNum:1,
        pageSize:10,
        totalPages:10,
        total:100
    },
}
// error
{
    code: -1,// 对于状态码
    msg: "error data",
    data: "",
}

V2

相对标准的 RESTful风格api，标准过于严苛，完全遵守成本略高，关于RESTful风格标准，请大家自行学习。

接口

• 接口只是资源路径，只能由名词组成，不能出现动词，接口的行为通过 Method 表达
• 接口状态体现在 http status code 上
• 分页接口以/page 结尾，列表以/list 结尾
• post,put,patch 全部以 json 形式传参数

请求方式

Methods 标准

返回体

• 成功 无基础字段，返回体直接返回内容
• 失败 http status code 为对应状态
  • http status 参考org.springframework.http.HttpStatus

例子

// success 单字段
{
    data: "hello world",
}
// success 多字段
{
    name: "张三",
    age: 18
}
// 分页 success
{
    content:[],
    hasNextPage:true,
    hasPrevPage:false,
    pageNum:1,
    pageSize:10,
    totalPages:10,
    total:100
}
// error
{
    code: 123,// http状态码以可以表达足够多的错误，次字段为拓展字段，可不用
    msg: "error data",
}

其他

• 接口返回字段禁止为null,如果因历史原因无法规避，须在 swagger 文档中表明