由于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

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

四、todo

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

https://www.qdu.life/api

2. 词典

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

五、开发流程

对于一个接口，有七个状态：

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