关于工作中复杂接口设计和治理

[clifftts]

有一个 service 层的下单业务接口，承载了各种业务下单功能，为了达到抽象和复用的目的，入参对象比较复杂，包含一些基本类型属性和一些对象属性，对象属性中又包含对象属性。 目前项目中使用 swagger 生成接口注释文档，因为不同的业务场景对同一个字段的必传，非必传要求是不一样的，所以不能简单的通过 @ApiModelProperty(required = true)来表达，人肉对接口，而且无法把内容沉淀， 请教各位大佬有没有好的方法 1.以某种方式或者借助某个工具能够在接口文档上体现这种场景校验的不同，让调用方能够看的懂 2.对于复杂业务接口抽象的应该如何把握尺度，既能兼顾抽象又能控制复杂度

[Jooooooooo]

看起来单接口承载了过多业务, 考虑按某种维度(比如场景)拆分吧.

[clifftts]

@Jooooooooo 之前我一直主张新开接口，这样场景很具体处理很方便，不过后来我也认同了去抽象。不拆分原因 1 领导认为主流程接口尽量复用，2 抽象的业务主流程大体一致，只是部分点会有差异，在一个接口里能更好识别不同业务的差异，3 目前场景比较多，业务组分了三个，每个业务组下还能细化出几个业务单元，如果接口拆分太散，维护起来麻烦，对接麻烦

[Jooooooooo]

@clifftts 领导不让拆就没办法了. 感觉只能老老实实维护一个详尽的接口文档让对接方看.

[IvanLi127]

在 controller 上按场景多写几个接口，分别定义，然后统一转发给现在这个接口？

[akira]

你这样理解，单一接口承担多个业务的时候，其实只是把路由工作从前面后移到接口里面去了而已。
这个大杂烩接口里面，设计成只做路由动作，实际业务转发到后续的接口处理，这样应该就会好很多了

[sagaxu]

单一接口，所有订单(包括未来的)都必填或都非必填的参数作为公共参数，每个类型订单提供一个不同的类型定义，

1. order 字段兼容不同类型，入口通过 orderType 来区分
或者 2. fooOrder, barOrder 使用不同的字段类区分

最不能忍的是，不同订单的非公共参数，放在同一个层级的同一个类型中，调用方哪怕只对接一个订单类型，也要从上百个字段里，一个个去抠怎么填

[night98]

定义抽象父类实现主流程可复用代码，可变业务部分抽象为子类方法，写一个调度工厂完成实现调用主流程+子类方法，controller 层使用不同 function 及入参 DTO ，打包转发给调度工厂实现

[clifftts]

@IvanLi127 controller 层还好，都是自己人写，但是 app 的后端是其他组来写对接的问题主要在这里，为什么不多拆接口，因为调用方跨组，希望 service 接口尽量复用，而不是每次新开接口，这样接口太多维护成本高

[clifftts]

@akira 即使设计一个单一接口作为路由，但是还是会涉及到一个抽象入参的设计，随着业务变化，参数还是会臃肿

[SmiteChow]

出多份文档，多简单的事情

[clifftts]

@sagaxu 当前订单模型结构整体是满足通用的，也在不同层级留有扩展字段，目前的复用是在字段层面，同一个字段可能不同业务的用法都会不同，或者不同业务在扩展对象里塞一个特性值，扩展本身就自带一层模糊的意思，只能通过注释来备注

[clifftts]

@SmiteChow 这个接口是老接口，把所有场景识别出来对老员工确实也有一定考验，另外公司搭建了接口管理平台，也是与 swagger 注解自动生成的，我是希望最好使用方能通过接口平台能看懂，把平台用起来，提高沟通效率，目前看 swagger 的注解无法满足我上述的问题中的差异场景字段是否必传的体现，当前也只能是通过文档了

[SmiteChow]

swagger 做不到的，它的粒度是 path ，它就不是为复杂接口服务的，而是 REST 。 我有一个折中的方案，把多份文档的链接放 swagger 的描述里。

[arvinsilm]

这个接口是老接口，把所有场景识别出来对老员工确实也有一定考验

感觉不趁早拆分的话，早晚有一天这个接口会变成没有任何人能改、敢改的状态

[kiotech]

听起来适合做接口版本控制，如：
/API/DoSomething
/API/V2/DoSomething
/API/V3/DoSomething

[akira]

@clifftts 你这样理解嘛，接口 A 要参数 abcd ，接口 B 要参数 adef ，要什么传什么就是了呀。其实本质上就是多个接口

[edward1987]

该抽象复用的是 service 的下单逻辑,而不是接口吧 接口参数应该固定,而不是分好几个版本

[clifftts]

@edward1987 抽象的肯定是内部逻辑，另外对外接口也应该尽量服用，不能来一个业务就开一个接口，这里不同的是场景而不是版本，这里不存在版本，接口必须向下兼容