接口开发总结

接口开发总结

1.什么是接口？

我理解的接口其实就是系统对外提供的服务，客户端(浏览器、手机APP、微信小程序)通过接口的请求地址请求接口，并传入接口约定好的参数，然后接口进行业务逻辑处理，最后按照约定好的数据格式返回数据。(看到这里，大家是不是觉着接口和咱们项目里面Controller类里的写的方法很像。没错，在这里你可以简单的理解为，接口就是咱们项目里Controller类里面写的一个个的请求方法。）

2.如何统一接口返回的数据格式？如何统一接口的返回值？

当时我们自己封装了一个ServerResponse类，这个类里面包含code,message,data三项属性，其中code代表业务操作状态码，message代表业务操作状态码的含义，data代表接口具体返回的数据。这样我们在Controller层的各个方法中，统一返回的都是我们自定义的ServerResponse对象。另外为了方便进行堆code和message的统一赋值对我们还自定义了一个枚举类ResponseEnum。这个枚举类里其实就是定义了每一个业务操作状态码及业务操作状态码对应的含义。

3.接口文档存在的意义？

第一可以方便前端开发人员和后端开发的人员的沟通交流，提高了工作效率吧。第二呢我觉着万一项目组成员发生了变更，后面替上来的人也可以通过接口文档很快的上手工作。

4.接口文档里包含哪些东西？如何编写接口文档呢？

在编写接口文档时通常需要写清楚接口的业务描述，接口的请求地址，请求方式，请求参数的类型，是否含有头信息，请求参数的含义以及接口的响应格式【json/xml】，响应内容，响应内容的各个字段含义。最开始写接口文档的时候我都是用最传统的方法写的，就是很笨的建了一个文档然后在里面写上接口的业务描述，接口的请求地址啊，请求方式啊，请求参数的类型啊，是否含有头信息，请求参数的含义以及接口的响应数据格式【json/xml】，响应内容，响应内容的各个字段含义等等之类的。后来我了解到原来有一个叫Swagger的接口文档工具，用完之后感觉太方便了，它就只需要在项目的接口上面加上一些简单的注解，就可以自动的生成接口文档。

5.你怎么做的接口开发？

我在之前工作的过程中，我们的经理给我说，我们项目需要给前台提供RESTful接口,当时对这个RESTful只是了解并没有真正的在项目中使用过,所以下去我也查阅了许多关于RESTful接口开发的文档,通过文档得知,restful是ROA面向资源编程的一种设计风格，RESTful不是一项新技术,其实就是符合RESTful风格的url,都被称之为RESTful类型的接口,因为在互联网中可以通过url去访问任意的资源,比如：文章、图片、视频等,像这个RESTful在使用的时候就要注意，路径中不能出现动词，最好是名词并且要以复数的形式出现，RESTful是基于HTTP协议现有的Get动作进行查询，Post动作进行增加，Put动作进行修改，Delete动作进行删除。

经过了解之后，我就开始了基于SpringMVC进行restful接口项目的开发。开发时用到的注解有 @RestController @PathVariable @RequestBody @Value @RestControllerAdvice这些，其中 @RestController就相当于 @Controller 和 @ResponseBody的组合体，这样就可以避免在各个方法上加入 @ResponseBody注解了，@ResponseBody的作用是将java对象转换为对应的json格式，默认使用的是Jackson这个第三方的工具包，这个注解的本质说白了就是通过Jackson将java对象转换为对应的json格式的字符串并且通过response获取输出流将json格式的字符串响应给客户端，想要使@ResponseBody起作用除了要在maven的pom文件中导入jackson的依赖外还需要在spring的配置文件中加入<mvc:annotation-driven/>，@PathVariable是为了从路径中获取参数信息比如在删除操作的时候就需要从路径中获取id信息， @RequestBody起到的作用和@ResponseBody看好相反，就是将前端提交过来的json格式的数据，自动转换为对应的java对象；@Value可以从属性文件中根据key获取对应的信息，比如我们可以把调用第三方接口时需要的信息以键值对的形式写到自定义的属性文件中，然后通过context:property-placeholder加载属性文件并且通过@Value根据key找到指定的值，这样可以避免程序中出现硬编码，提高程序代码的可维护性。对于@RestControllerAdvice来说它的作用就是异常的统一处理，就相当于@ResponseBody和@ControllerAdvice的结合体,我们项目中异常的统一处理就是用它来完成的。

我们当时采用的是JSON格式的数据作为RESTful风格接口的响应结果，其中用code表示状态码，用message表示提示信息，用data表示返回的数据。为了方便返回的指定格式的JSON数据，我们自己封装了一个ServerResponse类，这个类里面包含code,message,data三项属性，其中code代表业务操作状态码，message代表业务操作状态码的含义，data代表接口具体返回的数据。这样我们在Controller层的各个方法中，统一返回的都是我们自定义的ServerResponse对象。另外为了方便进行堆code和message的统一赋值对我们还自定义了一个枚举类ResponseEnum。这个枚举类里其实就是定义了每一个业务操作状态码及业务操作状态码对应的含义。

对于客户端前台调用RESTful接口，如果涉及到跨域则可以通过多种方案解决。首先我们可以通过ajax的jsonp来解决ajax跨域问题，如果采用这种方案则客户端在发送ajax请求时候需要将datatype设置为jsonp,在服务端需要接受callback参数，结合spring提供的MappingJacksonValue来将要响应的信息作为构造参数进行传递，并调用对应的setJsonpFunction设置为参数callback对应的值；但是这种方案只能发送get请求，如果服务端接口接受的是其他类型的请求如post,put,delete则jsonp就没办法。这个时候我们可以采用spring给我们提供的@CrossOrigin注解来解决，使用这个注解的时候要特别注意一点它需要和jdk1.8及其以上配套使用，否则会报错。通过@CrossOrign的value属性指定客户端所在的域名这样客户端前台就可以使用普通的ajax进行跨域访问了而且可以发送任意类型的请求，这样就解决了上面所说的ajax jsonp只能发送get请求的问题。

写完接口之后我们通常会通过PostMan去测试接口的正确性，并且会自己编写接口文档，在编写接口文档时通常需要写清楚接口的业务描述，接口的请求地址，请求方式，请求参数的类型，是否含有头信息，请求参数的含义以及接口的响应格式【json/xml】，响应内容，响应内容的各个字段含义。