Spring框架学习笔记(9)——API接口设计相关知识及具体编码实现

时间:2024-04-29 20:03:55

最近需要设计一个API服务器,想要把API接口搞得规范一下,就通过网上搜集到了一些资料,以下便是自己的一些理解以及相关的具体实现

本文采用的是spring boot+maven的方案

restful规范

这个规范我在这里也不打算长篇大论地讲解,怎么说呢,有人喜欢有人讨厌,我也不去争,因为我经验不多,看法和大佬有所不同。

restful规范简单来说,就是通过一些关键字去定义url接口,从而让url具有更好的可读性,如下面举个例子

# 查询所有用户
http://localhost:9200/shunbang/api/user/users
# 指定id为1的用户
http://localhost:9200/shunbang/api/user/users/1
# 数据太多,只要前10
http://localhost:9200/shunbang/api/user/users?limit=10
# 从第十条数据后开始(不要前十条数据)
http://localhost:9200/shunbang/api/user/users?offset=10

我觉得restful规范起来,url的可读性较好

restful规范使用的几种方式

方式 说明
get 从服务器上获取资源(select)
put 更新服务器上的资源(update)
post 将传入的资源存储在服务器上(insert)
delete 删除服务器上的资源(delete)

url请求协议介绍

方式 说明 例子
application/x-www-form-urlencoded 默认,客户端通过key-value键值对传递数据 http://localhost:9200/shunbang/api/user/update?id=1&name=xx
application/json 客户端通过body发送json数据
application/xml 客户端通过body发送xml数据
application/octet-stream 客户端通过body发送Binary数据(二进制文件)
multipart/form-data 客户端通过body发送一个表单

API文档生成框架 smart-doc

介绍

这里,我使用了smart-doc这款框架,可以无侵入实现API接口的注释,需要在Controller和实体类中添加注释

Spring框架学习笔记(9)——API接口设计相关知识及具体编码实现

Spring框架学习笔记(9)——API接口设计相关知识及具体编码实现

使用

使用此开源库很简单,我们只需要在maven项目中添加插件的依赖即可

<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>1.0.2</version>
<configuration>
<!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
<configFile>./src/main/resources/smart-doc.json</configFile>
<!--指定项目名称-->
<projectName>测试</projectName>
<!--smart-doc实现自动分析依赖树加载第三方依赖的源码,如果一些框架依赖库加载不到导致报错,这时请使用excludes排除掉-->
<excludes>
<!--格式为:groupId:artifactId;参考如下-->
<exclude>com.alibaba:fastjson</exclude>
</excludes>
</configuration>
<executions>
<execution>
<!--如果不需要在执行编译时启动smart-doc,则将phase注释掉-->
<phase>compile</phase>
<goals>
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>

之后,在resources文件夹中新建smart-doc.json文件,进行一些配置即可

{
"outPath": "Q:\\JavaWebProject\\shunbang\\target", //指定文档的输出路径
"serverUrl": "http://localhost:9200/shunbang", //设置服务器地址,非必须
// "serverUrl": "http://47.101.148.199:9200/shunbang", //设置服务器地址,非必须
"isStrict": false, //是否开启严格模式
"allInOne": true //是否将文档合并到一个文件中,一般推荐为true
}

我这里没开启严格模式,若是开启了严格模式,则调用插件的时候就会报错

之后直接在旁边的插件找到,选择对应生成的文档

Spring框架学习笔记(9)——API接口设计相关知识及具体编码实现

之后就可以在输出文件夹中找到html文件了

Spring框架学习笔记(9)——API接口设计相关知识及具体编码实现

打开网页,就会有详细的文档了

Spring框架学习笔记(9)——API接口设计相关知识及具体编码实现

补充

JsonIgnore注解

若是存在某些敏感字段不需要被返回,在实体类的字段中添加JsonIgnore注解(注意:此JsonIgnore注解为spring boot内置jackson框架自带)

public class JacksonAnnotation {

    /**
* 用户名
*/ @JsonProperty("name")
private String username; /**
* 身份证号
*/
@JsonIgnore
private String idCard;
}

Fastjson使用 @JSONField(serialize = false),起关键作用的是serialize = false

mock注解

smart-doc会在生成的文档的例子中进行自动随机赋值,如下图

Spring框架学习笔记(9)——API接口设计相关知识及具体编码实现

如果不想随机赋值,可以使用mock注解指定例子中的数据

Spring框架学习笔记(9)——API接口设计相关知识及具体编码实现

ignore注解

这个是smart-doc自带的注解,写在实体类字段的注释上,生成的API文档就会忽略此字段

Spring框架学习笔记(9)——API接口设计相关知识及具体编码实现

更多详情,请参考官方文档

具体编码

spring boot中其实内置了GetMappingPostMappingPutMappingDeleteMapping,分别对应的不同的请求方式,如果使用了以上注解,那么发送url请求的方式也是应该相对应,否则服务器不会进行数据的返回

1.指定id

想要通过http://localhost:9200/shunbang/api/user/users/1查询指定id用户信息

使用PathVariable注解

/**
* 查询指定id的用户信息
*
* @param id 用户id
* @return 用户信息
*/
@GetMapping("{id}")
public User selectByPk(@PathVariable("id") Integer id) {
return userMapper.selectOne(new QueryWrapper<User>().eq("user_id", id));
}

2.limit限制

想要通过http://localhost:9200/shunbang/api/user/users?limit=10来获得前几条记录,limit此参数是可选的,使用RequestParam注解

当用户没有输入limit参数,则显示返回所有的数据,有的话则进行数据的限制,offset也是同理,之后便不多说了

/**
* 查询所有用户
*
* @return 用户列表的json
*/
@GetMapping("users")
public List<User> selectAll(@RequestParam(required = false) Integer limit) {
if (limit == null) {
return userMapper.selectList(null);
} else {
System.out.println(limit);
return userMapper.selectList(null);
}
}

3.传递实体类

原本我是想要通过http://localhost:9200/shunbang/api/user/update?jsonData=xx这样传递实体类的json数据,之后由后台接收json数据,并再将json数据转为实体类对象,调用update方法,进行表记录的update

其实,有个方法比上面的方法更简单,使用RequestBody注解,之后进行put的请求,将json数据直接通过body传递

@PutMapping("update")
public boolean updateUser(@RequestBody User user) {
return user.updateById();
}

Java发送url请求

HttpURLConnection conn =new URL("address").openConnection();
conn.setRequestMethod("PUT"); // 可以根据需要 提交 GET、POST、DELETE、PUT等http提供的功能
conn.setRequestProperty("Content-Type", " application/json");//设定 请求格式 json,也可以设定xml格式的

上述是原生的,之后我会在补充使用okhttp框架进行相关的接口申请数据

我是使用的postwoman进行API的测试

Spring框架学习笔记(9)——API接口设计相关知识及具体编码实现

参考

smart-doc

SpringBoot RestFul风格API接口开发

Post 方法参数写在body中和写在url中有什么区别?知乎严振杰回答