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中有什么区别？知乎严振杰回答