mall项目学习笔记

springdoc-openapi 替换 Swagger2 总结

---

为什么要替换为 springdoc-openapi

1. Springfox/Swagger2 已停止维护
   无法适配 Spring Boot 新版本，存在安全和兼容性隐患。

2. 与 Spring Boot 2.6+ 兼容性差
   经常出现启动报错、NPE 等严重兼容性问题，社区已无有效修复方案。

3. springdoc-openapi 支持 OpenAPI 3 标准
   完全支持 OpenAPI 3 规范，功能更强大，文档结构更清晰，支持更多新特性。

---

迁移主要更改

1. Maven 依赖调整

   • 移除（或注释）Springfox/Swagger2 相关依赖（如 io.springfox:springfox-boot-starter:3.0.0）。
   • 新增 springdoc-openapi 依赖。

2. 注解替换

   • 将 Controller 和实体类中的 Swagger2 注解替换为 OpenAPI 3 注解：
     • @Api → @Tag
     • @ApiOperation → @Operation
     • @ApiModelProperty → @Schema

3. 配置类调整

   • 删除原有的 Swagger2Config.java 配置类（如有）。
   • 新增 OpenApiConfig.java，用于自定义文档信息（如标题、描述等）。

---

项目搭建

1. 生成 Spring Boot 聚合项目

在 pom.xml 中添加相关依赖：

 - 父工程 `pom` 设置 `<parent>` 继承 Spring Boot 版本控制，设置 `<modules>` 管理子模块。

2. 子模块初始化

目录结构

• 

添加依赖

