微服务开发系列：设计一个统一的 http 接口内容形式

源码地址

微服务开发系列：开篇
微服务开发系列：为什么选择 kotlin
微服务开发系列：为什么用 gradle 构建
微服务开发系列：目录结构，保持整洁的文件环境
微服务开发系列：服务发现，nacos 的小补充
微服务开发系列：怎样在框架中选择开源工具
微服务开发系列：数据库 orm 使用
微服务开发系列：如何打印好日志
微服务开发系列：鉴权
微服务开发系列：认识到序列化的重要性
微服务开发系列：设计一个统一的 http 接口内容形式
微服务开发系列：利用异常特性，把异常纳入框架管理之中
微服务开发系列：利用 knife4j，生成最适合微服务的文档

1 统一接口格式

所有有关于接口返回的数据格式，都定义在 framework:cn/framework/common/http 包路径下。

1.1 MessageType

系统中为了方便直观的使用，对所有 HTTP code 做了拦截，除了网络错误的请求，前端不再需要判断 404、500 等错误，只需要根据 MessageType 判断是否成功。

定义返回的消息类型，直接确定下来前端根据这个消息类型去打印不同的信息。

目前只定义了 WARNING、SUCCESS、ERROR 三种消息类型，并且定义了相应的消息内容，可以根据业务场景的增加扩展。

1.2 RequestResult

所有返回到前端的数据格式，都必须为此格式。

关键字段：

1. MessageType type，信息类型，默认为成功
2. String message，消息内容，如果为空使用 MessageType 中自带的消息内容
3. String reason，错误消息，用于在发生异常时，携带异常信息，不能用于展示给客户端
4. Long code，行动码，用于与前端交互，改变行为，没有可不设置，使用 type 代替就可以
5. LocalDateTime time，变量生成时间，用于协助判断问题
6. Object value，真正返回的业务数据，可以是任何可被序列化的数据

拥有统一的数据格式，前端才能更好统一的处理信息。

1.3 InnerExp

内部异常，用于方便返回结果到前端。

对于内部异常，和其它异常的分析，放在下一篇《利用异常特性，把异常纳入框架管理之中》单独讲述。

2 http status code

http 的协议中，定义了很多状态码。

但是我认为在一般的前后端的业务交互上，我们不需要这么多状态码，这些状态码，更多的是给还未到达后端的请求准备的。

例如有些请求在 nginx 这一层就出现异常，此时 nginx 就可以根据一些情况返回对应的状态码，因为像 nginx 这种中间件，它要满足更加标准化的情况。

对此，框架中设计的消息返回状态码，只要是到达了后端，一律返回 200，消息只分为成功、失败、警告三种。

如果有更加复杂的场景，需要前端针对不同的异常类型，作为不同的反应，例如登录失败的原因是密码错误还是密码到期，上面的返回消息体中，也可以自定义 code。

这样不仅简化了后端的处理方式，也大大降低了前端的处理难度。

前端获取的 response 只要是非 200 的，证明肯定不是后端出现了问题，将错误信息统一处理。

针对 200 消息可以做统一的拦截处理，针对错误、警告消息做出回应，成功消息放行。

我们不需要对没有使用正统的 http code 这件事耿耿于怀，任何能够简化我们开发的方式，都是一种好方式，以当下的事实环境来设计开发方式，如果未来不满足，再重新设计。