服务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编码规范》互补，同时有效。