webflux的探索与实战 - 零：风格约定

法欧特斯卡雷特_Official
238 阅读6分钟

零

约定归约定，遵守也是得看意志力。

尽信《书》，则不如无《书》。

风格约定

这次可能就没有那么的长篇大论了，毕竟风格约定，亦或者说代码规范这类的东西，实在没什么好说的。如果有你想看但是没看到的约定，你就假装它是大家常见的规范罢。

接口格式

首先讲一下有关Controller层对外界的返回值格式：

{
    "code": 0,
    "msg": "Success",
    "data": {
        "id": "114514",
        "username": "ForteScarlet",
        "gender": 0
    }
}

喜闻乐见的三段式返回值。

code代表响应结果码，0即成功，其他为失败。

msg代码响应消息。

data即响应的真实数据。

以及，这数据中的code和msg，与http response中的状态码和消息不同，仅仅代表业务层面的错误码或消息。而http响应码，该是什么也依旧是什么。服务器出错了，响应码就应该是500，没有权限之类的，就应该是401。

但是！ 这仅仅只是对外控制层，也就是常规意义上的 Controller ，或者说是web客户端调用的时候得到的响应值。通过前几篇大家应该知道，我们这是个微服务项目，有很多服务，有网关，有这个有那个。既然是个微服务项目，那么应当也存在服务之间的调用。我通常喜欢将这种服务接口称作 Api 接口或者 Resource接口。而对于这类“对内”服务接口，其返回值中，就是原原本本的数据 data，而不要携带 code 或者 msg，比如：

{
    "id": "114514",
    "username": "ForteScarlet",
    "gender": 0
}

为什么要这样呢？其实原因很简单：我曾思考，为什么不这样呢？本身服务间的接口就是数据的交互，原本就是把一个服务拆了出去罢了。既然在单机应用中，你不会让你的每个service interface的返回值是一个 Result 对象，那么为什么拆出去之后格式就变化了呢？

3b39c30cd6faf937d76bf7cbde4109ad.jpeg

RESTful

其实，在一开始的时候我也考虑过完全遵守RESTful规范，定义上明确的 GET POST PUT之类的接口。但是我之后又想了想，顺便参考了几篇帖子，最终我还是选择放弃这种想法。

因此，此项目还是仅仅以 GET POST 为主，只不过路径风格会稍微的美观一些。比如，删除用户也许会被定义为 /user/delete/{userId} 。

代码风格

至于其他的，我是真的想不出来还能说什么了，但是只有上述两个内容实在是太空荡了。所以这里简单说一下代码风格之类的吧。

其实代码风格也就是大家熟知的那样，大家可以参考家喻户晓的阿里规范（但是没必要完全遵守），并取出其中一些典型内容进行效仿即可。实际上，对于我个人来讲，我并不是对阿里规范中的全部内容都完全赞同，但是90%多的东西也是非常有参考价值的。

说一下我个人写代码时候的一些常见规范吧。

  • 对于一个类，需要有类描述和方法描述的文档注释；对于常量、不可变属性/字段，追加final修饰符，常量变量名尽量全大写。

  • 对于一个接口，需要对其所有抽象方法注明参数含义及返回值。实际上IDE也会推荐你这么做。

  • 对于列表，尽可能不去对其他方法返回的列表/集合等做任何修改，除非其明确表示其返回值为可变的。尽可能不对作为参数的列表/集合等做任何修改，除非你在方法注释说明中明确表示作为参数的列表/集合等会发生改变。

    有关这一点，我可能要多说两嘴。众所周知，kotlin中的列表/集合等内容是分为可变(mutable) 与 不可变(Immutable) 的，而在其他语言或者库中也常有这种设计，包括Java自己的Collections和Arrays中也有这样的内容。总有人说，不要去使用 Arrays.asList() 或者 Collections.emptyList()，因为有坑云云。但是我认为，毫无征兆的去对作为参数的内容进行修改，反而才是一种不规范。

    善用可变与不可变的特性，能够使得整个程序的效率更上一层楼。

  • 对于变量，善用final修饰符。

  • 对于Stream，减少仅有单层操作的Stream转化。如果你对列表的操作仅仅只有一层处理，比如仅仅只是一个.map(...) 或者 .filter(...)，那么你可能需要重新考虑，是否真的需要这么做。如果数据量非常少，那么不如通过工具类来完成这种操作，来避免额外的对象开销。

    是的，Stream很迷人，我无法否定。但是对于它的利用也不可过分泛滥。

  • 对于Null，尝试使用jetbrains中的 @NotNull 和 Nullable 注解进行约束，减少出错的可能。

  • 对于异常，业务中出现的问题直接通过异常抛出，不要把异常try-catch，然后悄无声息的将其做掉。除非你十分清楚你为什么这么做。

  • 对于代码，在任何你认为需要进行辅助说明的地方进行注释标注。虽然经常有人说：“好的代码本身就是注释，满屏的注释才是新手写的代码，真正高手的代码不需要注释”，但是我要告诉你，这是放屁。哦好吧，也许这句话某些层面上并没有错，但是你要明白，在工作中，并不是所有人的想法都像天才如你的头脑一样清晰。就算仅仅只是为了照顾他们也好，至少在一些较为复杂的逻辑中，为他们开一扇窗。

    答应我，好吗？

6c0e80a3247ff69f8f99d55c122a1181.jpeg

收尾

那么以上就是我暂时能想到的与《风格约定》相关的全部内容了。不知道你是否能看到这里呢？如果看到了，那么十分感激。

第零章的全部到这里就结束了，接下来的后续章节会随着这个项目的进展逐步更新，主要用作技术分享以及各种感悟，且会视情况发布在各个不同的平台，如果能帮助到因为同样问题而困扰的人就再好不过了。

a3d5e08534fecbcb495c8430d97caa2e.png

对于所有的技术总结文章，我也会像本篇一样，尽可能的附上所有我有所参考的文档链接，供大家参阅。

就是这样，感谢您的阅读，我们下一篇再见。

avatar
文章
阅读
粉丝