API命名规范
命名风格
面向资源
在大型系统中，常以”业务领域”视角进行模块划分，以达到业务”高内聚低耦合”的效果。
“业务领域”必有”数据对象”沉淀，从宏观抽象的角度看，"数据对象"可统称为"资源"，”业务领域”就是业务相近的”资源”的集合。
"资源"一定是业务抽象后的对象：
- 可以是具体的数据对象：
- 可以是抽象的对象概念：
"业务领域"与"业务领域"之间的依赖，可理解为是对"资源"操作(读、写、通知)的依赖。
所以，API作为"业务领域"间沟通的手段，其应该(Should)以面向资源角度进行命名。
注：子资源，需要逐级索引命名，例如：修改-订单-商品：updateOrderItem。
单一视角
动宾风格
API应该(Should)以"动宾短语"风格命名。
例如：
1
2
3
4
5 | xxx.xxx.xxx.OrderService // 上下文已涵盖Order语义
Response<T> save(...)
Response<T> updateItem(Long orderId, List<T> items) |
1
2
3
4
5
6
7 | xxx.xxx.xxx.WCService // 上下文未涵盖Order语义
Response<T> saveOrder(...)
Response<Boolean> removeOrder(Long orderId)
Response<T> updateOrderItem(Long orderId, List<T> items) // 逐级索引子资源 |
统一术语
API命名统一”动词”术语、”名词”术语。优点是能风格一致，经验复用。
详见
注：统一术语的节奏，参考研发级术语规范逐步执行：业务内统一、业务领域内统一、平台统一。
错误实践-1：”商品”命名不统一
1
2
3
4 | 业务1：商品 -> item ✔️
业务2：商品 -> items
业务3: 商品 -> product
业务4：商品 -> goods |
错误实践-2：”特性”命名不统一
1
2
3 | 业务1：特性 -> feature ✔️
业务2: 特性 -> character
业务3：特性 -> rule |
错误实践-3：”金额”命名不统一
1
2
3 | 业务1：金额 -> amount ✔️
业务2: 金额 -> money
业务3：金额 -> sum |
错误实践-4：”校验”命名不统一
1
2
3 | 业务1：校验 -> verify
业务2: 校验 -> check ✔️
业务3：校验 -> test |
错误实践-5：”分页”命名不统一
1
2
3 | 业务1：分页 -> page
业务2: 分页 -> paging✔️
业务3：分页 -> list |
错误实践-6：”创建”命名不统一
1
2
3 | 业务1：创建 -> save✔️
业务2: 创建 -> create
业务3：创建 -> insert |
错误实践-7：”删除”命名不统一
1
2
3
4 | 业务1：删除 -> delete
业务2: 删除 -> remove✔️
业务3：删除 -> disable
业务3：删除 -> cancel |
错误实践-8：”检索”命名不统一
1
2
3 | 业务1：搜索 -> query✔️
业务2: 搜索 -> search
业务3：搜索 -> list |
常见API命名参考
分页查询
1 | Response<Page<T>> pagingXXX(QueryDTO q) //用对象包装查询条件 |
1 | Response<Page<T>> pagingXXX(String name, String code, Long orgId, Long creatorId, Integer pageNo, Integer PageSize) |
以上错误实践缺点：
1、对于调用方来说，无论以什么条件查询，都需要逐个条件传参
2、API对扩展不友好，一旦想增加查询条件，API就不兼容。
列表查询
1 | Response<List<T>> listXXX(...) |
获取单个详情
1
2
3
4
5 | Response<T> getXXX(Long id)
类同条件，用重载
Response<T> getXXX(String code) |
1
2
3 | Response<T> getXXXById(Long id)
Response<T> getXXXByCode(String code) |
说明：
- API契约应该由”API名 + 入参”共同组成，而不是只靠”API名”说明一切。
- API方法支持获取单个详情的方式，可以通过入参字段名自解释。无需再用”By***”来额外标注。
- 不带”By***”声明的方法语义上更具有扩展性。
创建
1 | Response<T> saveXXX(...) //参照《阿里巴巴Java编码规范》 |
删除
1 | Response<T> removeXXX(...) //参照《阿里巴巴Java编码规范》 |
更新
1
2
3 | Response<T> updateXXX(...) //参照《阿里巴巴Java编码规范》
Response<T> updateXXXxxx(...) //更新主资源下的子资源 |
提审
1 | Response<T> submitXXX(...) |
审核
1 | Response<T> auditXXX(...) |
退回（退回到流程中的某一步）
1 | Response<T> returnXXX(...) |
撤销（退回到流程的第一步）
1 | Response<T> cancelXXX(...) |