# 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