服務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)

以上錯誤實踐缺點：
一、對於調用方來講，不管以什麼條件查詢，都須要逐個條件傳參。
二、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; ...... }

【推薦】在客戶端完成基礎字段校驗

• 方式1：【推薦】自定義Dubbo Filter實現通用攔截、校驗。
• 方式2：【推薦】經過Builder模式構建入參對象。
• 方式3：【不推薦】Dubbo 客戶端參數校驗，要求consumer方設置validation=」true」，Dubbo 客戶端參數校驗。缺點：以拋異常方式處理校驗失敗，須要業務方額外處理Exception。並且，IDE並不會提示consumer方須要處理ConstraintViolationException。
• 方式4：Dubbo方式，local-stub特性。實現較複雜，校驗代碼通用性低。Dubbo local-stub

---

注：此規範與《阿里巴巴Java編碼規範》互補，同時有效。