Spring框架学习笔记（9）——API接口设计相关知识及具体编码实现
最近需要设计一个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和实体类中添加注释
使用
使用此开源库很简单，我们只需要在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
}
我这里没开启严格模式，若是开启了严格模式，则调用插件的时候就会报错
之后直接在旁边的插件找到，选择对应生成的文档
之后就可以在输出文件夹中找到html文件了
打开网页，就会有详细的文档了
补充
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会在生成的文档的例子中进行自动随机赋值，如下图
如果不想随机赋值，可以使用mock注解指定例子中的数据
ignore注解
这个是smart-doc自带的注解，写在实体类字段的注释上，生成的API文档就会忽略此字段
更多详情，请参考官方文档
具体编码
spring boot中其实内置了GetMapping、PostMapping、PutMapping、DeleteMapping，分别对应的不同的请求方式，如果使用了以上注解，那么发送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的测试
参考
smart-doc
SpringBoot RestFul风格API接口开发
Post 方法参数写在body中和写在url中有什么区别？知乎严振杰回答
