【强制】字段名称用小驼峰风格
【强制】Service API 返回值必须使用 Response 包装
- Service API 返回值强制要求进行通用包装，例如：Response。
- Response 的作用：
- 统一方法表示 API 调用是否成功
- API 调用失败时，统一格式反馈错误 Code，错误 Message
- 统一的 Response 易于调用方经验复用，框架集成
- 作为 API 调用方，其编码诉求很简单：
- API 调用是否成功；
- 调用不成功时，提示文案是什么；
- 调用方几不想：
- 不想关心 API 内部有多牛逼
- 不想关心 API 可能会抛的各种 Exception，以及因此不得不做各种异常处理
- 关于当前不统一的 Response
- 【新业务】【强制】使用架构组定义的统一 Response：ZCY Response
- 目前业务方有自定义 Result/Response，风格和作用大同小异。有更好的设计可以自荐给架构组集成，杜绝各自开辟重复的新定义。
【强制】杜绝完全不规范的缩写，避免望文不知义。（国际通用缩写除外）
- 错误实践
- AbstractClass “缩写” 命名成 AbsClass;
- condition “缩写” 命名成 condi；
- 此类随意缩写严重降低了代码的可阅读性。
【强制】禁止使用 Map 作为参数类型
Map<K,V> 机制非常灵活，但这样的灵活却是负作用巨大。
- Map 的数据说明是晦涩的，调用方、实现方之间需要具有隐式的契约解释支持哪些 Key，每个 Key 的 Value 是什么类型。增加了双方的使用复杂度。
- Map<K,V> 不可被校验。加之第 1 条的使用复杂度，导致使用上非常容易出错。
- 用 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; ...... } |
【推荐】在客户端完成基础字段校验
- 方式 1：【推荐】自定义 Dubbo Filter 实现通用拦截、校验。
- 方式 2：【推荐】通过 Builder 模式构建入参对象。
- 方式 3：【不推荐】Dubbo 客户端参数校验，要求 consumer 方设置 validation=”true”，Dubbo 客户端参数校验。缺点：以抛异常方式处理校验失败，需要业务方额外处理 Exception。而且，IDE 并不会提示 consumer 方需要处理 ConstraintViolationException。
- 方式 4：Dubbo 方式，local-stub 特性。实现较复杂，校验代码通用性低。Dubbo local-stub
