开发环境
-
JDK安装
①也可使用idea自带jdk,可能与open jdk存在一些区别
②傻瓜式安装,完成后配置环境变量 -
Intellij IDEA安装
傻瓜式安装,完成后在“文件→设置→插件”中搜索①Alibaba Java Code Guidelines②Gitee并安装 -
克隆项目
①Fork教学项目
②在非中文目录下clone项目“git clone https://gitee.com/xxx/api-practices.git” -
安装mysql-installer-community-8.0.22.0
①仅安装Server即可(Server only)
②检测安装,可能会有一些依赖安装,按提示安装即可
③安装完会有配置,其中密码验证方式,必须选择传统验证(Legacy),强密码方式navicat无法连接
④root根用户密码要牢记,开发环境建议使用123456或654321,生产环境不要使用易于猜测的密码
⑤其他配置一般按默认即可
参考:https://www.modb.pro/db/53520 -
安装Navicat,并打补丁
①安装完成后打开navicat,点击连接输入root用户密码并连接到mysql
②创建practices数据库。字符集utf8 -- UTF-8 Unicode,排序utf8_bin -
接口测试工具
①一般的接口测试,请在Edge或Chrome上安装postwoman插件
②涉及到文件上传,需要安装和使用postman应用
③要测试接口需要提交复杂json作为参数时,可使用>>>在线json编辑器<<<
搭建项目框架
1.RESTful API项目开发流程
本项目使用Spring Boot框架,其中数据库MySQL,持久化框架Spring Data JPA,包含自定义的认证及授权机制,包括RESTful API开发规范,包含文件上传等内容。
2.创建项目
①使用Spring Initializer创建项目,建议使用IDE创建
//若官网start.sprint.io无法链接,可切换到阿里云镜像start.aliyun.com,但spring boot的版本可能存在差异
//可在官网页面创建,并无本质区别,IDE可检测jdk
②构建工具:Maven
//对于构建Java程序,Maven出现时间早,支持范围更广,使用xml编码更易阅读;Gradle支持增量构建,性能更强,使用groovy或kotlin语言,对于初学者有一定的要求
③JDK版本,根据个人安装的情况选择,本项目使用jdk1.8,Java语言版本8
//高级的语言版本具有更多的语言特性,尤其是集合API上,更方便易用,但新版本对于反射增加了限制,本项目的自定义授权机制因为要使用反射,因此选择8具备更高的灵活性
④打包方式Jar(官方推荐)
//spring boot内置了web容器,jar包直接运行;若已存在外部web容器可使用war打包
⑤spring boot版本(2.7.6),在官网当时提供的版本中选择,尽量选择发行版本
⑥选择依赖3.相关配置文件
①pom.xml
//项目对象模型(Project Object Model)是Maven工程的基本工作单元,包含了项目的基本信息,用于描述项目如何构建,声明项目依赖。若需要添加其他依赖,可在pom中添加。
//pom文件中指定源码文件编码为UTF-8
//pom中配置maven打包跳过测试,或忽略测试失败
②application.yml
//application.properties→application.yml,应用程序配置文件的格式由properties修改为yml,yml文件的结构更为清晰
//yml中配置数据源,包括驱动类、数据库地址、用户名、密码等
//yml中配置数据库架构变化时的更新策略为update:必要时才更新。其他还有全部删除后更新、每次会话删除更新等。开发时配置为update;在项目部署后,可将该项配置为none,避免在生产数据库中更新造成数据丢失
//yml中配置jpa的show-sql为true,方便开发时在控制台查看和定位问题
③为不同的环境添加个性化的应用程序配置文件
//比如开发环境下的application-dev.yml和生产环境下的application-prd.yml,将共同的配置留在application.yml中
④不同环境的yml文件,指定个性化配置
//比如端口号生产环境80、开发环境8xxx,比如不同的数据源地址、用户名密码等
⑤在默认的yml配置文件中,指定当前生效的配置文件,只需要指定后缀
4.启动应用测试
①可在控制台看输出,出现Started XXXApplication in xxx seconds,表示运行成功
②可在yml中配置日志级别,开发时输出详细信息,生产环境根据需要记录关键信息
③应用启动并测试成功后,将创建的项目框架推送到远程仓库
异常处理
-
定义错误页面
①添加首页(resources/templates/index.html)及相应Controller
--添加控制器注解
--添加index方法
--添加路由注解
②添加404和500页面
③运行测试,分别访问首页、制造错误访问其他两个页面 -
自定义错误处理
①添加自定义异常类(业务异常类BusinessException和资源不存在异常类NotFoundException)
②添加统一的异常处理类PracticeExceptionHandler
--使用ControllerAdvice注解把所有Controller作为切面统一提供错误处理功能
--添加专门处理业务异常的方法,使用ExceptionHandler注解
--添加通用的异常处理方法,使用ExceptionHandler注解
--还可使用ModelAttribute注解添加全局数据 -
自定义错误页面
①添加Thymleaf依赖
②完成error页面 -
接口专用错误处理类
①添加handlers文件夹,并添加专用于RESTful接口异常的处理类ApiExceptionHandler
②使用注解指定处理的类型为RestController
③在内部定义一个类型ExceptionWrapper专用于包装异常信息
④添加异常处理方法,同样使用ExceptionHandler注解,返回异常包装类对象
⑥在完成接口开发后,制造异常以测试该异常处理类
实体类
-
类图
-
操作步骤
-
相关注解
@MappedSuperclass
//JPA注解,用于实体类的父类,被标注的父类不是完整的实体类,不会映射到数据库,而是把其属性映射到子类的数据库列。因此被标注的类不能再标注@Entity或@Table
@Id
//JPA注解,声明该字段映射为数据库中的主键列
@GeneratedValue&@GenericGenerator
//JPA注解,通过stragegy属性声明主键的生成策略,MySQL中默认是自增AUTO(auto increment)其他还有TABLE、SEQUENCE、IDENTITY等,在本项目中使用自定义类型,则可使用generator = "uuid2"指定生成类型。
//第二个注解是自定义主键生成策略生成器,必须与第一个搭配使用,@GeneratedValue注解中的"generator"属性要与@GenericGenerator注解中name属性一致,strategy属性表示hibernate的主键生成策略
@Column
//指定数据库列的相关设置,比如各种约束如unique nullable等,还可指定创建列时的相关定义,比如本项目中指定类型binary
@Entity
//指定被注解的类为实体类,ORM则会把其映射到数据库的表,如果不手动设置表名则默认会把类名作为表名
@Temporal
//注解日期时间类型字段持久化到数据库时的存储精度,其枚举类型为TemporalType,枚举值有DATE日期、TIME时间、TIMESTAMP日期时间
@Getter&@Setter
//lombok注解,用于自动生成getter和setter
@Transient
//注解字段,被注解的字段在ORM映射到数据库时会忽略,用于Java代码中一些辅助性的字段如常量等
@ManyToOne&@OneToMany&@ManyToMany
//注解实体关系,多对一、一对多、多对多,使用mappedBy属性指定主次关系,具体的规则请参考项目代码
@Table
//使用改注解自定义映射的表明,因为默认使用类名作为表名即可,所以该注解一般用于表名与关键字冲突的情况,比如本项目中的option关键字、或者电商系统中的order关键字@JsonBackReference&@JsonManagedReference&@JsonIgnore
//在序列化的时候,@JsonManagedReference 注解的属性则会被序列化,@JsonBackReference 的注解将会被忽略
//@JsonBackReference 注解,通常说明这个字段是关联的一个双向引用字段,这个字段在这个双向引用的角色是 “孩子”。这个字段的值只能是对象(Bean),不能是集合、图、数组等
//@JsonManagedReference 注解,通常说明这个字段是一个双向引用的字段,这个字段在这个双向引用中的角色为 “父”,与这个字段对应的引用需要注解为 @JsonBackReference
上传文件
接口调试
1.使用的测试工具
-
-
一般的接口测试,在Edge或Chrome上使用PostWoman插件(Postman插件已下架)
-
测试接口需要提交复杂json时,可使用在线json编辑器
-
涉及到文件上传,必须安装Postman应用
-
使用Chrome或Edge的开发者工具,可在网络面板中解析接口资源
-
如需分析接口发送的数据,可安装fiddler,在请求过程中抓包
-
2.一般接口测试
-
-
①选择请求方法,如GET、POST、PUT、DELETE等
-
②输入接口请求地址
-
③请求发送按钮
-
④输入请求参数
-
⑤响应得到的json数据
-
3.不同的请求参数
-
-
上图1是
@RequestBody
注解的参数,类型是application/json
,输入的参数为json格式 -
上图2是
@RequestParam
注解的参数,类型是x-www-form-urlencoded
,最常见的表单参数传递方式 -
上图3是Get请求时的
@RequestParam
参数
-
4.可将一个项目的所有需要调试接口保存在多个模块中
5.文件上传接口测试