RuoYi-Vue-Plus/ruoyi-site/ruoyi-h5/README_COMPONENT.md

H5 组件库系统开发完成

开发时间

2026-03-06

功能概述

实现了一个完整的 H5 组件库系统，支持组件分类管理、标签检索、快速应用等功能。

已完成的功能

1. 数据库设计 (5 张表)

• h5_component: 组件表 - 存储组件基本信息和配置数据
• h5_component_category: 分类表 - 存储两级分类结构
• h5_component_category_rel: 组件分类关联表 - 组件与分类的多对多关系
• h5_tag: 标签表 - 存储标签信息
• h5_component_tag_rel: 组件标签关联表 - 组件与标签的多对多关系

2. 核心功能

组件管理

• ✅ 组件 CRUD 操作
• ✅ 分页查询 (支持按类型、关键词、分类、标签筛选)
• ✅ 使用次数统计
• ✅ 点赞数统计
• ✅ 热门组件查询
• ✅ 批量删除

分类管理

• ✅ 两级分类结构 (一级固定 5 大类：文字、图片、扩展、背景、音乐)
• ✅ 一级分类查询
• ✅ 二级分类查询 (按父 ID)
• ✅ 按类型查询分类
• ✅ 分类树形结构
• ✅ 分类 CRUD 操作

标签管理

• ✅ 所有标签查询
• ✅ 热门标签查询
• ✅ 按类型查询标签
• ✅ 标签 CRUD 操作
• ✅ 标签使用次数统计

3. 技术实现

分层架构

com.luban.api
├── controller          # 控制器层
│   ├── H5ComponentController
│   ├── H5ComponentCategoryController
│   └── H5TagController
├── service             # 服务层接口
│   ├── H5ComponentService
│   ├── H5ComponentCategoryService
│   └── H5TagService
├── service.impl        # 服务层实现
│   ├── H5ComponentServiceImpl
│   ├── H5ComponentCategoryServiceImpl
│   └── H5TagServiceImpl
├── dao                 # 数据访问层
│   ├── H5ComponentDao
│   ├── H5ComponentCategoryDao
│   ├── H5TagDao
│   ├── H5ComponentCategoryRelDao
│   └── H5ComponentTagRelDao
├── entity              # 实体类
│   ├── H5Component
│   ├── H5ComponentCategory
│   ├── H5Tag
│   ├── H5ComponentCategoryRel
│   └── H5ComponentTagRel
├── vo                  # 视图对象
│   ├── H5ComponentVO
│   └── Result
└── convert             # 转换类
    └── H5ComponentConvert

技术栈

• Spring Boot 3
• MyBatis-Plus (ORM 框架)
• Lombok (简化代码)
• MapStruct (对象转换)
• Swagger (API 文档)

代码规范

• ✅ 使用 @Data、@EqualsAndHashCode、@NoArgsConstructor、@AllArgsConstructor进行 POJO 类定义
• ✅ MyBatis-Plus映射添加@TableName和@TableId注解
• ✅ 事务一致性保障 (@Transactional 注解)
• ✅ Controller 不直接调用 Repository
• ✅ Controller 返回值不使用 Map 类型
• ✅ ID 字段统一命名为 id
• ✅ 所有类和方法有适当的 Swagger 注解
• ✅ 时间字段使用 Unix 时间戳 (秒级)

4. API 接口列表

组件接口

GET    /h5/component/{id}           # 根据 ID 查询组件
GET    /h5/component/page           # 分页查询组件列表
POST   /h5/component                # 创建组件
PUT    /h5/component/{id}           # 更新组件
DELETE /h5/component/{id}           # 删除组件
DELETE /h5/component/batch          # 批量删除组件
POST   /h5/component/{id}/usage     # 增加使用次数
POST   /h5/component/{id}/like      # 增加点赞数
GET    /h5/component/hot            # 获取热门组件

分类接口

GET    /h5/category/top-level       # 查询所有一级分类
GET    /h5/category/children        # 根据父分类 ID 查询子分类
GET    /h5/category/by-type         # 根据类型查询分类
GET    /h5/category/tree            # 获取分类树形结构
POST   /h5/category                 # 创建分类
PUT    /h5/category/{id}            # 更新分类
DELETE /h5/category/{id}            # 删除分类

标签接口

GET    /h5/tag                      # 查询所有标签
GET    /h5/tag/hot                  # 查询热门标签
GET    /h5/tag/by-type              # 根据类型查询标签
POST   /h5/tag                      # 创建标签
PUT    /h5/tag/{id}                 # 更新标签
DELETE /h5/tag/{id}                 # 删除标签

5. 数据库初始化脚本

位置：ruoyi-site/ruoyi-h5/doc/dml/h5_component.sql

包含:

• 5 张表的建表语句
• 一级分类初始化数据 (固定 5 大类)
• 二级分类示例数据
• 标签示例数据

6. 组件类型说明

根据需求定义的组件类型:

• text: 文字类组件 (标题、正文、艺术字等)
• image: 图片类组件 (产品图、装饰图等)
• form: 表单组件
• map: 地图定位组件
• background: 背景类组件
• music: 音乐音频组件
• extension: 扩展组件 (包含 form、map 等)

7. JSON 数据结构

组件内容使用 JSON 格式存储，支持以下类型:

• image: 包含 url、width、height、transform 等属性
• text: 包含 content、fontFamily、fontSize、color 等属性
• svg: 包含 url、content、colors 等属性
• group: 包含 elements 数组 (可嵌套子元素)
• form: 包含 formData、formSchema、formItems 等属性
• map: 包含 longitude、latitude、address 等属性

下一步工作

阶段 2: 核心业务逻辑

• 组件推荐算法
• 标签智能匹配
• 组件收藏功能
• 用户上传自定义组件

阶段 3: 性能优化

• Redis 缓存热门数据
• 搜索引擎集成 (Elasticsearch)
• 图片 CDN 加速
• 批量操作优化

阶段 4: 扩展功能

• 组件版本管理
• 组件评价系统
• 组件下载统计
• 组件分享功能

编译验证

✅ 所有代码编译通过，无错误

使用说明

1. 执行数据库脚本：doc/dml/h5_component.sql
2. 启动项目后访问 Swagger 文档查看 API
3. 使用 Postman 或前端项目进行接口测试

注意事项

• 所有时间字段使用 Unix 时间戳 (秒级)
• 组件内容以 JSON 字符串形式存储
• 分类只支持两层结构，不支持多级嵌套
• 删除分类前会检查是否有子分类