数据访问接口设计思考

以你之姓@ 2022-08-08 06:15 159阅读 0赞

# 数据访问接口设计思考 #

这题目有点大，但我也没想到一个更好的题目，先这么用着。老规矩，先说背景。本周遇到了一个难题，如下：某entity有add和update两个接口，add和update的参数基本一致(add时无id，update时有id，其他基本一致)。该entity有个字段A是Date类型，非必填项。如果add时传了这个字段，那么update的时候，没有办法把字段A给修改为NULL。为什么没办法呢？往下看。

--------------------

## 接口设计现状 ##

我们主要着眼在控制层的逻辑

### 基础类APIController ###

/** * 提供接口的基础服务如获取请求、鉴权、获取DTO */
    public class APIController extends Controller {    
        ……
        /** * 获取请求的DTO * @param <T> * @return object */
        public static <T> T getDTO(Class<T> clazz) {
            JsonObject requestJsonData = (JsonObject) getDataOfJson();
            /** * 省略具体处理逻辑 */
        }
        public static JsonElement getDataOfJson() {
            ……
        }
    
    }

### 具体实体的Controller ###

/** * 事件实体的控制类，提供add和update方法 */
    public class Event extends APIController { 
        ……
        public static void update() {
            ……    
            // 获取参数，只是为了验证是否有传递该参数，该字段对请求结果不影响，仅为了安全，防猜密钥之用途。
            @SuppressWarnings("unused")
            EventUpdateRequestDTO eventRequest = getDTO(EventUpdateRequestDTO.class);
            updateEvent(eventRequest);
        }
        ……
        private static void updateEvent(EventUpdateRequestDTO request) {
            ……
            // new Event
            Event event = EventService.getById(request.getEventId());
            if (event == null) {
                helper.returnError("5000005", "eventId does not exist.");
            }
            ……
            if (request.getPrvEventId() != null) {
                event.setPrvEventId(request.getPrvEventId());
            }
            /** * 省略具体字段的处理，对所有的字段都是在不为NULL的时候set */
            if (request.getSource() != null) {
                event.setSource(request.getSource());
            }
            ……
        }
    
    }

从以上两段代码中可以看出，具体entity的Controller是通过父类的getDTO方法来拿到请求类的，由于父类封装了这个过程，在具体entity的Controller里，是不知道原始请求信息中是没传这个字段呢，还是传了但传的是NULL。update时，对所有的字段都统一粗暴地进行NULL判断，不为NULL时才set。于是本文开头的问题就很好理解了，对于一开始在add时就有值的字段，无法将其update成NULL。

## 为什么要跟NULL过不去 ##

是的，我们在思考解决方案之前，要先回答这个问题。为什么我们要跟NULL过不去，为什么非要在update时将一个已有值的字段设置为NULL。我给出的答案如下：

*  有业务场景需要，如本文例子中的event，该实体仅在特定状态下需要有endTime(Date类型)字段，其他状态下若保留endTime会造成干扰和误解。因此，有这样的业务需求在update时清空已有字段。
 *  即使目前没有业务场景需要，但接口功能还是得齐备。**我可以不用，但你不能没有**。万一我哪天就想用了呢？
    
    **所以，还是得解决这个问题。**

## 几种可能的解决方案 ##

### 特殊处理法 ###

实在是有这样的字段，那就特殊处理好了。比如可以这样：

// 对endTime做特殊处理
        if (request.getEndTime() != null) {
            event.setEndTime(new Date(request.getEndTime() * 1000));
        } else {
            // 不传或传null的时候，将endTime设置为null(因为只有开测状态的大事件有结束时间，其他状态不需要结束时间)
            event.setEndTime(null);
        }

也可以这样：

// 对endTime做特殊处理
        if (request.getEndTime() != null) {
            // 传特殊时间表示需要置为NULL
            if (request.getEndTime().longValue() == 0L) {
                event.setEndTime(null);
            } else {
                event.setEndTime(new Date(request.getEndTime() * 1000));    
            }            
        }

and so on。总之，针对这个字段做一些特殊的约定和处理。这样解决的好处是改动小(未涉及接口框架的改动，也不牵连其他字段)，坏处是埋坑。我们讨厌特殊处理，很大程度上是因为特殊处理需要人的特殊注意，容易出错。这段特殊处理的代码放在这里，其实就是埋了一个坑，指不定哪天就掉进去了。

### 修改接口协议 ###

这里的接口协议指的是整体api的所有update接口协议。原本我们的协议是，update时仅传需要修改的字段。那我们改一下，改成和add类似的“全量”update，即update时需要传这个实体所有的字段值（即使有些字段没有修改）。这样的优点显而易见，不再存在无法清空某一字段的问题，想改成啥都行；缺点也一样显而易见，update接口交互的内容增多，很多不需要修改的值也传来传去的，浪费网络流量。再者，针对目前遇到的这个问题，这个方法不具备可行性，因为接口已经大规模铺开应用，修改接口协议不现实。如果是完全从头设计新接口，倒是可以考虑下这种方案。

### 修改基础类APIController ###

【写在前面的话】这个解决方案纯粹是我异想天开。所以这一小节的标题是“几种可能的解决方案”，仅仅只是可能。看完如果觉得搞笑，哈哈一笑就好，不要当真。嗯，因为我自己都觉得挺搞笑，或者说不现实。

我的想法是，既然是APIController的getDTO方法屏蔽了请求的细节(如参数是传了还是没传)，那为什么不改写getDTO这个方法呢？哪里跌倒哪里爬起来，这个方法里就搞清楚请求原内容是什么，返回的DTO也要做相应修改。异想天开的地方来了：

public class EventUpdateRequestDTO { 
        ……
        // 请求里有没有传endTime
        private boolean endTimeFlag;
        // endTime的内容
        private Long endTime;
        ……
    }

getDTO的职责就是解析请求，根据实际情况设置每个字段的两个相关属性（传了没，如果传了值是啥）。

这种方法（虽然getDTO的逻辑我没有贴，还没时间写）可以解决本文开头提出的问题。优点就是，接口协议不用修改，不影响关联方，即使接口已经铺开使用了也没事。缺点是，如果一个entity有N个字段的话，那requestDTO里就会有2\*N个属性，代码量大增，开发复杂度上来了。另外就是我觉得这个方案有点搞笑，冗余、不优雅。

## 总结 ##

其实对于这个问题，我现在没有一个特别倾向的答案。由于项目时间的关系，目前我们采用的是特殊处理法（心不甘情不愿地埋了一个坑）。剩余两个解决方案也不太好。写这个文章，其实也是希望把问题摆出来，大家一起探讨怎么优雅地解决这个接口设计的问题。