命名规范

词汇表

API 说明文档应该在开头部分对业务相关的词汇进行约定，给出一份供所有人参考的词汇表。

可以参考商业阿拉丁资源库接口文档的相应部分。

---

通用命名

为了避免不同产品线对业务对象的增删改查等操作都使用不同词汇从而增加了沟通和维护的成本，在此对接口、Action路径中的常用操作和展现形式的语义进行明确，对类似含义的词汇进行合并。

常用操作

下面 X ← Y / Z 的意思是 Y 和 Z 均标准化为 X 进行表述。

create

系统中不存在，从无到有进行创建。

add ← attach

将已有的东西关联到其他东西上（add A to B）。

remove

将已有的东西从其他东西上移除但仍存在于系统中，即去除关联关系（remove A from B）。

delete ← destroy

从系统中彻底删除一个东西，使其不存在。

edit ← modify / change

对业务对象进行修改。

update

使修改生效（持久化）。

save

保存修改后的内容，但不实际生效（一般业务中对应「仅保存」的情况）。

submit

通用的提交操作（比如 create / update 共用，通过 id 参数是否存在来判断类型等）。

常用展现形式

对于查询类的操作，我们可以通过下面的方式来描述被查看内容的展现形式：

list

以列表方式展现。

detail

以详情方式展现。

summary

以概要方式展现。

chart

以图表方式展现。

Action 命名

模块名 → 业务对象 → 修饰符 → 操作 / 展现方式

[/<module>]+/<entity>[/[<modifier>||<entity>]]*/[<operation>||<display>]

eg.

• /promotion/ad/list
• /promotion/material/daily/list
• /validation/enterprise_qualification/create
• /account/setting/edit // 前端的修改入口，用 edit 比较合适

前后端接口命名

统一前缀 → 模块名 → 业务对象 → 修饰符 → 操作 / 展现方式

/data[/<module>]+/<entity>[/[<modifier>||<entity>]]*/[<operation>||<display>]

注：前后端接口中的 ad 字样统一用 173 （0xAD === 173）代替，以免请求被 AdBlock 等工具过滤。

eg.

• /data/promotion/173/update // 将修改提交到后端，统一用 update
• /data/promotion/173/pie/chart // 推广计划的饼图数据
• /data/promotion/material/daily/list // 将物料信息按天统计成列表
• /data/promotion/material/save // 仅保存物料
• /data/validation/enterprise_qualification/create