17 KiB
17 KiB
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 成功响应
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"name": "张三"
},
"timestamp": 1710604800000
}
4.2 分页响应
{
"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 错误响应
{
"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 用户表
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 积分表
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 积分流水表
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 订单表
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
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 本地开发环境启动
# 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