查看: 1009|回复: 0

[手机开发] RESTful风格的API接口开发教程

发表于 2018-5-9 08:00:03
引言

前后端分离、APP交互等,大多都是通过API接口实现的。既然要进行数据交互,那么这接口就得有讲究了:既要实用,又要优雅好看!

那么,如何写一套(个)漂亮的API接口呢?

一、返回格式

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

类注解 @RestController

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

类注解

方法注解 @ResponseBody

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

方法注解

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

我们来看下 @RestController 的源码

RestController

二、请求方式

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

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

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

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

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

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

三、接收参数 @RequestParam

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

  1. public String getInfo(@RequestParam(name = "param",
  2. required = false,
  3. defaultValue = "param dafault value") String param)
复制代码

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

@PathVariable
  1. @RequestMapping("/get-info/{param}")
  2. public String getInfo(@PathVariable("param") Object param)
复制代码

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

@RequestHeader

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

四、数据格式

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

而我们在日常中,还可能有 ArrayListMap……

那么,Spring Boot支持吗?

这个我就不在这里探讨了,因为格式的原因,我们不会用他。如果你感兴趣,可以去尝试一下。答案嘛,肯定是可以做到的咯。

五、问题

对于中的问题,我们如何解决?并且统一化呢?

JSON!

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

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

六、解决方案

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

封装并提交 POST 数据
  1. @Test
  2. public void testPostData() {
  3. // int
  4. int pInt = 0;
  5. // String
  6. String pString = "String";
  7. // String []
  8. String [] pStrings = {"String [0]", "String [1]"};
  9. // List
  10. List<String> pLists = List.of("list[0]", "list[1]");
  11. // 。。
  12. Map<String, Object> params = new HashMap<>();
  13. params.put("p-int", pInt);
  14. params.put("p-string", pString);
  15. params.put("p-strings", pStrings);
  16. params.put("p-list", pLists);
  17. String url = "http://localhost:8080/api/get-info";
  18. try {
  19. String rs = HttpUtil.post(url, null, params);
  20. System.out.println(rs);
  21. } catch (IOException e) {
  22. e.printStackTrace();
  23. }
  24. }
复制代码
获取POST提交的数据
  1. @RestController
  2. @RequestMapping("/api")
  3. public class APIController {
  4. @PostMapping("/get-info")
  5. public String getInfo(HttpServletRequest request) {
  6. try {
  7. String jsonStr = RequestUtil.getPostData(request);
  8. System.out.println(jsonStr);
  9. } catch (IOException e) {
  10. e.printStackTrace();
  11. }
  12. return "";
  13. }
  14. }
复制代码

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

七、分享

先看 Ajax 代码:

  1. $.ajax({
  2. headers : {
  3. Accept: "application/json; charset=utf-8",
  4. 'token' : '9B4BF951093F1F1A40BB2DAAA30B3838'
  5. },
  6. url: URI + '/admin/blog/add',
  7. type: 'POST',
  8. async: true,
  9. data: {
  10. ...
  11. },
  12. timeout: 3000,
  13. dataType: 'json',
  14. beforeSend: function(xhr){},
  15. success: function(data, textStatus, jqXHR){
  16. console.log(data);
  17. },
  18. error: function(xhr, textStatus){
  19. console.log(xhr);
  20. },
  21. complete: function(){}
  22. })
复制代码

现在的问题是如何获取 token的值?相信聪明的你,一定还记得我们早就卖好了关子!没错,就是 @RequestHeader("token")!

问题还没结束,如果我们没在Controller,那怎么办?

答案是

  1. String token = request.getHeader("token");
  2. System.out.println(token);
复制代码
八、尾声

到这里,终于要和大家说拜拜了!

你一定能写出漂亮、简洁、优雅的API接口。

如果你在开发中遇到关于接口的问题,欢迎与我交流!

九、更新

之前因为是我写公共接口文档(参考:【Work】投递服务API文档),所以用了MD格式。

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

闲话少说,直接看效果:

swagger2.png

代码,请看这里:api-demo

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

另外:

1、需要你想学习更多,你可以看下 TestController

2、参考资料:

SpringBoot开发案例之整合Swagger篇

swagger注释API详细说明

Swagger的接收参数的注解问题


回复

使用道具 举报