初始化
This commit is contained in:
218
README.md
Normal file
218
README.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# 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 导入导出
|
||||
- 多云对象存储接入
|
||||
|
||||
## 项目结构
|
||||
|
||||
```text
|
||||
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](/Users/gxwebsoft/JAVA/websopy-java/src/main/resources/application.yml:5) 中配置为 `dev`。
|
||||
|
||||
开发环境配置文件为：
|
||||
|
||||
- [src/main/resources/application-dev.yml](/Users/gxwebsoft/JAVA/websopy-java/src/main/resources/application-dev.yml)
|
||||
|
||||
建议优先使用环境变量或本地未提交配置覆盖以下信息：
|
||||
|
||||
- 数据库连接
|
||||
- Redis 连接
|
||||
- RabbitMQ 连接
|
||||
- 邮件账号
|
||||
- OSS / 支付 / 第三方平台密钥
|
||||
|
||||
### 3. 启动项目
|
||||
|
||||
```bash
|
||||
mvn spring-boot:run
|
||||
```
|
||||
|
||||
或在 IDE 中直接运行启动类：
|
||||
|
||||
- [WebSoftApplication.java](/Users/gxwebsoft/JAVA/websopy-java/src/main/java/com/gxwebsoft/WebSoftApplication.java:25)
|
||||
|
||||
### 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 打包
|
||||
|
||||
```bash
|
||||
mvn clean package -Dmaven.test.skip=true
|
||||
```
|
||||
|
||||
打包后运行：
|
||||
|
||||
```bash
|
||||
java -jar target/websopy-api-1.5.0.jar --spring.profiles.active=prod
|
||||
```
|
||||
|
||||
## Docker 部署
|
||||
|
||||
仓库包含以下文件：
|
||||
|
||||
- [Dockerfile](/Users/gxwebsoft/JAVA/websopy-java/Dockerfile)
|
||||
- [docker-compose.yml](/Users/gxwebsoft/JAVA/websopy-java/docker-compose.yml)
|
||||
|
||||
### Dockerfile 当前行为
|
||||
|
||||
- 基础镜像：`openjdk:17-jdk-alpine`
|
||||
- 容器内默认激活：`SPRING_PROFILES_ACTIVE=prod`
|
||||
- 暴露端口：`9200`
|
||||
|
||||
### 注意
|
||||
|
||||
当前仓库内存在一个端口差异：
|
||||
|
||||
- `application-prod.yml` 默认端口是 `9500`
|
||||
- `Dockerfile` 和 `docker-compose.yml` 仍按 `9200` 编排
|
||||
|
||||
如果直接按当前 Docker 配置部署，建议先统一端口设置后再上线，避免健康检查和端口映射不一致。
|
||||
|
||||
### 构建镜像
|
||||
|
||||
```bash
|
||||
docker build -t websopy-api .
|
||||
```
|
||||
|
||||
### 运行容器
|
||||
|
||||
以下命令仅适用于你已经把应用监听端口与 Docker 映射端口统一为 `9200` 的情况：
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name websopy-api \
|
||||
-p 9200:9200 \
|
||||
-e SPRING_PROFILES_ACTIVE=prod \
|
||||
websopy-api
|
||||
```
|
||||
|
||||
### 使用 Compose
|
||||
|
||||
`docker-compose.yml` 同样建议在统一端口后再直接使用：
|
||||
|
||||
```bash
|
||||
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 端口，建议同步更新本文档。
|
||||
Reference in New Issue
Block a user