11 KiB
11 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 │ 腾讯云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 成功响应
{
"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
}
五、错误码定义
| 错误码 | 说明 |
|---|---|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权（需要登录） |
| 403 | 禁止访问（无权限） |
| 404 | 资源不存在 |
| 500 | 服务器错误 |
| 1001 | 用户不存在 |
| 1002 | 密码错误 |
| 1003 | 手机号已注册 |
| 2001 | Skill不存在 |
| 2002 | Skill已下架 |
| 3001 | 积分不足 |
| 3002 | 积分规则不存在 |
| 4001 | 订单不存在 |
| 4002 | 订单状态错误 |
| 5001 | 支付失败 |
| 5002 | 充值订单不存在 |
文档版本：v1.0
创建日期：2026-03-16