为什么阿里巴巴Java开发手册中强制要求接口返回值不允许使用枚举

Posted 2023-04-02 Javaesandyou

在阅读《阿里巴巴Java开发手册》时，发现有一条关于二方库依赖中接口返回值不允许使用枚举类型的规约，具体内容如下：

在谈论为什么之前先来科普下什么是二方库，二方库也称作二方包，一般指公司内部发布到中央仓库，可供公司内部其他应用依赖的库（jar 包）。

那么一方库便是本工程内部子项目模块依赖的库；三方库为公司之外的开源库，比如像 fastjson、easyexcel 这种。

下面我们就通过一个例子来看下为什么阿里巴巴不允许返回枚举类型或者包含枚举类型的 POJO 对象。

比如星巴克提供了 0.0.1 版本的二方库，定义了一个 Starbucks 类，里面包含了枚举类型的 SizeEnum，里面分别是中杯、大杯、特大杯。

定义了一个服务类，实现了根据 id 获取星巴克的方法：

然后，星巴克的门店引入 0.0.1 这个版本 jar 包，然后卖的好好的：

有一天，老罗说要那个中等大小的中杯拿铁，但是服务员说那是大杯，经过一番争论，罗老师很是生气。

于是星巴克升级到了 0.0.2 版本二方库，在枚举类 SizeEnum 中新增了小杯，升级后的枚举类如下：

同时服务类的接口方法也做了相应修改：

由于星巴克的门店比较多，有的还不知道这个新加的需求，因此返回结果中出现了 SHORT，但是 0.0.1 版本的二方库中没有小杯啊，所以就出问题了，也就是序列化失败。

通过这个例子，我相信大家对枚举类型作为返回结果有了一定的理解，下面引用孤尽大佬在知乎的回答：

由于升级原因，导致双方的枚举类不尽相同，在接口解析，类反序列化时出现异常。

Java 中出现的任何元素，在 Gosling 的角度都会有背后的思考和逻辑（尽管并非绝对完美，但 Java 的顶层抽象已经是天才级了），比如：接口、抽象类、注解、和本文提到的枚举。枚举有好处，类型安全，清晰直接，还可以使用等号来判断，也可以用在 switch 中。它的劣势也是明显的，就是不要扩展。可是为什么在返回值和参数进行了区分呢，如果不兼容，那么两个都有问题，怎么允许参数可以有枚举。当时的考虑，如果参数也不能用，那么枚举几乎无用武之地了。参数输出，毕竟是本地决定的，你本地有的，传送过去，向前兼容是不会有问题的。但如果是接口返回，就比较恶心了，因为解析回来的这个枚举值，可能本地还没有，这时就会抛出序列化异常。

比如：你的本地枚举类，有一个天气 Enum：SUNNY, RAINY, CLOUDY，如果根据天气计算心情的方法：guess(WeatcherEnum xx)，传入这三个值都是可以的。返回值：Weather guess(参数)，那么对方运算后，返回一个 SNOWY，本地枚举里没有这个值，傻眼了。

对了，在这里说一下，我目前是在职Java开发，如果你现在正在学习Java，了解Java，渴望成为一名合格的Java开发工程师，在入门学习Java的过程当中缺乏基础入门的视频教程，可以关注并私信我：01。获取。我这里有最新的Java基础全套视频教程。

阿里巴巴Java开发手册-注释规约

1. 【强制】类、类属性、类方法的注释必须使用Javadoc规范，使用/**内容*/格式，不得使用//xxx方式。 

说明：在IDE编辑窗口中，Javadoc方式会提示相关注释，生成Javadoc可以正确输出相应注释；在IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。

2. 【强制】所有的抽象方法（包括接口中的方法）必须要用Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。 

说明：对子类的实现要求，或者调用注意事项，请一并说明。

3. 【强制】所有的类都必须添加创建者信息。

4. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。

5. 【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。

6. 【推荐】与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。 

反例：“TCP连接超时”解释成“传输控制协议连接超时”，理解反而费脑筋。

7. 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。 

说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。

8. 【参考】注释掉的代码尽量要配合说明，而不是简单的注释掉。 

说明：代码被注释掉有两种可能性：

1）后续会恢复此段代码逻辑。

2）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码）。

9. 【参考】对于注释的要求：

第一、能够准确反应设计思想和代码逻辑；

第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。

10. 【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。 

反例：

// put elephant into fridge

put(elephant, fridge);

方法名put，加上两个有意义的变量名elephant和fridge，已经说明了这是在干什么，语义清晰的代码不需要额外的注释。

11. 【参考】特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。 

1） 待办事宜（TODO）:（ 标记人，标记时间，[预计处理时间]） 表示需要实现，但目前还未实现的功能。这实际上是一个Javadoc的标签，目前的Javadoc还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个Javadoc标签）。 

2） 错误，不能工作（FIXME）:（标记人，标记时间，[预计处理时间]） 在注释中用FIXME标记某代码是错误的，而且不能工作，需要及时纠正的情况。