java前后端接口文档_前后端交互接口设计规范

在开发web应用的时候，往往会涉及到一个问题，前端后接口定义的问题。接口定义设计的好坏很大程度上能影响一个项目的进度和可扩展性。但是前辈们在这个问题上留下了非常宝贵的一些常规的设计思路，值得我们参考。

1、后端设计统一的返回模型

在与前端的交互过程中，我们最好统一一个通用的对象模型，避免一个接口返回一个模型，减少前端同学繁杂的工作量和沟通成本，类似如下：

code为返回的编码，一般分为成功的编码和错误的编码，比如code=200为请求成功，非200为失败，在失败的情况下message有具体的失败信息，data是请求的真正的返回结果，比如我们要返回的是一个list的对象，就把data设置为list，这也是把data的类型设置为Object的缘由，因为在java中一切对象继承自Object。

在设计了通用的对象模型后，还涉及到另外一个问题，接口文档怎么写？且看我一一道来。

一般会在开头部分有个总体说明类似：

public class RestResponse {private int code; private String message; private Object data;}code为200为请求成功 非200即为异常，异常信息在message中，data为请求返回的数据Content-Type: application/json

然后是每个接口的详细信息，类似：

url: /punishInfo/updatePunishInfoHTTP请求方式：POST请求参数：public class UpdatePunishInfoRequest {private long id; //惩罚id private boolean active; //是否有效}返回对象：RestResponse

最后还有个附录部分介绍详细的错误码等信息，类似：

2、后端处理所有的异常信息，避免把异常抛到前台

你是不是曾经也遇到过访问一个web网站的时候，直接报什么exception，要是这exception暴露出你生产机器的数据库连接信息的话，你可能会被老板炒鱿鱼的。一般的做法是写一个@ControllerAdvice标记的controller，结合@ExceptionHandler统一处理运行时异常，然后返回给前端一个异常错误码和错误的详细信息。

3、善用一些开源的接口开源框架

说到写接口文档，有的时间我们可能新增或者修改文档，在修改代码的同时再去修改文档这是大多数程序员不想干的事情，Swagger框架帮我们解决了这个问题，具体怎么使用，如果大家有兴趣，下次可以再介绍。善用工具，事半功倍。

实现java多线程的几种方式

java 集合类(一)

java 集合类之List(二)

java集合类之Set(三)