流程定义

  • 后端编写和维护接口文档，在 API 变化时更新接口文档
  • 后端根据接口文档进行接口开发
  • 前端根据接口文档进行开发 + 文档平台（需要沟通用哪个文档地址？）

  • 开发完成后联调和提交测试

    职责分离

  • 前后端仅仅通过异步接口 (AJAX/JSON) 来编程

  • 前后端都各自有自己的开发流程，构建工具，测试集合
  • 关注点分离，前后端变得相对独立并松耦合 | 后端 | 前端 | | —- | —- | | 提供数据 | 接收数据，返回数据 | | 处理业务逻辑 | 处理渲染逻辑 | | Server-side MVC 架构 | Client-side MV* 架构 | | 代码跑在服务器上 | 代码跑在浏览器上 |

协议规范

  • GET : 用于从服务器获取资源信息
  • POST : 用于创建新资源

其他请求方式不要出现，另外尽量使用POST！！

返回数据规范

正常格式：

需要定义单个数据、集合数据、可能有可能无数据、分页数据、流数据、二进制数据、认证加密数据。导出表格需采用Blob的方式实现

异常格式：

异常数据描述格式，包括异常名称、异常描述

数据编码:

  1. Content-Type: application/json; charset=utf-8

状态码

请求成功状态码标识

  • 200 : 求执行成功并返回相应数据
  • 201 : 创建成功并返回相应资源数据
  • 202 : 接受请求，但无法立即完成创建行为

  • 204 : 请求执行成功，不返回相应资源数据

    重定向

  • 301 : 被请求的资源已永久移动到新位置

  • 302 : 请求的资源现在临时从不同的 URI 响应请求
  • 303 : 对应当前请求的响应可以在另一个 URI 上被找到，客户端应该使用 GET 方法进行请求

  • 307 : 对应当前请求的响应可以在另一个 URI 上被找到，客户端应该保持原有的请求方法进行请求

    条件请求

  • 304 : 资源自从上次请求后没有再次发生变化，主要使用场景在于实现数据缓存

  • 409 : 请求操作和资源的当前状态存在冲突。主要使用场景在于实现并发控制

  • 412 : 服务器在验证在请求的头字段中给出先决条件时，没能满足其中的一个或多个。主要使用场景在于实现并发控制

    客户端请求错误

  • 400 : 请求体包含语法错误

  • 401 : 需要验证用户身份
  • 403 : 服务器拒绝执行
  • 404 : 找不到目标资源
  • 405 : 不允许执行目标方法，响应中应该带有 Allow 头，内容为对该资源有效的 HTTP 方法
  • 406 : 服务器不支持客户端请求的内容格式
  • 410 : 被请求的资源已被删除
  • 413 : POST 或者 PUT 请求的消息实体过大
  • 415 : 服务器不支持请求中提交的数据的格式
  • 422 : 请求格式正确，但是由于含有语义错误，无法响应

  • 428 : 要求先决条件，如果想要请求能成功必须满足一些预设的条件要求先决条件，如果想要请求能成功必须满足一些预设的条件

    服务端错误

  • 500 : 服务器遇到了一个未曾预料的状况，导致了它无法完成对请求的处理

  • 502 : 作为网关或者代理工作的服务器尝试执行请求时，从上游服务器接收到无效的响应
  • 501 : 服务器不支持当前请求所需要的某个功能

  • 503 : 由于临时的服务器维护或者过载，服务器当前无法处理请求

    1. {
    2.  "code":"200", // 1.成功为200， 2.其他非200
    3.   "data": {
    4.     "currPage": 1,
    5.     "datas": [
    6.       {
    7.         "name":"张三",
    8.         "age":"20"
    9.       }
    10.     ],  
    11.     "total": 20,
    12.     "totalPage": 2  
    13.   },
    14.   "message":"成功", //  1.成功信息， 2其他返回对应信息 
    15. }

    URL规范

    1. http://bapi.qa.zktsoft.com/项目名称/菜单名/接口名称 //QA环境
    2. http://bapi.t.zktsoft.com/项目名称/菜单名/接口名称 //预发环境
    3. https://bapi.zktsoft.com/项目名称/菜单名/接口名称 //生产环境

  • 不能使用大写，用小驼峰命名；传参同样；

  • 接口名称，首字母可以用动词来标识干什么的，获取get，保存save，更新update，删除delete等。
  • 传参如何未有值，类型为空字符串，其他类型不适用。分页传参固定pageSize,pageIndex；接口返回如果字段未有值，请选择类型为空字符串，其他类型不需要，并返回。