Initial commit
This commit is contained in:
Developer
309
后端架构设计/01-单体架构总体设计.md
Normal file
309
后端架构设计/01-单体架构总体设计.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# OpenClaw Skills 后端Java架构设计 - 单体架构
|
||||
|
||||
## 一、架构概览
|
||||
|
||||
### 1.1 整体架构图
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 前端应用层 │
|
||||
│ Web / 小程序 / App │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 单体应用 (Spring Boot) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Controller 层 (API接口) │ │
|
||||
│ │ UserController SkillController OrderController ... │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Service 层 (业务逻辑) │ │
|
||||
│ │ UserService SkillService PointsService ... │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ ↓ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ Repository 层 (数据访问) │ │
|
||||
│ │ UserRepository SkillRepository OrderRepository ... │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 基础设施层 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ MySQL 8.0 │ Redis 7.x │ 腾讯云COS（文件存储） │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 1.2 技术栈
|
||||
|
||||
| 层级 | 技术选型 | 说明 |
|
||||
|------|--------|------|
|
||||
| **框架** | Spring Boot 3.x | Web框架 |
|
||||
| **ORM** | MyBatis Plus | 数据访问 |
|
||||
| **数据库** | MySQL 8.0 | 主数据存储 |
|
||||
| **缓存** | Redis 7.x | 会话、缓存、分布式锁 |
|
||||
| **认证** | JWT + Spring Security | 用户认证 |
|
||||
| **文件存储** | 腾讯云COS | 图片/文件上传存储 |
|
||||
| **支付** | 微信支付SDK / 支付宝SDK | 支付集成 |
|
||||
| **部署** | Docker | 容器化 |
|
||||
|
||||
## 二、项目结构
|
||||
|
||||
```
|
||||
openclaw-backend/
|
||||
├── src/main/java/com/openclaw/
|
||||
│ ├── controller/ # 控制层
|
||||
│ │ ├── UserController.java
|
||||
│ │ ├── SkillController.java
|
||||
│ │ ├── OrderController.java
|
||||
│ │ ├── PointsController.java
|
||||
│ │ ├── PaymentController.java
|
||||
│ │ └── InviteController.java
|
||||
│ │
|
||||
│ ├── service/ # 业务层
|
||||
│ │ ├── UserService.java
|
||||
│ │ ├── SkillService.java
|
||||
│ │ ├── OrderService.java
|
||||
│ │ ├── PointsService.java
|
||||
│ │ ├── PaymentService.java
|
||||
│ │ ├── InviteService.java
|
||||
│ │ └── impl/
|
||||
│ │ ├── UserServiceImpl.java
|
||||
│ │ ├── SkillServiceImpl.java
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ ├── repository/ # 数据访问层
|
||||
│ │ ├── UserRepository.java
|
||||
│ │ ├── SkillRepository.java
|
||||
│ │ ├── OrderRepository.java
|
||||
│ │ ├── PointsRepository.java
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ ├── entity/ # 实体类
|
||||
│ │ ├── User.java
|
||||
│ │ ├── Skill.java
|
||||
│ │ ├── Order.java
|
||||
│ │ ├── UserPoints.java
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ ├── dto/ # 数据传输对象
|
||||
│ │ ├── UserRegisterDTO.java
|
||||
│ │ ├── SkillListDTO.java
|
||||
│ │ ├── OrderCreateDTO.java
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ ├── config/ # 配置类
|
||||
│ │ ├── SecurityConfig.java
|
||||
│ │ ├── RedisConfig.java
|
||||
│ │ ├── MybatisPlusConfig.java
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ ├── exception/ # 异常处理
|
||||
│ │ ├── BusinessException.java
|
||||
│ │ ├── GlobalExceptionHandler.java
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ ├── util/ # 工具类
|
||||
│ │ ├── JwtUtil.java
|
||||
│ │ ├── EncryptUtil.java
|
||||
│ │ ├── IdGenerator.java
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ ├── constant/ # 常量
|
||||
│ │ ├── ErrorCode.java
|
||||
│ │ ├── PointsConstant.java
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ ├── interceptor/ # 拦截器
|
||||
│ │ └── AuthInterceptor.java
|
||||
│ │
|
||||
│ ├── listener/ # 消息监听
|
||||
│ │ ├── OrderEventListener.java
|
||||
│ │ ├── PaymentEventListener.java
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ └── OpenclawApplication.java # 启动类
|
||||
│
|
||||
├── src/main/resources/
|
||||
│ ├── application.yml # 主配置
|
||||
│ ├── application-dev.yml # 开发环境
|
||||
│ ├── application-prod.yml # 生产环境
|
||||
│ ├── db/
|
||||
│ │ └── migration/
|
||||
│ │ ├── V1__init_users.sql
|
||||
│ │ ├── V2__init_skills.sql
|
||||
│ │ ├── V3__init_orders.sql
|
||||
│ │ └── ...
|
||||
│ └── logback-spring.xml # 日志配置
|
||||
│
|
||||
├── pom.xml # Maven配置
|
||||
├── Dockerfile # Docker配置
|
||||
├── docker-compose.yml # 容器编排
|
||||
└── README.md # 项目说明
|
||||
```
|
||||
|
||||
## 三、核心模块设计
|
||||
|
||||
### 3.1 用户模块 (User Module)
|
||||
|
||||
**职责**：用户注册、登录、个人信息管理
|
||||
|
||||
**核心表**：
|
||||
- `users` - 用户基本信息
|
||||
- `user_profiles` - 用户详细资料
|
||||
- `user_auth` - 第三方授权
|
||||
|
||||
**关键API**：
|
||||
- POST /api/v1/users/register - 注册
|
||||
- POST /api/v1/users/login - 登录
|
||||
- GET /api/v1/users/profile - 获取个人信息
|
||||
- PUT /api/v1/users/profile - 更新个人信息
|
||||
- POST /api/v1/users/logout - 登出
|
||||
|
||||
### 3.2 Skill模块 (Skill Module)
|
||||
|
||||
**职责**：Skill管理、浏览、搜索、下载
|
||||
|
||||
**核心表**：
|
||||
- `skills` - Skill基本信息
|
||||
- `skill_categories` - 分类
|
||||
- `skill_reviews` - 评价评论
|
||||
- `skill_downloads` - 下载记录
|
||||
|
||||
**关键API**：
|
||||
- GET /api/v1/skills - 列表
|
||||
- GET /api/v1/skills/{id} - 详情
|
||||
- POST /api/v1/skills - 上传Skill
|
||||
- GET /api/v1/skills/search - 搜索
|
||||
- POST /api/v1/skills/{id}/reviews - 发表评价
|
||||
|
||||
### 3.3 积分模块 (Points Module)
|
||||
|
||||
**职责**：积分获取、消耗、明细
|
||||
|
||||
**核心表**：
|
||||
- `user_points` - 用户积分账户
|
||||
- `points_records` - 积分流水
|
||||
- `points_rules` - 积分规则
|
||||
|
||||
**关键API**：
|
||||
- GET /api/v1/points/balance - 获取余额
|
||||
- GET /api/v1/points/records - 积分明细
|
||||
- POST /api/v1/points/sign-in - 签到
|
||||
- POST /api/v1/points/consume - 消耗积分
|
||||
|
||||
### 3.4 订单模块 (Order Module)
|
||||
|
||||
**职责**：订单创建、支付、退款
|
||||
|
||||
**核心表**：
|
||||
- `orders` - 订单主表
|
||||
- `order_items` - 订单项
|
||||
- `order_refunds` - 退款记录
|
||||
|
||||
**关键API**：
|
||||
- POST /api/v1/orders - 创建订单
|
||||
- GET /api/v1/orders/{id} - 订单详情
|
||||
- POST /api/v1/orders/{id}/pay - 支付
|
||||
- POST /api/v1/orders/{id}/refund - 申请退款
|
||||
|
||||
### 3.5 支付模块 (Payment Module)
|
||||
|
||||
**职责**：支付处理、充值
|
||||
|
||||
**核心表**：
|
||||
- `recharge_orders` - 充值订单
|
||||
- `payment_records` - 支付记录
|
||||
|
||||
**关键API**：
|
||||
- POST /api/v1/payments/recharge - 发起充值
|
||||
- POST /api/v1/payments/callback - 支付回调
|
||||
- GET /api/v1/payments/records - 支付记录
|
||||
|
||||
### 3.6 邀请模块 (Invite Module)
|
||||
|
||||
**职责**：邀请码、邀请奖励
|
||||
|
||||
**核心表**：
|
||||
- `invite_codes` - 邀请码
|
||||
- `invite_records` - 邀请记录
|
||||
|
||||
**关键API**：
|
||||
- POST /api/v1/invites/generate - 生成邀请码
|
||||
- GET /api/v1/invites/records - 邀请记录
|
||||
|
||||
## 四、API响应格式
|
||||
|
||||
### 4.1 成功响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"name": "张三"
|
||||
},
|
||||
"timestamp": 1710604800000
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 分页响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"records": [
|
||||
{ "id": 1, "name": "Skill1" },
|
||||
{ "id": 2, "name": "Skill2" }
|
||||
],
|
||||
"total": 100,
|
||||
"size": 10,
|
||||
"current": 1,
|
||||
"pages": 10
|
||||
},
|
||||
"timestamp": 1710604800000
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 错误响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "请求参数错误",
|
||||
"data": null,
|
||||
"timestamp": 1710604800000
|
||||
}
|
||||
```
|
||||
|
||||
## 五、错误码定义
|
||||
|
||||
| 错误码 | 说明 |
|
||||
|--------|------|
|
||||
| 200 | 成功 |
|
||||
| 400 | 请求参数错误 |
|
||||
| 401 | 未授权（需要登录） |
|
||||
| 403 | 禁止访问（无权限） |
|
||||
| 404 | 资源不存在 |
|
||||
| 500 | 服务器错误 |
|
||||
| 1001 | 用户不存在 |
|
||||
| 1002 | 密码错误 |
|
||||
| 1003 | 手机号已注册 |
|
||||
| 2001 | Skill不存在 |
|
||||
| 2002 | Skill已下架 |
|
||||
| 3001 | 积分不足 |
|
||||
| 3002 | 积分规则不存在 |
|
||||
| 4001 | 订单不存在 |
|
||||
| 4002 | 订单状态错误 |
|
||||
| 5001 | 支付失败 |
|
||||
| 5002 | 充值订单不存在 |
|
||||
|
||||
---
|
||||
|
||||
**文档版本**：v1.0
|
||||
**创建日期**：2026-03-16
|
||||
Reference in New Issue
Block a user