blandarebiter/number

Fork 0

Files

Developer 70bedcf241 Initial commit

2026-03-17 12:09:43 +08:00

17 KiB

Raw Blame History

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

17 KiB Raw Blame History Unescape Escape

OpenClaw Skills 后端Java架构设计 - 单体架构

一、架构概览

1.1 整体架构图

1.2 技术栈

二、项目结构

三、核心模块设计

3.1 用户模块 (User Module)

3.2 Skill模块 (Skill Module)

3.3 积分模块 (Points Module)

3.4 订单模块 (Order Module)

3.5 支付模块 (Payment Module)

3.6 邀请模块 (Invite Module)

四、API响应格式

4.1 成功响应

4.2 分页响应

4.3 错误响应

4.4 错误码定义

五、数据库设计

5.1 用户表

5.2 积分表

5.3 积分流水表

5.4 订单表

六、配置文件

6.1 application.yml

七、开发流程

7.1 本地开发环境启动

7.2 代码提交规范

17 KiB

Raw Blame History