本文主要讲解“什么是API参数规范”，简单明了，易学易懂。请跟随边肖的思路，一起学习学习“API参数规范是什么”！
00-1010
【强制】字段名称用小驼峰风格
服务API的返回值强制进行一般打包，如Response。
回应的作用：
统一方法指示API调用是否成功。
当应用编程接口调用失败时，统一格式会反馈错误代码和错误消息。
统一响应易于重用调用者的经验和集成框架。
作为API调用方，它的编码吸引力很简单：
API调用是否成功；
当呼叫不成功时，提示副本是什么；
打电话的人不想：
不在乎API有多牛逼。
不要在意API可能抛出的各种异常，因此要做各种异常处理。
论当前回应的不统一
[新业务][强制]使用架构组定义的统一响应：zcyresponse。
目前业务端有自定义的Result/Response，风格和功能类似。有更好的设计可以推荐给架构组进行集成，以防止他们打开重复的新定义。
【强制】Service API返回值必须使用Response包装
错误做法
AbstractClass的缩写为脓肿类；
condi的缩写；命名为condi
这种任意缩写严重降低了代码的可读性。
00-1010 MAPK，V机制非常灵活，但这样的灵活性有巨大的负面影响。
Map的数据描述是模糊的，调用者和实现者之间需要有一个隐式的契约来解释支持哪些键以及每个键的值是什么类型。增加了双方的使用复杂度。
MapK，V无法验证。此外，第1条使用的复杂性使得在使用中非常容易出错。
带有映射类型字段的保留扩展性的设计并不优雅。
注意：参数的调用者自定义数据部分允许映射。API提供者不关心，不解析，只透明地传输。
00-1010正确练习
分页，以DTO模式包装查询条件。
双序列化的特点：
在Dubbo API的POJO类中，uid是不一致的：没关系。
在duoapi的POJO类中，字段的数量是不一致的：没关系，只要字段名和类型一致，数据就可以成功反序列化。
发送方的字段比接收方多：没关系。
发送方的字段比接收方少：没关系。
1 responsepagepaging XXX(query toq)错误的做法
1 responsepagepagingxxx(string name，Stringcode，LongorgId，LongcreatorId，IntegerpageNo，nb
sp;Integer PageSize)
以上错误实践缺点：
1、对于调用方来说，无论以什么条件查询，都需要逐个条件传参。
2、API对扩展不友好，一旦想增加查询条件，API就不兼容。
【推荐】DTO字段设置JSR303 Annotation进行基础校验
-
正确实践
1 2 3 |
public interface ZcyPayFacade {
Result<Boolean> 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(max = 50)
private String merchantName;
/** 订单标题（即商品名称），粗略描述用户的支付目的。如“喜士多（浦东店）消费”*/
@NotBlank
@Length(max = 256)
private String orderSubject;
/** 订单描述（即商品描述），可以对交易或商品进行一个详细地描述，比如填写"购买商品2件共15.00元"*/
@NotBlank
@Length(max = 128)
private String orderBody;
......
}
|
感谢各位的阅读，以上就是“API参数规范有哪些”的内容了，经过本文的学习后，相信大家对API参数规范有哪些这一问题有了更深刻的体会，具体使用情况还需要大家实践验证。这里是，小编将为大家推送更多相关知识点的文章，欢迎关注！
内容来源网络，如有侵权，联系删除，本文地址：https://www.230890.com/zhan/97032.html