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<K,V>機制非常靈活，但這樣的靈活卻是負作用巨大。

1. Map的數據說明是晦澀的，調用方、實現方之間需要具有隱式的契約解釋支持哪些Key，每個Key的Value是什么類型。增加了雙方的使用復雜度。

2. Map<K,V>不可被校驗。加之第1條的使用復雜度，導致使用上非常容易出錯。

3. 用Map類型字段做預留擴展性的設計都是不優雅的設計。

注：參數中的調用方自定義數據部分允許使用Map。API提供方不關系、不解析、只透傳。

【強制】業務對象/查詢條件用DTO封裝，禁止以入參方式平鋪字段。

• 正確實踐

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

Dubbo序列化特點：

• Dubbo API的POJO類中，UID不一致：沒關系。

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

• 發送方比接收方的字段多：沒關系。

• 發送方比接收方的字段少：沒關系。

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就不兼容。

【推薦】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參數規范有哪些這一問題有了更深刻的體會，具體使用情況還需要大家實踐驗證。這里是億速云，小編將為大家推送更多相關知識點的文章，歡迎關注！