用Spring Boot开发API接口

写在前面的话

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

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

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

返回格式

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

• 类注解 @RestController

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

• 方法注解 @ResponseBody

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

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

我们来看下 @RestController 的源码

请求方式

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

@GetMapping

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

@PostMapping 

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

@DeleteMapping 

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

@PutMapping 

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

以上请求我是在接口开发中经常使用的，图片是注解源码。当然还有其他一些。关于请求方式及使用范围，可以参考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也是可以的。

  如何用？代码怎么写？前端？移动端都支持吗？

  解决方案

  我已将代码封装到 JavaLib 库中，所以，我们直接调用。

• 封装并提交 POST 数据

• @Test
  public void testPostData() {
      // int
      int pInt = 0;
      // String
      String pString = "String";
      // String []
      String [] pStrings = {"String [0]", "String [1]"};
      // List
      List<String> pLists = List.of("list[0]", "list[1]");
      // 。。
  
      Map<String, Object> params = new HashMap<>();
      params.put("p-int", pInt);
      params.put("p-string", pString);
      params.put("p-strings", pStrings);
      params.put("p-list", pLists);
  
      String url = "http://localhost:8080/api/get-info";
  
      try {
          String rs = HttpUtil.post(url, null, params);
          System.out.println(rs);
      } catch (IOException e) {
          e.printStackTrace();
      }
  }

• 获取POST提交的数据

  @RestController
  @RequestMapping("/api")
  public class APIController {
  
      @PostMapping("/get-info")
      public String getInfo(HttpServletRequest request) {
  
          try {
              String jsonStr = RequestUtil.getPostData(request);
              System.out.println(jsonStr);
          } catch (IOException e) {
              e.printStackTrace();
          }
  
          return "";
      }
  }

  到这里，我相信你对接口的编写应该游刃有余了吧！可是，我还有东西想要分享给你！

  分享

  先看 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);

更新

之前因为写的公共接口，所以也就写的公共接口文档（参考： 【Work】投递服务API文档 )，采用了 Markdown 格式。

但在实际开发中，我们可能只给前端或者APP写接口，如果还要写接口，那可能是相当麻烦的。所以很多人建议我更新一下。所以抽闲先更新一下，Spring Boot集成Swagger，如果你有兴趣，那就来学习一下吧。

闲话少说，直接看效果：

代码，请看这里： api-demo ，如果可以请 star。

详细讲解，请看这里： Spring Boot中使用Swagger2构建强大的RESTful API文档

需要你想学习更多，你可以看下： TestController

后记

至此，你一定能写出漂亮、简洁、优雅的API接口。如果你在开发中遇到关于接口的问题，欢迎与我交流！

参考资料：

• SpringBoot开发案例之整合Swagger篇

• swagger注释API详细说明

• Swagger的接收参数的注解问题