API参数规范有哪些

　　

这篇文章主要讲解了“API参数规范有哪些”，文中的讲解内容简单清晰，易于学习与理解，下面请大家跟着小编的思路慢慢深入，一起来研究和学习“API参数规范有哪些”吧！

【强制】字段名称用小驼峰风格

【强制】Service API返回值必须使用Response包装

• Service API返回值强制要求进行通用包装，例如：Response。

• Response的作用：

1. 统一方法表示API调用是否成功

2. API调用失败时，统一格式反馈错误Code，错误Message

3. 统一的Response易于调用方经验复用，框架集成

• 作为API调用方，其编码诉求很简单：

1. API调用是否成功；

2. 调用不成功时，提示文案是什么；

• 调用方几不想：

1. 不想关心API内部有多牛逼

2. 不想关心API可能会抛的各种Exception，以及因此不得不做各种异常处理

• 关于当前不统一的Response

• 【新业务】【强制】使用架构组定义的统一Response：ZCY Response

• 目前业务方有自定义Result/Response，风格和作用大同小异。有更好的设计可以自荐给架构组集成，杜绝各自开辟重复的新定义。

【强制】杜绝完全不规范的缩写，避免望文不知义。（国际通用缩写除外）

• 错误实践

• AbstractClass“缩写”命名成 AbsClass;

• condition“缩写”命名成 condi；

• 此类随意缩写严重降低了代码的可阅读性。

【强制】禁止使用 Map 作为参数类型

Map机制非常灵活，但这样的灵活却是负作用巨大。

1. Map的数据说明是晦涩的，调用方、实现方之间需要具有隐式的契约解释支持哪些Key，每个Key的Value是什么类型。增加了双方的使用复杂度。

2. Map不可被校验。加之第1条的使用复杂度，导致使用上非常容易出错。

3. 用Map类型字段做预留扩展性的设计都是不优雅的设计。

注：参数中的调用方自定义数据部分允许使用Map。API提供方不关系、不解析、只透传。

【强制】业务对象/查询条件用DTO封装，禁止以入参方式平铺字段。

• 正确实践

分页查询，将查询条件以DTO方式包装。

Dubbo序列化特点：

• Dubbo API的POJO类中，UID不一致：没关系。

• Dubbo API的POJO类中，字段数量不一致：没关系，只要字段名和类型一致，数据能反序列化成功。

• 发送方比接收方的字段多：没关系。

• 发送方比接收方的字段少：没关系。

1

Response pagingXXX(QueryDTO q)

• 错误实践

1

Response pagingXXX(String name, String code, Long orgId, Long creatorId, Integer pageNo, Integer PageSize)

以上错误实践缺点：
1、对于调用方来说，无论以什么条件查询，都需要逐个条件传参。
2、API对扩展不友好，一旦想增加查询条件，API就不兼容。

【推荐】DTO字段设置JSR303 Annotation进行基础校验

• 正确实践

1
　　2
　　以前3  <>之前public  interface  ZcyPayFacade  {
　　,,,Result, validTradePay (@NotNull  @Valid  TradePayPO  tradePayPO);
　　}

 1
　　2
　　3.
　　4
　　5
　　6
　　7
　　8
　　9
　　10
　　11
　　12
　　13
　　14
　　15
　　16
　　17
　　18
　　19
　　20.
　　21
　　22
　　23
　　24
　　25
　　26
　　27
　　28
　　29
　　30.
　　31
　　32
　　33
　　34
　　35 

<>以前public  class  TradePayPO  implements  Serializable  { 　　 　　,,@NotBlank 　　,,,@Length (=max  15) 　　,,,/* *,业务交易编号(订单编号),*/,,,private  String  businessTradeNo; 　　 　　,,,/* * 　　,,,,*,业务渠道:1 -订阅,2-CA 　　,,,,*,@see  BusinessTypeEnum 　　,,,, 　　,,,*,*/,,@NotNull 　　,,,@Range (min =, 1,, max =, 2) 　　,,,private  Integer  businessType; 　　 　　,,…… 　　,,,, 　　,,,/* *,商户名称商(家),*/,,@NotBlank 　　,,,@Length (50)=max  　　,,,private  String  merchantName; 　　 　　,,,/* *,订单标题(即商品名称),粗略描述用户的支付目的。如“喜士多(浦东店)消费”*/,,@NotBlank 　　,,,@Length (max =, 256) 　　,,,private  String  orderSubject; 　　 　　,,,/* *,订单描述(即商品描述),可以对交易或商品进行一个详细地描述,比如填写“购买商品2件共15.00元“*/,,@NotBlank 　　,,,@Length (max =, 128) 　　,,,private  String  orderBody; 　　 　　,,…… 　　}

API参数规范有哪些