492 lines
17 KiB
Markdown
492 lines
17 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 │ RabbitMQ │ Elasticsearch │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 1.2 技术栈
|
||
|
||
| 层级 | 技术选型 | 说明 |
|
||
|------|--------|------|
|
||
| **框架** | Spring Boot 3.x | Web框架 |
|
||
| **ORM** | MyBatis Plus | 数据访问 |
|
||
| **数据库** | MySQL 8.0 | 主数据存储 |
|
||
| **缓存** | Redis 7.x | 会话、缓存 |
|
||
| **搜索** | Elasticsearch 8.x | Skill搜索 |
|
||
| **消息队列** | RabbitMQ 3.x | 异步处理 |
|
||
| **认证** | JWT + Spring Security | 用户认证 |
|
||
| **文件存储** | 七牛云 / 阿里云OSS | 文件上传 |
|
||
| **支付** | 微信支付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
|
||
}
|
||
```
|
||
|
||
### 4.4 错误码定义
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未授权（需要登录） |
|
||
| 403 | 禁止访问（无权限） |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器错误 |
|
||
| 1001 | 用户不存在 |
|
||
| 1002 | 密码错误 |
|
||
| 1003 | 手机号已注册 |
|
||
| 2001 | Skill不存在 |
|
||
| 2002 | Skill已下架 |
|
||
| 3001 | 积分不足 |
|
||
| 3002 | 积分规则不存在 |
|
||
| 4001 | 订单不存在 |
|
||
| 4002 | 订单状态错误 |
|
||
| 5001 | 支付失败 |
|
||
| 5002 | 充值订单不存在 |
|
||
|
||
## 五、数据库设计
|
||
|
||
### 5.1 用户表
|
||
|
||
```sql
|
||
CREATE TABLE users (
|
||
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '用户ID',
|
||
phone VARCHAR(20) UNIQUE NOT NULL COMMENT '手机号',
|
||
password_hash VARCHAR(255) NOT NULL COMMENT '密码哈希',
|
||
nickname VARCHAR(100) COMMENT '昵称',
|
||
avatar_url VARCHAR(500) COMMENT '头像URL',
|
||
status ENUM('active', 'inactive', 'banned') DEFAULT 'active' COMMENT '状态',
|
||
member_level ENUM('normal', 'silver', 'gold', 'diamond') DEFAULT 'normal' COMMENT '会员等级',
|
||
growth_value INT DEFAULT 0 COMMENT '成长值',
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||
deleted_at TIMESTAMP NULL COMMENT '删除时间',
|
||
INDEX idx_phone (phone),
|
||
INDEX idx_status (status),
|
||
INDEX idx_created_at (created_at)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户表';
|
||
```
|
||
|
||
### 5.2 积分表
|
||
|
||
```sql
|
||
CREATE TABLE user_points (
|
||
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '积分ID',
|
||
user_id BIGINT NOT NULL UNIQUE COMMENT '用户ID',
|
||
available_points INT DEFAULT 0 COMMENT '可用积分',
|
||
frozen_points INT DEFAULT 0 COMMENT '冻结积分',
|
||
total_earned INT DEFAULT 0 COMMENT '累计获取',
|
||
total_consumed INT DEFAULT 0 COMMENT '累计消耗',
|
||
last_sign_in_date DATE COMMENT '最后签到日期',
|
||
sign_in_streak INT DEFAULT 0 COMMENT '连续签到天数',
|
||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||
FOREIGN KEY (user_id) REFERENCES users(id),
|
||
INDEX idx_user_id (user_id)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户积分表';
|
||
```
|
||
|
||
### 5.3 积分流水表
|
||
|
||
```sql
|
||
CREATE TABLE points_records (
|
||
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '流水ID',
|
||
user_id BIGINT NOT NULL COMMENT '用户ID',
|
||
points_type ENUM('earn', 'consume') NOT NULL COMMENT '类型',
|
||
source ENUM('register', 'sign_in', 'invite', 'join_community', 'recharge', 'skill_purchase', 'review', 'activity') NOT NULL COMMENT '来源',
|
||
amount INT NOT NULL COMMENT '积分数量',
|
||
description VARCHAR(255) COMMENT '描述',
|
||
related_id BIGINT COMMENT '关联ID',
|
||
related_type VARCHAR(50) COMMENT '关联类型',
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
FOREIGN KEY (user_id) REFERENCES users(id),
|
||
INDEX idx_user_id (user_id),
|
||
INDEX idx_source (source),
|
||
INDEX idx_created_at (created_at)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='积分流水表';
|
||
```
|
||
|
||
### 5.4 订单表
|
||
|
||
```sql
|
||
CREATE TABLE orders (
|
||
id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '订单ID',
|
||
order_no VARCHAR(50) NOT NULL UNIQUE COMMENT '订单号',
|
||
user_id BIGINT NOT NULL COMMENT '用户ID',
|
||
total_amount DECIMAL(10, 2) NOT NULL COMMENT '总金额',
|
||
paid_amount DECIMAL(10, 2) DEFAULT 0 COMMENT '已支付金额',
|
||
points_used INT DEFAULT 0 COMMENT '使用积分',
|
||
status ENUM('pending', 'paid', 'completed', 'cancelled', 'refunding', 'refunded') DEFAULT 'pending' COMMENT '订单状态',
|
||
payment_method ENUM('wechat', 'alipay', 'points', 'mixed') DEFAULT 'wechat' COMMENT '支付方式',
|
||
remark VARCHAR(500) COMMENT '备注',
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||
paid_at TIMESTAMP NULL COMMENT '支付时间',
|
||
FOREIGN KEY (user_id) REFERENCES users(id),
|
||
INDEX idx_user_id (user_id),
|
||
INDEX idx_status (status),
|
||
INDEX idx_created_at (created_at),
|
||
INDEX idx_order_no (order_no)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='订单表';
|
||
```
|
||
|
||
## 六、配置文件
|
||
|
||
### 6.1 application.yml
|
||
|
||
```yaml
|
||
spring:
|
||
application:
|
||
name: openclaw-backend
|
||
|
||
datasource:
|
||
url: jdbc:mysql://localhost:3306/openclaw?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=UTC
|
||
username: root
|
||
password: wang200314
|
||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||
|
||
redis:
|
||
host: localhost
|
||
port: 6379
|
||
password:
|
||
timeout: 10000ms
|
||
jedis:
|
||
pool:
|
||
max-active: 8
|
||
max-idle: 8
|
||
min-idle: 0
|
||
|
||
jpa:
|
||
hibernate:
|
||
ddl-auto: validate
|
||
show-sql: false
|
||
|
||
jackson:
|
||
default-timezone: GMT+8
|
||
date-format: yyyy-MM-dd HH:mm:ss
|
||
|
||
mybatis-plus:
|
||
mapper-locations: classpath*:/mapper/**/*.xml
|
||
type-aliases-package: com.openclaw.entity
|
||
configuration:
|
||
map-underscore-to-camel-case: true
|
||
log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
|
||
|
||
server:
|
||
port: 8080
|
||
servlet:
|
||
context-path: /
|
||
compression:
|
||
enabled: true
|
||
min-response-size: 1024
|
||
|
||
logging:
|
||
level:
|
||
root: INFO
|
||
com.openclaw: DEBUG
|
||
pattern:
|
||
console: "%d{yyyy-MM-dd HH:mm:ss} - %msg%n"
|
||
file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
|
||
file:
|
||
name: logs/openclaw.log
|
||
max-size: 10MB
|
||
max-history: 30
|
||
```
|
||
|
||
## 七、开发流程
|
||
|
||
### 7.1 本地开发环境启动
|
||
|
||
```bash
|
||
# 1. 启动MySQL
|
||
docker run -d --name mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=root mysql:8.0
|
||
|
||
# 2. 启动Redis
|
||
docker run -d --name redis -p 6379:6379 redis:7-alpine
|
||
|
||
# 3. 启动RabbitMQ
|
||
docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management
|
||
|
||
# 4. 创建数据库
|
||
mysql -u root -p < init.sql
|
||
|
||
# 5. 启动应用
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
### 7.2 代码提交规范
|
||
|
||
```
|
||
feat: 新增用户注册功能
|
||
fix: 修复积分计算错误
|
||
docs: 更新API文档
|
||
refactor: 重构订单服务
|
||
test: 添加支付测试用例
|
||
chore: 更新依赖版本
|
||
```
|
||
|
||
---
|
||
|
||
**文档版本**：v1.0
|
||
**创建日期**：2026-03-16
|