day01
整体介绍
基础功能
中州养老系统为养老院量身定制开发专业的养老管理软件产品;涵盖来访管理、入退管理、在住管理、服务管理、财务管理等功能模块,涉及从来访参观到退住办理的完整流程。
中州养老项目分为两端,一个是管理后台,另外一个是家属端
- 管理后台:养老院员工使用,入住、退住,给老人服务记录等
- 家属端:养老院的老人家属使用,查看老人信息,缴费,下订单等
技术架构
- 前端主要使用的Vue3+TS
- 后端主要使用的是Springboot作为基础架构,当然后端也集成了很多其他的技术,比如有Mybatis、Swagger、Spring cache、Spring Security、Xxl-job、Activiti7
- 数据存储主要使用到了MySQL和Redis
- 使用了nginx来作为反向代理和前端的静态服务器
- 其他技术:阿里云物联网平台IOT、对象存储OSS、微信登录、AI工具辅助开发等
DTO 、VO
接收对象和返回对象分别使用了DTO和VO
- DTO:Data Transfer Object 数据传输对象:xxxDto或者xxxDTO,xxx为业务领域相关的名称, 用于接口的入参
- VO:Value Object展示对象:xxxVO或者xxxVo,xxx一般为网页名称, 用于接口的出参
接口四要素
搞明白需求之后,我们下面就可以来设计接口了,一个接口包含了四个基本要素,分别是:请求路径、请求方式、接口入参、接口出参
请求路径 命名:以模块名称进行区分(英文)
请求方式(需要符合restFul风格)
- 查询 GET
- 新增 POST
- 修改 PUT
- 删除 DELETE
接口入参
- 路径参数
- 问号传参---->后端形参接收
- path传参---->后端PathVariable注解接收
- 请求体参数
- 前端:json对象
- 后端:对象接收,DTO
接口出参
- 统一格式
{code:200,msg:"成功",data:{}}
- 数据封装,一般为VO
- 敏感数据过滤
- 整合数据
床位接口增删改查
新增床位为例
BedController层
@PostMapping("/create")
public ResponseResult createBed(@RequestBody BedDto bedDto){
bedService.addBed(bedDto);
return ResponseResult.success();
}
BedService层
@Override
public void addBed(BedDto bedDto) {
Bed bed = new Bed();
//使用了BeanUtils中的copyProerties方法
//也可以使用Bed bed = BeanUtil.toBean(bedDto, Bed.class);
BeanUtils.copyProperties(bedDto, bed);
bed.setCreateTime(LocalDateTime.now());
bed.setCreateBy(1L);
bed.setBedStatus(0);
try {
bedMapper.addBed(bed);
}catch (Exception e){
throw new BaseException(BasicEnum.BED_INSERT_FAIL);
}
}
BedMapper层
<insert id="addBed" parameterType="com.zzyl.entity.Bed">
insert into bed(bed_number, sort, bed_status, room_id, create_by, remark, create_time)
values (#{bedNumber}, #{sort}, #{bedStatus}, #{roomId}, #{createBy}, #{remark}, #{createTime})
</insert>
Swagger
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务
Spring已经将Swagger纳入自身的标准,建立了Spring-swagger项目,现在叫Springfox。通过在项目中引入Springfox ,即可非常简单快捷的使用Swagger。
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名knife4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!
目前,一般都使用knife4j框架。
项目中集成
导入 knife4j 的maven坐标(注意:由于knife4j是基于swagger的,所以也会自动导入swagger的依赖)
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>
配置类
在配置类中加入 knife4j 相关配置,可以使knife4j在全局生效,目的就是项目中的所有接口都生成在线接口文档
@Configuration
@EnableConfigurationProperties(SwaggerConfigProperties.class)
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {
@Autowired
SwaggerConfigProperties swaggerConfigProperties;
@Bean(value = "defaultApi2")
@ConditionalOnClass(SwaggerConfigProperties.class)
public Docket defaultApi2() {
// 构建API文档 文档类型为swagger2
return new Docket(DocumentationType.SWAGGER_2)
.select()
// 配置 api扫描路径
.apis(RequestHandlerSelectors.basePackage(swaggerConfigProperties.getSwaggerPath()))
// 指定路径的设置 any代表所有路径
.paths(PathSelectors.any())
// api的基本信息
.build().apiInfo(new ApiInfoBuilder()
// api文档名称
.title(swaggerConfigProperties.getTitle())
// api文档描述
.description(swaggerConfigProperties.getDescription())
// api文档版本
.version("1.0") // 版本
// api作者信息
.contact(new Contact(
swaggerConfigProperties.getContactName(),
swaggerConfigProperties.getContactUrl(),
swaggerConfigProperties.getContactEmail()))
.build());
}
/**
* 增加如下配置可解决Spring Boot 6.x 与Swagger 3.0.0 不兼容问题
**/
@Bean
public WebMvcEndpointHandlerMapping webEndpointServletHandlerMapping(WebEndpointsSupplier webEndpointsSupplier,
ServletEndpointsSupplier servletEndpointsSupplier,
ControllerEndpointsSupplier controllerEndpointsSupplier,
EndpointMediaTypes endpointMediaTypes,
CorsEndpointProperties corsProperties,
WebEndpointProperties webEndpointProperties,
Environment environment) {
List<ExposableEndpoint<?>> allEndpoints = new ArrayList();
Collection<ExposableWebEndpoint> webEndpoints = webEndpointsSupplier.getEndpoints();
allEndpoints.addAll(webEndpoints);
allEndpoints.addAll(servletEndpointsSupplier.getEndpoints());
allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints());
String basePath = webEndpointProperties.getBasePath();
EndpointMapping endpointMapping = new EndpointMapping(basePath);
boolean shouldRegisterLinksMapping = this.shouldRegisterLinksMapping(webEndpointProperties, environment, basePath);
return new WebMvcEndpointHandlerMapping(endpointMapping, webEndpoints, endpointMediaTypes, corsProperties.toCorsConfiguration(),
new EndpointLinksResolver(allEndpoints, basePath), shouldRegisterLinksMapping, null);
}
private boolean shouldRegisterLinksMapping(WebEndpointProperties webEndpointProperties, Environment environment, String basePath) {
return webEndpointProperties.getDiscovery().isEnabled() && (StringUtils.hasText(basePath) || ManagementPortType.get(environment).equals(ManagementPortType.DIFFERENT));
}
}
在上述代码中引用了一个配置,用来定制项目中的一些特殊信息,比如扫描的包、项目相关信息等
@Setter
@Getter
@NoArgsConstructor
@ToString
@ConfigurationProperties(prefix = "zzyl.framework.swagger")
public class SwaggerConfigProperties implements Serializable {
/**
* 扫描的路径,哪些接口需要使用在线文档
*/
public String swaggerPath;
/**
* 项目名称
*/
public String title;
/**
* 具体描述
*/
public String description;
/**
* 组织名称
*/
public String contactName;
/**
* 联系网址
*/
public String contactUrl;
/**
* 联系邮箱
*/
public String contactEmail;
}
所以上述代码具体的配置,是在application.yml文件中来定义
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
zzyl:
framework:
swagger:
swagger-path: com.zzyl.controller
title: 项目名称
description: 具体描述
contact-name: 组织名称
contact-url: 联系网址
contact-email: 联系邮箱
静态资源映射
如果想要swagger生效,还需要设置静态资源映射,否则接口文档页面无法访问,
找到配置类为:WebMvcConfig,添加如下代码
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
//支持webjars
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
//支持swagger
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
//支持小刀
registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
}
常用注解
注解 | 说明 |
---|---|
@Api | 用在类上,描述Controller的作用 |
@ApiOperation | 用在方法上,说明方法的用途、作用 |
@ApiParam | 用在方法的参数上,描述单个形参的含义 |
@ApiImplicitParam | 用在方法上,描述单个形参的含义,与上面相比使用范围更广 |
@ApiModel | 用在类上,用对象来接收参数或者返回参数,描述类的含义 |
@ApiModelProperty | 用在类的属性上,用对象来接收参数或者返回参数,描述字段的含义 |
改造代码
BedController示例 , 改造完可以直接访问在线接口文档
@RestController
@RequestMapping("/bed")
@Api(tags = "床位管理相关接口")
public class BedController extends BaseController {
@Autowired
private BedService bedService;
@GetMapping("/read/room/{roomId}")
@ApiOperation(value = "根据房间id查询床位", notes = "传入房间id")
public ResponseResult<List<BedVo>> readBedByRoomId(
@ApiParam(value = "房间ID", required = true) @PathVariable("roomId") Long roomId) {
List<BedVo> beds = bedService.getBedsByRoomId(roomId);
return success(beds);
}
@PostMapping("/create")
@ApiOperation(value = "创建床位", notes = "传入床位对象,包括床位号和所属房间号")
public ResponseResult createBed(@RequestBody BedDto bedDto) {
bedService.addBed(bedDto);
return success();
}
}
全局异常处理
全局异常处理逻辑
一般项目开发有两种异常:
- 预期异常(程序员手动抛出)
- 运行时异常
BaseException
基础异常,如果业务中需要手动抛出异常,则需要抛出该异常
@Getter
@Setter
public class BaseException extends RuntimeException {
private BasicEnum basicEnum;
public BaseException(BasicEnum basicEnum) {
this.basicEnum = basicEnum;
}
}
其中BaseException中的参数为一个枚举,可以在BasicEnum自定义业务中涉及到的异常
@Getter
@AllArgsConstructor
public enum BasicEnum implements IBasicEnum {
SUCCEED(200, "操作成功"),
SECURITY_ACCESSDENIED_FAIL(401, "权限不足!"),
LOGIN_FAIL(401, "用户登录失败"),
LOGIN_LOSE_EFFICACY(401, "登录状态失效,请重新登录"),
SYSYTEM_FAIL(500, "系统运行异常"),
//编码
public final int code;
//信息
public final String msg;
}
GlobalExceptionHandler
全局异常处理器
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {
/**
* 处理自定义异常BaseException。
* 返回自定义异常中的错误代码和错误消息。
*
* @param exception 自定义异常
* @return 响应数据,包含错误代码和错误消息
*/
@ExceptionHandler(BaseException.class)
public ResponseResult<Object> handleBaseException(BaseException exception) {
exception.printStackTrace();
if (ObjectUtil.isNotEmpty(exception.getBasicEnum())) {
log.error("自定义异常处理:{}", exception.getBasicEnum().getMsg());
}
return ResponseResult.error(exception.getBasicEnum());
}
/**
* 处理其他未知异常。
* 返回HTTP响应状态码500,包含错误代码和异常堆栈信息。
*
* @param exception 未知异常
* @return 响应数据,包含错误代码和异常堆栈信息
*/
@ExceptionHandler(Exception.class)
public ResponseResult<Object> handleUnknownException(Exception exception) {
exception.printStackTrace();
if (ObjectUtil.isNotEmpty(exception.getCause())) {
log.error("其他未知异常:{}", exception.getMessage());
}
return ResponseResult.error(500,exception.getMessage());
}
}