用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 的源码

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接口。如果你在开发中遇到关于接口的问题,欢迎与我交流!

参考资料:

课程简介 这是一门使用Java语言,SpringBoot框架,从0开发一个RESTful API应用,接近企业级的项目(我的云音乐),课程包含了基础内容,高级内容,项目封装,项目重构等知识,99%代码为手写;因为这是项目课程;所以不会深入到源码讲解某个知识点,以及原理,但会粗略的讲解下基础原理;主要是讲解如何使用系统功能,流行的第三方框架,第三方服务,完成接近企业级项目,目的是让大家,学到真正的企业级项目开发技术。 适用人群 刚刚毕业的学生 想提高职场竞争力 想学从零开发SpringBoot项目 想提升SpringBoot项目开发技术 想学习SpringBoot项目架构技术 想学习企业级项目开发技术 就是想学习SpringBoot开发 能学到什么 从0开发一个类似企业级项目 学会能做出市面上90%通用API 快速增加1到2年实际开发经验 刚毕业学完后能找到满意的工作 已经工作学完后最高涨薪30% 课程信息 全课程目前是82章,155小时,每节视频都经过精心剪辑。 在线学习分辨率最高1080P 课程知识点 1~11章:学习方法,项目架构,编码规范,Postman使用方法,Git和Github版本控制 12~16章:搭建开发环境,快速入门SpringBoot框架 17~20章:快速入门MySQL数据库 21~30章:MyBatis,登录注册,找回密码,发送短信,发送邮件,企业级接口配置 31~41章:实现歌单,歌单标签,音乐,列表分页,视频,评论,好友功能 42~48章:阿里云OSS,话题,MyBatis-plus,应用监控 49~53章:Redis使用,集成Redis,SpringCache,HTTP缓存 54~58章:Elasticsearch使用,集成Elasticsearch,使用ES搜索 59~61章:商城,集成支付宝SDK,支付宝支付 62~64章:常用哈希和加密算法,接口加密和签名 65~67章:实时挤掉用户,企业级项目测试环境,企业级接口文档 68~69章:SpringBoot全站HTTPS,自签证书,申请免费证书 70~73章:云MySQL数据库,云Redis数据库使用,轻量级应用部署环境,域名解析 74~80章:Docker使用,生产级Kubernetes集群,域名解析,集群全站HTTPS 81~82章:增强和重构项目,课程总结,后续学习计划
©️2020 CSDN 皮肤主题: 技术黑板 设计师:CSDN官方博客 返回首页