a4纸背单词法的接口设计

a4纸背单词法的接口设计

黄鹏宇 645 2022-07-31

由于v2版本api定义混乱,出现了很多不优雅的接口,趁这次重构,重新规范,并在此记录学习与思考过程。
本文档定义的接口属于SSKD(Small Set of Known Develpers),服务于ace word产品的小程序端、移动端及web。

本文参考《Web API的设计与开发》,以及RESTFUL设计风格

〇、点击查看接口文档

一、规范

0. 基本格式

  1. 采用json进行通信
  2. url:
    1. 线上地址:https://api.aceword.xyz/v3/
    2. 测试地址:https://43008f543x.oicp.vip/v3/
  3. 返回值封装为
{    
    Integer errcode;
    String errmsg;
    T data;
}

1. 路径里使用小写,用连字符连接 - ,字段中使用驼峰法 userAge

2. 使用HTTP的方法

  • GET : 获取资源、幂等
  • POST:新建资源、不幂等
  • DELETE:删除资源、幂等
  • PATCH: 更新部分资源、幂等
  • PUT: 替换已有资源 、幂等

3. 使用参数还是路径

对于能唯一标识资源的,使用路径

  • 比如userID 可以唯一标识用户

/user-info?id=1

✔️ /user-info/2

  • 比如date不能唯一标识cards

/card/1

✔️ /cards?date=123&

4. 返回结果扁平化还是层级化

对于层级化不是占据巨大优势的情况下,尽量扁平化

✔️ 正确示范

{
	name: xxx,
	age:19,
	openClock: xxx
}

❌错误示范

{
  profile: 
  {
      name: xxx,
      age:19
  },
  setting:{
      openClock: xxx
  }
}

5. 根据字段来获取所需内容

使用fields = [ ] , 来选定所需内容
/card?fields=[id,createTimestamp,practiceCount], 则会返回对应三个字段

  • 若fields为空,则返回所有字段
  • 响应群
    定义basic = id,createTimestamp,practiceCount,则
    /card?fields=[basic]与上述相同

6. 状态码的定义【todo】

7. 标识不同环境 web / app / miniapp

/v3/app/user/xxx
/v3/miniapp/user/xxx

8. 文档的标志

:id :变量
fields=[a,b,c] 可选项

一个api包括: 方法、路径、返回值、可选字段、相应群

二、资源汇总

  • 用户 user
  • 卡片 card
  • 单词 word
  • 句子 sentence
  • 进度 progress
  • 单词本 wordgroup
  • 词书 wordbook

三、安全与稳定

1. 限流

错误码:429

服务 单位 时间 上限
整体 用户 / IP 5分钟 100次

2. 具体各个接口的频率限制不相同

四、todo

1. 将文档存储为json,并用web进行解析,并能测试

https://www.qdu.life/api

2. 词典

将字典抽离出来,作为微服务改造的第一步

五、开发流程

对于一个接口,有七个状态:

  • 设计中
  • 待确定
  • 开发中
  • 联调中
  • 测试中
  • 有异常
  • 已发布
    image