服务API设计之——API命名规范

2019/08/23 14:19
阅读数 1.7K

API命名规范

命名风格


面向资源

同RESTful命名风格

在大型系统中,常以”业务领域”视角进行模块划分,以达到业务”高内聚低耦合”的效果。

“业务领域”必有”数据对象”沉淀,从宏观抽象的角度看,"数据对象"可统称为"资源",”业务领域”就是业务相近的”资源”的集合。

"资源"一定是业务抽象后的对象

  1. 可以是具体的数据对象:
    • 商品
    • 订单
    • 合同
    • 发票
    • 采购计划
    • etc
  2. 可以是抽象的对象概念:
    • 租户
    • 用户
    • 支付
    • 文件
    • 需求
    • etc

"业务领域"与"业务领域"之间的依赖,可理解为是对"资源"操作(读、写、通知)的依赖。

所以,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命名统一”动词”术语、”名词”术语。优点是能风格一致,经验复用。

详见政采云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命名参考

假设:未按资源划分Service(上下文未界定资源域)的情况

“XXX”指某一种资源,”xxx”指”XXX”下的子资源

分页查询

  • 正确实践
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)

说明:

  1. API契约应该由”API名 + 入参”共同组成,而不是只靠”API名”说明一切。
  2. API方法支持获取单个详情的方式,可以通过入参字段名自解释。无需再用”By***”来额外标注。
  3. 不带”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(...)
展开阅读全文
加载中
点击引领话题📣 发布并加入讨论🔥
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部