API参数规范有哪些

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

成都创新互联专注于企业成都全网营销、网站重做改版、克山网站定制设计、自适应品牌网站建设、H5网站设计成都做商城网站、集团公司官网建设、成都外贸网站建设公司、高端网站制作、响应式网页设计等建站业务,价格优惠性价比高,为克山等各大城市提供网站开发制作服务。

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

【强制】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(max = 50)
    private String merchantName;

    /** 订单标题(即商品名称),粗略描述用户的支付目的。如“喜士多(浦东店)消费”*/
    @NotBlank
    @Length(max = 256)
    private String orderSubject;

    /** 订单描述(即商品描述),可以对交易或商品进行一个详细地描述,比如填写"购买商品2件共15.00元"*/
    @NotBlank
    @Length(max = 128)
    private String orderBody;

    ......
}

感谢各位的阅读,以上就是“API参数规范有哪些”的内容了,经过本文的学习后,相信大家对API参数规范有哪些这一问题有了更深刻的体会,具体使用情况还需要大家实践验证。这里是创新互联,小编将为大家推送更多相关知识点的文章,欢迎关注!


本文题目:API参数规范有哪些
网站地址:http://scyanting.com/article/pejcod.html