规范 - 接口文档

作者：Zonezzc
最后更新时间：2024-03-26 19:13:06

---

​​

原则

1. 接口的命名最终一定是便于理解的中文。
2. 接口的说明中一定包含接口原名如 getSellerStandardsProfile，若存在第三方在线接口文档，该原名设置为引向原文的超链接。
3. 所有的参数都要有中文注释。

命名规范

对接口理解不透彻时先使用接口的英文原文或接口的源代码名称占位，以防错误的理解翻译对他人造成理解困难。

例：

• 广告 - 创建（批量ByInventoryReference）
• 广告报表任务 - 生成 - 查询（生成状态）
• 促销活动 - 查询
• getSellerStandardsProfile

形如：x1 - ... - xn-1（xn）​

• ​-​ 符号前后各自有且仅有一个空格。
• ​（）​ 为中文括号，且前后与内部皆无空格。
• ​x1、xn-1、xn​ 在该规范中仅作为占位符存在，不表示长度限制。在保证语义的情况下尽可能简短，以便于检索。
• 同一接口目录下的 x1​ 尽可能保持相同且唯一，用于表示父级层级，可与目录或目录含义保持相同。
• ​xn​ 表示描述有 N 个层级，N 的值尽量不要大于 3。
• ​xn-1​ 位置的描述符见下文。

xn-1位置描述符规范

基础描述符

描述符	说明
创建	只执行创建或新增业务使用该描述符。
查询	查询或获取数据业务使用该描述符。
更新	只执行更新数据业务使用该描述符。
删除	只执行删除业务使用该描述符。

高级描述符

描述符	说明
保存	执行『创建』或『更新』 的业务使用该描述符。
克隆	基于已『创建』的内容部分『更新』生成相同本质的『创建』业务使用该描述符。
生成	基于已『创建』的内容产生新的不同本质的『创建』业务使用该描述符。

生命周期描述符

描述符	说明
启动	具有特殊生命周期业务的『更新』使用该描述符。
暂停	具有特殊生命周期业务的『更新』使用该描述符。
恢复	具有特殊生命周期业务的『更新』使用该描述符。
停止	具有特殊生命周期业务的『更新』使用该描述符。

资源描述符

描述符	说明
上传	需要资源上传的业务使用该描述符。
下载	需要资源下载的业务使用该描述符。

xn位置描述符规范

描述符	说明
批量	该描述符仅存在于 xn​ 位置，用于表述接口中的 s​ 等复述形式（需要具有较多返回值，而非单个返回）。
目的/目标	用于表示目标或目的，例 xx - 查询（学生）​，xx - 查询（校区）​。
Byxxx/Forxxx/xxx	用于表示筛选条件时尽量不要出现中文，使用接口中的英文原文进行描述，注意英文的驼峰书写，且首字母大写。

‍