diff --git a/README.md b/README.md index 3dbc925..ebe5ad5 100644 --- a/README.md +++ b/README.md @@ -1,286 +1,218 @@ -
-

🚀 WebSoft API

-

基于 Spring Boot + MyBatis Plus 的企业级后端API服务

+# WebSoft API -

- Java - Spring Boot - MyBatis Plus - MySQL - Redis - License -

-
+WebSoft API 是一个基于 `Spring Boot + Spring Security + MyBatis-Plus` 的后端 API 项目，覆盖 CMS、商城、支付、系统配置、消息同步等业务场景。 -## 📖 项目简介 +## 当前技术栈 -WebSoft API 是一个基于 **Spring Boot + MyBatis Plus** 构建的现代化企业级后端API服务，采用最新的Java技术栈： +以下信息以仓库当前代码为准： -- **核心框架**：Spring Boot 2.5.4 + Spring Security + Spring AOP -- **数据访问**：MyBatis Plus 3.4.3 + Druid 连接池 -- **数据库**：MySQL + Redis -- **文档工具**：Swagger 3.0 + Knife4j -- **工具库**：Hutool、Lombok、FastJSON +| 技术 | 当前版本 | 说明 | +|------|------|------| +| 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 导入导出 +- 多云对象存储接入 -## 项目演示 -| 后台管理系统 | https://mp.websoft.top | -|--------|-------------------------------------------------------------------------------------------------------------------------------------| -| 测试账号 | 13800010123,123456 -| 正式账号 | [立即注册](https://mp.websoft.top/register/?inviteCode=github) | -| 关注公众号 | ![输入图片说明](https://oss.wsdns.cn/20240327/f1175cc5aae741d3af05484747270bd5.jpeg?x-oss-process=image/resize,m_fixed,w_150/quality,Q_90) | +## 项目结构 - - - -## 🛠️ 技术栈 - -### 核心框架 -| 技术 | 版本 | 说明 | -|------|-------|------| -| Java | 17+ | 编程语言 | -| Spring Boot | 2.5.4 | 微服务框架 | -| Spring Security | 5.5.x | 安全框架 | -| MyBatis Plus | 3.4.3 | ORM框架 | -| MySQL | 8.0+ | 关系型数据库 | -| Redis | 6.0+ | 缓存数据库 | -| Druid | 1.2.6 | 数据库连接池 | - -### 功能组件 -- **Swagger 3.0 + Knife4j** - API文档生成与测试 -- **JWT** - 用户认证与授权 -- **Hutool** - Java工具类库 -- **EasyPOI** - Excel文件处理 -- **阿里云OSS** - 对象存储服务 -- **微信支付/支付宝** - 支付集成 -- **Socket.IO** - 实时通信 -- **MQTT** - 物联网消息传输 - -## 📋 环境要求 - -### 基础环境 -- ☕ **Java 1.8+** -- 🗄️ **MySQL 8.0+** -- 🔴 **Redis 6.0+** -- 📦 **Maven 3.6+** - -### 开发工具 -- **推荐**：IntelliJ IDEA / Eclipse -- **插件**：Lombok Plugin、MyBatis Plugin - -## 🚀 快速开始 - -### 1. 克隆项目 -```bash -git clone https://github.com/websoft-top/mp-java.git -cd mp-java -``` - -### 2. 数据库配置 -```sql --- 创建数据库 -CREATE DATABASE websoft_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; - --- 导入数据库脚本（如果有的话） --- source /path/to/database.sql -``` - -### 3. 配置文件 -编辑 `src/main/resources/application-dev.yml` 文件，配置数据库连接： -```yaml -spring: - datasource: - url: jdbc:mysql://localhost:3306/websoft_db?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8 - username: your_username - password: your_password - redis: - host: localhost - port: 6379 - password: your_redis_password -``` - -### 4. 启动项目 -```bash -# 使用 Maven 启动 -mvn spring-boot:run - -# 或者使用 IDE 直接运行 WebSoftApplication.java -``` - -访问 `http://localhost:9200` 即可看到API服务。 - -### 5. API文档 -启动项目后，访问以下地址查看API文档： -- Swagger UI: `http://localhost:9200/swagger-ui/index.html` -- Knife4j: `http://localhost:9200/doc.html` - -## ⚙️ 配置说明 - -### 数据库配置 -在 `application-dev.yml` 中配置数据库连接： -```yaml -spring: - datasource: - url: jdbc:mysql://localhost:3306/websoft_db - username: root - password: your_password - driver-class-name: com.mysql.cj.jdbc.Driver -``` - -### Redis配置 -```yaml -spring: - redis: - host: localhost - port: 6379 - password: your_redis_password - database: 0 -``` - -### 阿里云OSS配置 -```yaml -config: - endpoint: https://oss-cn-shenzhen.aliyuncs.com - accessKeyId: your_access_key_id - accessKeySecret: your_access_key_secret - bucketName: your_bucket_name - bucketDomain: https://your-domain.com -``` - -### 其他配置 -- **JWT密钥**：`config.token-key` 用于JWT令牌加密 -- **文件上传路径**：`config.upload-path` 本地文件存储路径 -- **邮件服务**：配置SMTP服务器用于发送邮件 - -## 🎯 核心功能 - -### 🔐 用户认证与授权 -- **JWT认证**：基于JSON Web Token的用户认证 -- **Spring Security**：完整的安全框架集成 -- **角色权限**：基于RBAC的权限控制 -- **图形验证码**：防止恶意登录 - -### 📝 内容管理系统(CMS) -- **文章管理**：支持富文本内容管理 -- **媒体文件**：图片/视频文件上传与管理 -- **分类管理**：内容分类与标签管理 -- **SEO优化**：搜索引擎优化支持 - -### 🛒 电商系统 -- **商品管理**：商品信息、规格、库存管理 -- **订单系统**：完整的订单流程管理 -- **支付集成**：支持微信支付、支付宝 -- **物流跟踪**：快递100物流查询集成 - -### 🔧 系统管理 -- **用户管理**：用户信息维护与管理 -- **系统配置**：动态配置管理 -- **日志监控**：系统操作日志记录 -- **数据备份**：数据库备份与恢复 - -### 📊 数据分析 -- **统计报表**：业务数据统计分析 -- **图表展示**：数据可视化展示 -- **导出功能**：Excel数据导出 -- **实时监控**：系统性能监控 - -## 🏗️ 项目结构 - -``` +```text src/main/java/com/gxwebsoft/ -├── WebSoftApplication.java # 启动类 -├── cms/ # 内容管理模块 -│ ├── controller/ # 控制器层 -│ ├── service/ # 业务逻辑层 -│ ├── mapper/ # 数据访问层 -│ └── entity/ # 实体类 -├── shop/ # 商城模块 -│ ├── controller/ -│ ├── service/ -│ ├── mapper/ -│ └── entity/ -├── common/ # 公共模块 -│ ├── core/ # 核心配置 -│ ├── utils/ # 工具类 -│ └── exception/ # 异常处理 -└── resources/ - ├── application.yml # 主配置文件 - ├── application-dev.yml # 开发环境配置 - └── application-prod.yml# 生产环境配置 +├── WebSoftApplication.java +├── app/ # 应用配置、任务、通用业务模块 +├── cms/ # 内容管理 +├── common/ # 公共能力、核心配置、MQ、系统模块 +├── payment/ # 支付领域 +└── shop/ # 商城领域 ``` -## 🔧 开发规范 +资源与配置文件位于 `src/main/resources/`： -### 代码结构 -- **Controller层**：处理HTTP请求，参数验证 -- **Service层**：业务逻辑处理，事务管理 -- **Mapper层**：数据访问，SQL映射 -- **Entity层**：数据实体，数据库表映射 +- `application.yml` +- `application-dev.yml` +- `application-test.yml` +- `application-prod.yml` +- `application-websopy.yml` -### 命名规范 -- **类名**：使用大驼峰命名法（PascalCase） -- **方法名**：使用小驼峰命名法（camelCase） -- **常量**：使用全大写，下划线分隔 -- **包名**：使用小写字母，点分隔 +## 环境要求 -## 📚 API文档 +- JDK 17 +- Maven 3.6+ +- MySQL 8.x +- Redis +- RabbitMQ -项目集成了Swagger和Knife4j，提供完整的API文档： +## 本地开发 -### 访问地址 -- **Swagger UI**: `http://localhost:9200/swagger-ui/index.html` -- **Knife4j**: `http://localhost:9200/doc.html` +### 1. 安装依赖环境 -### 主要接口模块 -- **用户认证**: `/api/auth/**` - 登录、注册、权限验证 -- **用户管理**: `/api/user/**` - 用户CRUD操作 -- **内容管理**: `/api/cms/**` - 文章、媒体文件管理 -- **商城管理**: `/api/shop/**` - 商品、订单管理 -- **系统管理**: `/api/system/**` - 系统配置、日志管理 +确保本地已经启动： -## 🚀 部署指南 +- 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 -# 1. 启动MySQL和Redis服务 -# 2. 创建数据库并导入初始数据 -# 3. 修改配置文件 -# 4. 启动应用 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 -# 1. 打包应用 mvn clean package -Dmaven.test.skip=true - -# 2. 运行jar包 -java -jar target/com-gxwebsoft-modules-1.5.0.jar --spring.profiles.active=prod - -# 3. 使用Docker部署（可选） -docker build -t websoft-api . -docker run -d -p 9200:9200 websoft-api ``` -## 🤝 贡献指南 +打包后运行： -1. Fork 本仓库 -2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) -3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) -4. 推送到分支 (`git push origin feature/AmazingFeature`) -5. 打开 Pull Request +```bash +java -jar target/websopy-api-1.5.0.jar --spring.profiles.active=prod +``` -## 📄 许可证 +## Docker 部署 -本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情 +仓库包含以下文件： -## 📞 联系我们 +- [Dockerfile](/Users/gxwebsoft/JAVA/websopy-java/Dockerfile) +- [docker-compose.yml](/Users/gxwebsoft/JAVA/websopy-java/docker-compose.yml) -- 官网：https://websoft.top -- 邮箱：170083662@qq.top -- QQ群：479713884 +### Dockerfile 当前行为 ---- +- 基础镜像：`openjdk:17-jdk-alpine` +- 容器内默认激活：`SPRING_PROFILES_ACTIVE=prod` +- 暴露端口：`9200` -⭐ 如果这个项目对您有帮助，请给我们一个星标！ \ No newline at end of file +### 注意 + +当前仓库内存在一个端口差异： + +- `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 端口，建议同步更新本文档。