查看: 255|回复: 0

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

[复制链接]
发表于 2020-2-21 14:45:11 | 显示全部楼层 |阅读模式
最近需要设计一个API服务器,想要把API接口搞得规范一下,就通过网上搜集到了一些资料,以下便是自己的一些理解以及相关的详细实现
本文采用的是spring boot+maven的方案
restful规范

这个规范我在这里也不打算长篇大论地讲解,怎么说呢,有人喜欢有人讨厌,我也不去争,因为我经验不多,看法和大佬有所差异。
restful规范简单来说,就是通过一些关键字去定义url接口,从而让url具有更好的可读性,如下面举个例子
  1. # 查询全部用户http://localhost:9200/shunbang/api/user/users# 指定id为1的用户http://localhost:9200/shunbang/api/user/users/1# 数据太多,只要前10http://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=xxapplication/json客户端通过body发送json数据application/xml客户端通过body发送xml数据application/octet-stream客户端通过body发送Binary数据(二进制文件)multipart/form-data客户端通过body发送一个表单API文档天生框架 smart-doc

介绍

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


使用

使用此开源库很简单,我们只需要在maven项目中添加插件的依赖即可
  1.     com.github.shalousun    smart-doc-maven-plugin    1.0.2                    ./src/main/resources/smart-doc.json                测试                                        com.alibaba:fastjson                                                compile                            html                        
复制代码
之后,在resources文件夹新建smart-doc.json文件,进行一些设置即可
  1. {  "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框架自带)
  1. 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注解
  1. /** * 查询指定id的用户信息 * * @param id 用户id * @return 用户信息 */@GetMapping("{id}")public User selectByPk(@PathVariable("id") Integer id) {    return userMapper.selectOne(new QueryWrapper().eq("user_id", id));}
复制代码
2.limit限制

想要通过http://localhost:9200/shunbang/api/user/users?limit=10来获得前几条记录,limit此参数是可选的,使用RequestParam注解
当用户没有输入limit参数,则显示返回全部的数据,有的话则进行数据的限制,offset也是同理,之后便不多说了
  1. /** * 查询全部用户 * * @return 用户列表的json */@GetMapping("users")public List 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传递
  1. @PutMapping("update")public boolean updateUser(@RequestBody User user) {    return user.updateById();}
复制代码
Java发送url哀求
  1. 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中有什么区别?知乎严振杰回答

本帖子中包含更多资源

您需要 登录 才可以下载或查看,没有帐号?用户注册

x

相关技术服务需求,请联系管理员和客服QQ:2753533861或QQ:619920289
您需要登录后才可以回帖 登录 | 用户注册

本版积分规则

帖子推荐:
客服咨询

QQ:2753533861

服务时间 9:00-22:00

快速回复 返回顶部 返回列表