這篇文章主要講解了“API參數(shù)規(guī)范有哪些”，文中的講解內(nèi)容簡(jiǎn)單清晰，易于學(xué)習(xí)與理解，下面請(qǐng)大家跟著小編的思路慢慢深入，一起來研究和學(xué)習(xí)“API參數(shù)規(guī)范有哪些”吧！

成都創(chuàng)新互聯(lián)專注于企業(yè)成都全網(wǎng)營銷、網(wǎng)站重做改版、克山網(wǎng)站定制設(shè)計(jì)、自適應(yīng)品牌網(wǎng)站建設(shè)、H5網(wǎng)站設(shè)計(jì)、成都做商城網(wǎng)站、集團(tuán)公司官網(wǎng)建設(shè)、成都外貿(mào)網(wǎng)站建設(shè)公司、高端網(wǎng)站制作、響應(yīng)式網(wǎng)頁設(shè)計(jì)等建站業(yè)務(wù)，價(jià)格優(yōu)惠性價(jià)比高，為克山等各大城市提供網(wǎng)站開發(fā)制作服務(wù)。

【強(qiáng)制】字段名稱用小駝峰風(fēng)格

【強(qiáng)制】Service API返回值必須使用Response包裝

• Service API返回值強(qiáng)制要求進(jìn)行通用包裝，例如：Response。

• Response的作用：

1. 統(tǒng)一方法表示API調(diào)用是否成功

2. API調(diào)用失敗時(shí)，統(tǒng)一格式反饋錯(cuò)誤Code，錯(cuò)誤Message

3. 統(tǒng)一的Response易于調(diào)用方經(jīng)驗(yàn)復(fù)用，框架集成

• 作為API調(diào)用方，其編碼訴求很簡(jiǎn)單：

1. API調(diào)用是否成功；

2. 調(diào)用不成功時(shí)，提示文案是什么；

• 調(diào)用方幾不想：

1. 不想關(guān)心API內(nèi)部有多牛逼

2. 不想關(guān)心API可能會(huì)拋的各種Exception，以及因此不得不做各種異常處理

• 關(guān)于當(dāng)前不統(tǒng)一的Response

• 【新業(yè)務(wù)】【強(qiáng)制】使用架構(gòu)組定義的統(tǒng)一Response：ZCY Response

• 目前業(yè)務(wù)方有自定義Result/Response，風(fēng)格和作用大同小異。有更好的設(shè)計(jì)可以自薦給架構(gòu)組集成，杜絕各自開辟重復(fù)的新定義。

【強(qiáng)制】杜絕完全不規(guī)范的縮寫，避免望文不知義。（國際通用縮寫除外）

• 錯(cuò)誤實(shí)踐

• AbstractClass“縮寫”命名成 AbsClass;

• condition“縮寫”命名成 condi；

• 此類隨意縮寫嚴(yán)重降低了代碼的可閱讀性。

【強(qiáng)制】禁止使用 Map 作為參數(shù)類型

Map機(jī)制非常靈活，但這樣的靈活卻是負(fù)作用巨大。

1. Map的數(shù)據(jù)說明是晦澀的，調(diào)用方、實(shí)現(xiàn)方之間需要具有隱式的契約解釋支持哪些Key，每個(gè)Key的Value是什么類型。增加了雙方的使用復(fù)雜度。

2. Map不可被校驗(yàn)。加之第1條的使用復(fù)雜度，導(dǎo)致使用上非常容易出錯(cuò)。

3. 用Map類型字段做預(yù)留擴(kuò)展性的設(shè)計(jì)都是不優(yōu)雅的設(shè)計(jì)。

注：參數(shù)中的調(diào)用方自定義數(shù)據(jù)部分允許使用Map。API提供方不關(guān)系、不解析、只透?jìng)鳌?/p>

【強(qiáng)制】業(yè)務(wù)對(duì)象/查詢條件用DTO封裝，禁止以入?yún)⒎绞狡戒佔(zhàn)侄巍?/h4>

• 正確實(shí)踐

分頁查詢，將查詢條件以DTO方式包裝。

Dubbo序列化特點(diǎn)：

• Dubbo API的POJO類中，UID不一致：沒關(guān)系。

• Dubbo API的POJO類中，字段數(shù)量不一致：沒關(guān)系，只要字段名和類型一致，數(shù)據(jù)能反序列化成功。

• 發(fā)送方比接收方的字段多：沒關(guān)系。

• 發(fā)送方比接收方的字段少：沒關(guān)系。

1	Response> pagingXXX(QueryDTO q)

• 錯(cuò)誤實(shí)踐

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

以上錯(cuò)誤實(shí)踐缺點(diǎn)：
1、對(duì)于調(diào)用方來說，無論以什么條件查詢，都需要逐個(gè)條件傳參。
2、API對(duì)擴(kuò)展不友好，一旦想增加查詢條件，API就不兼容。

【推薦】DTO字段設(shè)置JSR303 Annotation進(jìn)行基礎(chǔ)校驗(yàn)

• 正確實(shí)踐

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)
    /** 業(yè)務(wù)交易編號(hào)(訂單編號(hào)) */
    private String businessTradeNo;

    /**
     * 業(yè)務(wù)渠道：1-訂閱，2-CA
     * @see BusinessTypeEnum
     *
     * */
    @NotNull
    @Range(min = 1, max = 2)
    private Integer businessType;

    ......
    
    /** 商戶名稱(商家) */
    @NotBlank
    @Length(max = 50)
    private String merchantName;

    /** 訂單標(biāo)題（即商品名稱），粗略描述用戶的支付目的。如“喜士多（浦東店）消費(fèi)”*/
    @NotBlank
    @Length(max = 256)
    private String orderSubject;

    /** 訂單描述（即商品描述），可以對(duì)交易或商品進(jìn)行一個(gè)詳細(xì)地描述，比如填寫"購買商品2件共15.00元"*/
    @NotBlank
    @Length(max = 128)
    private String orderBody;

    ......
}

感謝各位的閱讀，以上就是“API參數(shù)規(guī)范有哪些”的內(nèi)容了，經(jīng)過本文的學(xué)習(xí)后，相信大家對(duì)API參數(shù)規(guī)范有哪些這一問題有了更深刻的體會(huì)，具體使用情況還需要大家實(shí)踐驗(yàn)證。這里是創(chuàng)新互聯(lián)，小編將為大家推送更多相關(guān)知識(shí)點(diǎn)的文章，歡迎關(guān)注！