API 设计总结

569 阅读2分钟

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

本文首发于 www.lvdawei.com/post/API-de…

设计角度

  1. 基础数据与用户数据尽量分离。 分别用不同的字段存储或直接分到不同的 API里。 逻辑解耦,便于后期修改,也便于优化打开速度。
// bad
{
    title:"新概念英语",
    image:"http://example.com/en.png",
    learnProgess:80
}
// good
{
    baseData:{
        title:"",
        image:"http://example.com/en.png"
    },
    userData:{
        learnProgess:80
    }
}
  1. 鉴权数据能放 header 尽量放 header。不要往 GET/POST 请求参数里放。

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

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

// bad
{
    "channel":"",
    "locale":"zh_CN",
    "appver":"1.2.3",
    "token":"mytoken123",
    "sitecode":"sitecode567",
    "data":{
        "id":123
    }
}

开发角度

  1. 后端开发的时候根据项目实际规模预留合理的升级空间,切勿考虑过多导致过度设计,冗余代码。

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

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

数据库角度

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

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