修改 Spring Boot 配置文件 application.yml：

 - 添加数据源配置和 MyBatis 的 `mapper.yml` 路径配置。- ![application.yml 配置截图](https://img2024.cnblogs.com/blog/3492432/202509/3492432-20250920232805654-1999344054.png)

MyBatis Generator 配置：

 - `generatorConfig.xml`：配置连接数据库信息，生成的 Java 实体类、Mapper.xml 文件、Mapper 接口文件所在包及位置等。- `MyBatisConfig.java`：用于配置需要动态生成的 mapper 接口路径，让 Spring 能识别和管理 Mapper 接口。- `CommentGenerator.java`：自定义注释生成器，继承自 MBG 的 DefaultCommentGenerator，用于在生成的实体类字段上添加数据库备注等注释，提升代码可读性。- `Generator.java`：generator 的 main 函数生成代码，读取 `generatorConfig.xml`，解析并执行代码。- `generator.properties`：结合 generatorConfig.xml 使用，作为参数引用，通过 ${} 占位符引用- `PmsBrandMapper.xml`：SQL 映射文件，定义了具体的 SQL 语句和结果映射关系，供 Mapper 接口调用。- `PmsBrandMapper.java`：Mapper 接口，定义了对 PmsBrand 表的增删改查（CRUD）方法，供 Service 层调用，实际 SQL 由 MyBatis 实现。- `PmsBrand.java`：实体类，对应数据库中的 PmsBrand 表，每个字段映射一列，用于数据传递。- `PmsBrandExample.java`：条件构造器类，用于动态生成复杂的查询条件（如 where、order by），常配合 Mapper 的 selectByExample 等方法实现灵活查询。

Controller 接口实现：

 - 实现 `PmsBrand` 表的添加、修改、删除及分页查询接口。- `IErrorCode.java`：封装 API 的错误码- `ResultCode.java`：实现 IErrorCode 接口，枚举常用 API 操作码- `CommonResult.java`：结合 ResultCode，实现通用返回对象- `CommonPage.java`：分页数据封装类- `PmsBrandService.java`：接口文件- `PmsBrandServiceImpl.java`：实现接口- `PmsBrandController.java`：实现具体功能

3. 加入Springfox/Swagger2 UI（高版本废弃，可采用springdoc-openapi

目录结构

 - 若需要调整为springdoc-openapi，可前往问题解答查看- ![目录树02](https://img2024.cnblogs.com/blog/3492432/202509/3492432-20250920233019574-788653682.png)

依赖引入：

 - springfox swagger官方Starter：io.springfox:springfox-boot-starter:3.0.0

application.yml：新增Spring MVC路径匹配策略

 - spring.mvc.pathmatch.matching-strategy = ANT_PATH_MATCHER- ANT_PATH_MATCHER 表示使用传统的 Ant 风格路径匹配（如 /api/**），而不是 Spring 5.3+ 默认的 PathPatternParser。常用于解决升级 Spring Boot 后，部分路由、拦截器、Swagger 等路径匹配不兼容的问题。

Swagger2配置

 - `Swagger2Config.java`：Swagger 的核心配置类，创建并配置 Docket，指定扫描的 Controller 包，设置 API 信息。- `PmsBrandController.java`：调整内容，补充Swagger 注解- `CommentGenerator.java`：调整注释生成器，配置后，用于在自动生成的实体类字段上添加 @ApiModelProperty 注解- 运行Generator.java重新生成文件- 运行项目，即可访问http://localhost:8080/swagger-ui/

4. 整合Redis实现缓存功能

目录结构

 - ![目录树03](https://img2024.cnblogs.com/blog/3492432/202509/3492432-20250920233029324-905195071.png)

依赖引入：

 - Spring Data Redis依赖配置：org.springframework.boot:spring-boot-maven-plugin

application.yml：

 - 添加Redis的配置及Redis中自定义key的配置。

RedisConfig.java：

 - 用于自定义和优化 Spring Boot 项目中 Redis 的序列化方式、缓存管理等，保证数据能正确存储和读取，提升兼容性和性能。

RedisService.java：

 - redis接口用于定义一些常用Redis操作- `RedisServiceImpl.java`：注入StringRedisTemplate，实现RedisService接口

UmsMemberService.java：

 - 定义会员相关的业务接口（如生成、校验验证码）。- `UmsMemberServiceImpl.java`：实现会员业务逻辑，调用 RedisService 进行验证码的存取。- 生成验证码时，将自定义的Redis键值加上手机号生成一个Redis的key,以验证码为value存入到Redis中，并设置过期时间为自己配置的时间（这里为120s）。校验验证码时根据手机号码来获取Redis里面存储的验证码，并与传入的验证码进行比对。- `UmsMemberController.java`：编写 Controller 层，暴露获取和校验验证码的接口，调用 UmsMemberService。

5. 整合SpringSecurity和JWT实现认证和授权

目录结构

• 

依赖引入：

 - SpringSecurity依赖配置：org.springframework.boot:spring-boot-starter-security- JWT(Json Web Token)登录支持：io.jsonwebtoken:jjwt:0.9.1- Hutool Java工具包：cn.hutool:hutool-all:5.8.9

application.yml：

 - 添加jwt，secure相关配置

AdminUserDetails.java：

 - 先定义用户信息封装类，便于后续认证和授权。

UmsResource.java：

 - 表示系统中的“后台资源”实体，是数据库表的映射

UmsAdminService.java：

 - 定义用户管理接口，明确需要哪些功能。

UmsAdminServiceImpl.java：

 - 实现接口，完成用户、资源、登录等核心业务逻辑。

JwtTokenUtil.java：

 - 实现 JWT 生成和校验工具类，供登录和认证使用。

MallSecurityConfig.java：

 - 配置如何获取用户信息，注入自定义的 UserDetailsService。

JwtAuthenticationTokenFilter.java：

 - 实现 JWT 认证过滤器，集成到 Spring Security。

IgnoreUrlsConfig.java：

 - 配置白名单路径，便于安全配置。

RestAuthenticationEntryPoint.java 和 RestfulAccessDeniedHandler：

 - 实现自定义异常处理，提升接口友好性。

SecurityConfig.java：

 - 配置安全规则、过滤器链、异常处理等，集成前面所有组件。

UmsAdminController.java：

 - 实现接口层，调用 Service 提供登录和资源查询等功能。

6. 整合Elasticsearch实现商品搜索

目录结构

• 

依赖引入：

 - Elasticsearch相关依赖：org.springframework.boot:spring-boot-starter-data-elasticsearch

安装Elasticsearch，Kibana

 - 注意Spring Boot与Elasticsearch版本兼容性，- Elasticsearch- 7.17.29- 下载zip包，并解压到指定目录，下载地址：https://www.elastic.co/downloads/past-releases/elasticsearch-7-17-29- 安装中文分词插件：elasticsearch-plugin install https://get.infini.cloud/elasticsearch/analysis-ik/7.17.29- 执行elasticsearch.bat- Kibana- 7.17.29- 下载zip包，并解压到指定目录，下载地址：https://www.elastic.co/downloads/past-releases/kibana-7-17-29- 执行kibana.bat- 访问http://localhost:5601 即可打开Kibana的用户界面

application.yml：

 - 添加Elasticsearch相关配置

EsProductAttributeValue.java和EsProduct.java：

 - 定义ES文档结构- 定义了存储在Elasticsearch中的商品和商品属性的数据结构（文档结构），通过注解指定了索引、字段类型、分词器等。关系：决定了Elasticsearch索引的数据模型，部署Elasticsearch后，这些类对应ES中的文档结构。- 不需要中文分词的字段设置成@Field(type = FieldType.Keyword)类型，需要中文分词的设置成@Field(analyzer = "ik_max_word",type = FieldType.Text)类型。

EsProductDao.java：

 - 自定义DAO接口，用于从数据库中查询商品数据，为后续导入Elasticsearch做准备。

EsProductRepository.java：

 - 添加接口用于操作Elasticsearch- 继承ElasticsearchRepository接口，这样就拥有了一些基本的Elasticsearch数据操作方法，同时定义了一个衍生查询方法。

EsProductService.java：

 - 添加接口- `EsProductServiceImpl.java`：EsProductService接口的实现类

EsProductController.java：

 - 暴露REST API接口，供前端或其他服务调用，实现商品的ES相关操作。关系：最终通过Service间接操作Elasticsearch。

7. 整合Mongodb实现文档操作

目录结构

• 

依赖引入：

 - MongoDB相关依赖：org.springframework.boot:spring-boot-starter-data-mongodb

安装Mongodb与Studio 3T

 - 注意Spring Boot与Mongodb版本兼容性，- Mongodb- 4.4.29- 下载zip包，并解压到指定目录，下载地址：https://www.mongodb.com/try/download/community-edition/releases/archive- 新建配置文件mongod.cfg(mongodb.conf)，新建data目录用于存放数据，- 启动服务，执行：mongod --config "配置文件"- 启动shell，执行：mongo- 注册成Windows服务：mongod --config "配置文件" --install --serviceName "MongoDB" - 移除服务：mongod.exe --remove  --config "配置文件" --serviceName "MongoDB"- Studio 3T(Robo 3T)- 下载zip包，并解压到指定目录，执行安装程序，下载地址：https://robomongo.org/

application.yml：

 - 添加Mongodb相关配置

MemberReadHistory.java：

 - 定义 MongoDB 文档结构- 文档对象的ID域添加@Id注解，需要检索的字段添加@Indexed注解。

MemberReadHistoryRepository.java：

 - 用于与 MongoDB 交互- 继承MongoRepository接口，这样就拥有了一些基本的Mongodb数据操作方法，同时定义了一个衍生查询方法。

MemberReadHistoryService.java：

 - 声明业务方法，定义了浏览历史的服务接口，声明了创建、删除、查询浏览历史的方法，便于后续实现具体业务逻辑。

MemberReadHistoryServiceImpl.java：

 - 实现了服务接口，具体通过注入的 MemberReadHistoryRepository（MongoDB JPA 仓库）来操作 MongoDB，实现浏览历史的增删查。

MemberReadHistoryController.java：

 - 暴露 REST API，调用 Service。，供前端或其他服务调用，实现浏览历史的创建、删除、查询功能。

8. 整合RabbitMQ实现延迟消息

目录结构

• 

依赖引入：

 - Spring AMQP相关依赖：org.springframework.boot:spring-boot-starter-amqp

安装Erlang与RabbitMQ

 - Erlang- 下载zip包，并解压到指定目录，配置环境变量，下载地址：https://www.erlang.org/patches/otp-27.3.4.3- RabbitMQ- 下载zip包，并解压到指定目录，下载地址：https://github.com/rabbitmq/rabbitmq-server/releases/tag/v4.1.4- 启动web管理界面：rabbitmq-plugins enable rabbitmq_management- 执行，在后台执行需加 -detached：rabbitmq-server.bat- 访问：http://localhost:15672/- 默认账号：guest/guest- 创建帐号并设置其角色为管理员：mall mall

application.yml：

 - 修改配置，在spring节点下添加RabbitMQ相关配置。

QueueEnum.java：

 - 消息队列和交换机的枚举配置，统一管理队列、交换机、路由键的名称，便于维护和调用。

RabbitMqConfig.java：

 - RabbitMQ的核心配置类。用于配置交换机、队列及队列与交换机的绑定关系。- 定义了两个DirectExchange（普通和延迟），两个Queue（普通和延迟/死信），以及它们的绑定关系。延迟队列设置了死信交换机和路由键，实现消息到期后转发到实际消费队列。

CancelOrderSender.java：

 - 消息发送者。用于向订单延迟消息队列（mall.order.cancel.ttl）里发送消息。- 下单后，调用sendMessage方法向延迟队列发送消息，并设置延迟时间（如30秒），用于订单超时处理。

CancelOrderReceiver.java：

 - 消息接收者。用于从取消订单的消息队列（mall.order.cancel）里接收消息。- 监听实际消费队列（mall.order.cancel），收到死信转发的消息后，调用订单服务取消订单。

OmsPortalOrderService.java 和 OmsPortalOrderServiceImpl.java：

 - 订单服务接口及实现。- generateOrder方法下单后调用CancelOrderSender发送延迟取消消息，cancelOrder方法处理订单取消逻辑。

OrderParam.java：

 - 下单参数的数据传输对象（DTO），用于接收前端下单请求的数据。

OmsPortalOrderController.java：

 - 订单控制器，暴露下单接口，调用服务生成订单。