RESTful风格的API接口开发 Spring Cloud

学习笔记 大佬绕路,小白多篇文章整合总结篇

简单背景

网络程序正朝着移动设备的方向发展，前后端分离、APP，最好的交互交互方式莫过于通过API接口实现。既然要进行数据交互，那么这接口就得有讲究了：既要实用，又要优雅好看！

那么，如何写一套漂亮的API接口呢？

本次我们先了解一下Spring对API接口开发的支持，然后我们采用Spring Boot搭建项目，借用Swagger2列出API接口，便于查阅。

接口返回格式

API接口要求返回的格式是 application/json，我们知道网页返回的格式一般是 text/html，因此，Spring Boot为写接口，提供了两种实现方式：类注解 和 方法注解。

类注解 @RestController

我们只需要在类上写上注解 @RestController，那么此Controller返回格式就都是text/json。

/*类注解*/ @RestController @RequestMapping("/sdust/v1/sdcNode") public class SdcNodeController { @Autowired private SdcNodeApp sdcNodeApp; …… } 方法注解 @ResponseBody

我们只需要在某个方法上写上注解 @ResponseBody，那么该方法返回格式是text/json。如下图

/*类注解*/ @Controller @RequestMapping("/sdust/v1/sdcNode") public class SdcLnodeController { @Autowired private SdcNodeApp sdcNodeApp; @RequestMapping("/lef") @ResponseBody public String getInfo() { return ""; } …… }

值得提醒的是，虽然都是都可以，但更推荐使用类注解，会显得我们的编码风格十分统一，代码更加紧凑，不至于看起来零散。

我们来看下 @RestController 的源码

@Controller @ResponseBody public @interface RestController { …… }

请求方式源码

@RequestMapping 在``RequestMapping`的源码中提到，这种支持任意请求方式，类似于自适应。

@Mapping public @interface RequestMapping { …… }

@GetMapping 客户端只能用 GET 方式请求，适用于查询数据

@RequestMapping(method = RequestMethod.GET) public @interface GetMapping{ …… }

@PostMapping 客户端只能用 POST方式请求，适用于提交数据。

@RequestMapping(method = RequestMethod.POST) public @interface PostMapping{ …… }

@DeleteMapping 客户端只能用 DELETE方式请求，使用于删除数据。

@RequestMapping(method = RequestMethod.DELETE) public @interface DeleteMapping{ …… }

@PutMapping 客户端只能用 PUT方式请求，使用于修改数据（但在实际使用中，我个人建议还是采用POST方式较为妥当）。

@RequestMapping(method = REquestMethod.PUT) public @interface PutMapping{ …… }

以上请求我是在接口开发中经常使用的，图片是注解源码。当然还有其他一些。关于请求方式及使用范围，可以参考 RESTful API

接收参数

@RequestParam

我们来写一个示例并说明：

public String getInfo(@RequestParam(name = "param", required = false, defaultValue = "param dafault value") String param)

name代表提交参数名。 required意思是这个参数是否必需，默认true，没有该参数，无法调用此方法；这里设为false，有无该参数都可以调用。 defaultValue如果该参数值为空，那么就使用默认值。

@PathVariable @RequestMapping("/get-info/{param}") public String getInfo(@PathVariable("param") Object param)

我们可以在请求方法后面直接跟值，省去了 ？参数名= 。 这种一般配合 @DeleteMapping、@PutMapping使用。

@RequestHeader

这个使用了获取提交数据的 Headers 的值。我是用来接收 TOKEN。后面会举例。

数据格式

下面我们来了解下，Spring Boot 可以支持的数据格式。 我一般常用的基本数据类型有 int、String。

而我们在日常中，还可能有 Array、List、Map……

那么，Spring Boot支持吗？我们如何解决？并且统一化呢？

JSON！

毫无疑问JSON可以帮助我们解决这个问题，当然XML也是可以的。

在Controller层当中使用一些封装的方法，讲实现的内容封装到自己定义的数据结构中返回给前端就可以实现通过JSON传递数据

至于前端方面，先看 Ajax 代码：

$.ajax({ headers : { Accept: "application/json; charset=utf-8", 'token' : '9B4BF951093F1F1A40BB2DAAA30B3838' }, url: URI + '/admin/blog/add', type: 'POST', async: true, data: { ... }, timeout: 3000, dataType: 'json', beforeSend: function(xhr){}, success: function(data, textStatus, jqXHR){ console.log(data); }, error: function(xhr, textStatus){ console.log(xhr); }, complete: function(){} })

现在的问题是如何获取 token的值？没错，就是 @RequestHeader("token")!

如果我们没在Controller，那怎么办

答案是

String token = request.getHeader("token"); System.out.println(token);