310 lines
11 KiB
Markdown
310 lines
11 KiB
Markdown
# 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
|