一、开发流程

  1. api先行
    1. 后端根据实际业务结合原型图，写文档
    2. 前端对照原型，根据前端工程的架构审核api
  2. 前后端根据api同步开发
  3. 前后端联调

  4. 提测


    倡导api先行的原则，在需求确定后，优先完成api文档，以此为前后端并行开发的基础条件

二、API管理

  • 现采用Yapi管理平台，基本的操作⾃行摸索。
  • 注意点：
    • Ypi平台需要⾃行注册（用户名用名字拼音，邮箱使用公司邮箱，其它随意）
    • Yapi有项⽬目组的概念，如果看不到相应的api⽂档，需联系管理理员添加权限。

  • 相关链接：

  • API路径约定

    • 由于resultApi存在一定的歧义，又没有其它更好的规范约束。所以就保证原则自行发挥好了。
    • 原则
      • 路径上的目录分隔用以做分组，区分大类。
      • 以“驼峰”进行命名
      • 尽量描述清楚接口的作用
    • 例如：/api/user/editNickName
  • API请求传参
    • 请求类型限制在get和post两种类型。
    • GET请求参数就是标准的url传参，遇到特殊符号用uri编码。
    • POST请求为json类型的，即application/json类型。
    • 文件上传时使用multipart/form-data类型。
  • API返回值
    • 数据统一使用如下的方式返回：{“code”:”-1”,”msg”:”Required Integer parameter ‘sysNoticeId’ is not present”,” data”:{}}
      • code，表示状态码，string类型。
        • 业务状态码（-999——99）
          • 0表示正常，
          • 负数表示异常
          • 0-99可用来表示请求正常响应，不同类型的处理。例如：
            • 登录成功：0
            • 登录成功：1（原先不存在当前账户，自动注册了个新账户）
            • 登录成功：2（踢出了其它设备中登录的当前账户）
          • 业务中的error code参照api文档自行约定。
        • 系统全局状态码（200——999）
          • 其中200——599的系统异常是参照http的状态码制定的，请不要做修改和添加。
          • 其它异常使用600——699的状态码，这个区间增加状态码请更新文档
          • 百位数用以标识问题大类。
            • 2xx正常返回
            • 4xx权限异常
            • 5xx服务异常
            • 6xx系统异常
            • 9xx微服务异常
          • 具体约定见下文。
      • msg，是错误时的描述信息，string类型。提供给前端进行展示或提醒，如果非错误，默认返回ok
      • data，是真正的响应本体。
        • 请求结果正常的时候根据业务需要返回合适的值。（注意：查询数据为空的时候传{}，空对象，不要传null）
        • 请求结果错误的时候，在非生产环境下返回具体的错误原因，甚至错误代码。生产环境则为{}。
    • 系统级状态码
      • 可用http状态码表示的系统异常
        • 200: 服务器成功返回请求的数据。
        • 201: 新建或修改数据成功。
        • 202: 一个请求已经进入后台排队（异步任务）。
        • 204: 删除数据成功。
        • 400: 发出的请求有错误，服务器没有进行新建或修改数据的操作。
        • 401: 用户没有权限（令牌、用户名、密码错误）。
        • 403: 用户得到授权，但是访问是被禁止的。
        • 404: 发出的请求针对的是不存在的记录，服务器没有进行操作。
        • 406: 请求的格式不可得。
        • 410: 请求的资源被永久删除，且不会再得到的。
        • 422: 当创建一个对象时，发生一个验证错误。
        • 500: 服务器发生错误，请检查服务器。
        • 502: 网关错误。
        • 503: 服务不可用，服务器暂时过载或维护。
        • 504: 网关超时。
      • 其它系统异常（600-699）
        • 601: 数据库错误
        • 602: 代理错误（调用后的错误——微服务告知错误）
        • 603: 调用微服务时程序发生了错误（调用发生前的错误，比如请求超时、api地址不存在等）
      • 微服务异常（900-999）
        • 900: 微服务异常0222
        • 901: 微服务异常0001
        • ~~902: 微服务异常0002 ~~

补充说明：

  1. 200状态不做使用，code返回0
  2. 600-999，区间的状态用作“自定义”的全局错误，全系统统一的那种。
  3. 建议用第一位用作“标识”区分不同大类型的状态

四、其它

分页数据返回格式

  1.  {
  2.      list: [],
  3.      pageSize: 20,
  4.      currentPage:1,
  5.      total: 100,
  6.      totalPage: 5
  7. }