WebSoft API

WebSoft API 是一个基于 Spring Boot + Spring Security + MyBatis-Plus 的后端 API 项目，覆盖 CMS、商城、支付、系统配置、消息同步等业务场景。

当前技术栈

以下信息以仓库当前代码为准：

技术	当前版本	说明
Java	17	运行时与编译版本
Spring Boot	2.7.18	应用基础框架
Spring Security	5.7.x（随 Boot 2.7.18）	认证与授权
MyBatis-Plus	3.4.3.3	ORM 与通用 CRUD
MyBatis-Plus-Join	1.4.5	连表查询扩展
Druid	1.2.20	数据源连接池
Redis	Starter 管理	缓存
RabbitMQ	Starter 管理	消息队列
SpringDoc OpenAPI	1.7.0	OpenAPI 文档
Knife4j	4.3.0	接口文档增强
Maven	3.6+	构建工具

主要能力

• 用户认证与权限控制
• CMS 内容管理
• 商城商品、订单、优惠券
• 微信支付、支付宝支付
• Redis 缓存
• RabbitMQ 消息同步
• WebSocket 实时通信
• Excel 导入导出
• 多云对象存储接入

项目结构

src/main/java/com/gxwebsoft/
├── WebSoftApplication.java
├── app/         # 应用配置、任务、通用业务模块
├── cms/         # 内容管理
├── common/      # 公共能力、核心配置、MQ、系统模块
├── payment/     # 支付领域
└── shop/        # 商城领域

资源与配置文件位于 src/main/resources/：

• application.yml
• application-dev.yml
• application-test.yml
• application-prod.yml
• application-websopy.yml

环境要求

• JDK 17
• Maven 3.6+
• MySQL 8.x
• Redis
• RabbitMQ

本地开发

1. 安装依赖环境

确保本地已经启动：

• MySQL
• Redis
• RabbitMQ

2. 配置开发环境

默认激活的 Spring Profile 在 src/main/resources/application.yml 中配置为 dev。

开发环境配置文件为：

• src/main/resources/application-dev.yml

建议优先使用环境变量或本地未提交配置覆盖以下信息：

• 数据库连接
• Redis 连接
• RabbitMQ 连接
• 邮件账号
• OSS / 支付 / 第三方平台密钥

3. 启动项目

mvn spring-boot:run

或在 IDE 中直接运行启动类：

• WebSoftApplication.java

4. 访问地址

开发环境默认端口是 9200：

• 接口根地址：http://localhost:9200
• Swagger UI：http://localhost:9200/swagger-ui/index.html
• Knife4j：http://localhost:9200/doc.html

测试环境默认端口是 9300，生产环境默认端口是 9500。

配置说明

多环境配置

• dev：本地开发
• test：测试环境
• prod：生产环境
• websopy：额外业务环境配置

文件上传

主配置中定义了上传目录相关参数，生产部署前请根据服务器目录调整：

• config.upload-path
• config.local-upload-path

证书与支付

项目内包含微信支付、支付宝证书目录和密钥相关配置。建议：

• 不要在仓库中保存真实密钥
• 使用环境变量、挂载文件或配置中心注入
• 区分开发和生产证书

打包与运行

Maven 打包

mvn clean package -Dmaven.test.skip=true

打包后运行：

java -jar target/websopy-api-1.5.0.jar --spring.profiles.active=prod

Docker 部署

仓库包含以下文件：

• Dockerfile
• docker-compose.yml

Dockerfile 当前行为

• 基础镜像：openjdk:17-jdk-alpine
• 容器内默认激活：SPRING_PROFILES_ACTIVE=prod
• 暴露端口：9200

注意

当前仓库内存在一个端口差异：

• application-prod.yml 默认端口是 9500
• Dockerfile 和 docker-compose.yml 仍按 9200 编排

如果直接按当前 Docker 配置部署，建议先统一端口设置后再上线，避免健康检查和端口映射不一致。

构建镜像

docker build -t websopy-api .

运行容器

以下命令仅适用于你已经把应用监听端口与 Docker 映射端口统一为 9200 的情况：

docker run -d \
  --name websopy-api \
  -p 9200:9200 \
  -e SPRING_PROFILES_ACTIVE=prod \
  websopy-api

使用 Compose

docker-compose.yml 同样建议在统一端口后再直接使用：

docker compose up -d --build

接口文档

项目当前使用 SpringDoc OpenAPI + Knife4j：

• Swagger UI：/swagger-ui/index.html
• Knife4j：/doc.html

开发说明

代码分层

• controller：接口层
• service：业务层
• mapper：数据访问层
• entity / dto / vo / param：模型层

构建说明

• src/main/java 下同时存放了 Java 代码和 *Mapper.xml
• Maven 构建已显式把 *Mapper.xml 作为资源文件打包

文档维护说明

历史 README 中的 Java 1.8、Spring Boot 2.5.4、部分目录结构与当前代码不一致，本次已按现有仓库状态更新。后续如果升级到 Spring Boot 3.x 或调整 Docker 端口，建议同步更新本文档。