本文总结了笔者近几年在参与设计 API 时收获的一些经验和教训,针对中小型项目初期,供大家参考。

  1. 设计 基础数据与用户数据尽量分离。
    分别用不同的字段存储或直接分到不同的 API里。
    逻辑解耦,便于后期修改,也便于优化打开速度。

    1
    2
    3
    4
    5
    6
    // bad
    {
    title:"新概念英语",
    image:"http://example.com/en.png",
    learnProgess:80
    }
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    // good
    {
    baseData:{
    title:"",
    image:"http://example.com/en.png"
    },
    userData:{
    learnProgess:80
    }
    }
  2. 设计 鉴权数据能放 header 尽量放 header。不要往 GET/POST 请求参数里放。

  3. 设计 公共请求参数/响应参数提前设计,预留空间以备升级。

  4. 设计 原则上严格参考 GET/POST 的语义规范(GET 幂等,POST 提交数据)。
    之前一个项目采用了全 POST 请求,后期复盘后认为是一个比较失败的设计。公共参数都放在 POST 请求体里,无法修改成 GET 请求,导致做 PWA 的时候处处受限,并且也没有充分利用 GET 请求的强制缓存/协商缓存功能。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    // bad
    {
    "channel":"",
    "locale":"zh_CN",
    "appver":"1.2.3",
    "token":"mytoken123",
    "sitecode":"sitecode567",
    "data":{
    "id":123
    }
    }
  5. 开发 后端开发的时候根据项目实际规模预留合理的升级空间,切勿考虑过多导致过度设计,冗余代码。

  6. 开发 复杂逻辑在对性能没有极端要求的情况下,适当将并发操作改为串行,降低代码的阅读成本,或使用 async 流程控制库,在适当增加代码冗余的情况下,降低代码的阅读成本。

  7. 开发 文件名、变量名严禁单字母缩写。
    如,wQuizAction.js/uOrderReducer.js 等,当时写的时候也许觉得很清晰,但是给其他阅读代码的人造成很大障碍,即使是本人在查看几个月前的代码也很可能忘记缩写的含义。

  8. 数据库 用户相关的表在设计初级必须评估规模,根据可能出现的查询条件建索引,减少慢SQL。另外使用阿里云RDS的用户也可以经常查看下后台日志。

  9. 数据库 数据库的字段尽可能与业务代码保持一致,重构时也要考虑重构完全。