RESTful风格的API接口开发教程

原创
2018/02/15 03:04
阅读数 5.9K

写在前面的话

网络程序正朝着移动设备的方向发展,前后端分离、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 的源码

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

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

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 可以支持的数据格式。 我一般常用的基本数据类型有 intString

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

那么,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,如果你有兴趣,那就来学习一下吧。

闲话少说,直接看效果:

swagger2.png

代码,请看这里: api-demo ,如果可以请 star。

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

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

后记

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

参考资料:

展开阅读全文
打赏
0
0 收藏
分享
加载中
更多评论
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部