API设计总结

本文总结了笔者近几年在参与设计 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. 数据库 数据库的字段尽可能与业务代码保持一致，重构时也要考虑重构完全。