仿华为商城鸿蒙应用：HarmonyOS ArkTS + Spring Boot 全栈项目实战

本项目是一个面向课程设计的仿华为商城鸿蒙应用，使用 HarmonyOS ArkTS/ArkUI 实现移动端界面，使用 Spring Boot + JPA + MySQL 提供后端服务，完成从商品浏览、搜索、购物车到下单、订单和收藏的完整电商流程，并接入 OpenCode Zen 免费模型实现 AI 导购。
项目仅用于学习和课程演示，不代表华为官方应用，也不建议直接用于商业用途。

效果展示

一、项目介绍

这个项目的目标不是只做几个静态页面，而是尽量还原一个移动商城的完整使用流程：

• 首页轮播图、分类入口、运营楼层和商品推荐
• 分类浏览和商品瀑布流
• 关键词搜索和热门搜索词
• 商品详情、多图、价格、原价、标签、库存和销量
• 登录、注册、个人中心
• JWT 登录态持久化
• 加入购物车、修改数量、勾选、全选和删除
• 选择收货地址、确认金额、提交订单
• 订单列表和订单详情
• 支付、取消订单、确认收货
• 收货地址增删改查和默认地址设置
• 收藏商品和收藏列表
• AI 导购多轮对话
• AI 回复中的商品标记解析为可点击商品卡片

整体业务流程如下：

浏览商品 → 查看详情 → 登录 → 加入购物车
        → 选择地址 → 提交订单 → 订单管理
        → 收藏商品 / AI 导购 / 搜索商品

二、技术栈

1. 鸿蒙前端

• HarmonyOS
• ArkTS
• ArkUI 声明式 UI
• DevEco Studio 6.0
• API 20
• @kit.NetworkKit 网络请求
• @kit.ArkData preferences 持久化
• AppStorage 响应式状态管理
• Tabs、Swiper、List、Grid 等 ArkUI 组件

前端按照功能进行分层：

• common：网络请求、模型、路由、登录态和全局配置
• components：商品卡片、标题栏、空状态和错误状态等公共组件
• views：底部 Tab 页面
• pages：详情、搜索、登录、注册、结算、订单、地址、收藏和 AI 导购页面

2. Spring Boot 后端

• Spring Boot 3.3.5
• Spring Web
• Spring Data JPA
• Hibernate ORM
• Validation
• MySQL Connector/J
• JJWT 0.12.6
• BCrypt 密码加密
• Lombok
• Maven

后端采用 Controller、Service、Repository、Entity、DTO 的分层结构：

Controller：接收 HTTP 请求，返回统一响应
    ↓
Service：编写业务逻辑和事务
    ↓
Repository：通过 Spring Data JPA 访问数据库
    ↓
Entity：映射数据库表

3. 数据库

• MySQL 8.0
• Docker Compose
• 宿主机端口：3307
• 容器端口：3306
• 数据卷：vmall-mysql-data

项目主要包含以下数据表：

• t_user：用户
• t_category：商品分类
• t_product：商品
• t_banner：轮播图
• t_cart_item：购物车
• t_order：订单
• t_order_item：订单项
• t_address：收货地址
• t_favorite：收藏

三、项目目录

keshe-hongmeng/
├── backend/
│   ├── docker-compose.yml
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/vmall/
│       │   ├── common/       # 统一响应、异常处理、分页等
│       │   ├── config/       # 配置、初始化数据、Web 配置
│       │   ├── controller/   # REST 接口
│       │   ├── dto/          # 请求和响应对象
│       │   ├── entity/       # JPA 实体类
│       │   ├── repository/   # 数据访问层
│       │   ├── security/     # JWT 拦截和解析
│       │   └── service/      # 业务服务
│       └── resources/
│           ├── application.yml
│           ├── seed/
│           │   ├── catalog.json
│           │   └── banners.json
│           └── static/images/
│
├── frontend/VmallApp/
│   ├── AppScope/
│   ├── entry/
│   │   └── src/main/ets/
│   │       ├── common/
│   │       ├── components/
│   │       ├── views/
│   │       └── pages/
│   ├── build-profile.json5
│   ├── hvigorfile.ts
│   └── oh-package.json5
│
├── _assets/                  # 原始图片和数据素材
├── docs/                     # 项目文档或课程报告
└── README.md

四、运行环境

开始运行前，需要准备：

• Docker Desktop
• JDK 17
• Maven
• DevEco Studio 6.0
• HarmonyOS SDK/API 20
• HarmonyOS 真机或 DevEco 模拟器
• 真机调试时通常需要登录华为开发者账号并完成自动签名

五、后端运行

1. 启动 MySQL

进入后端目录：

cd backend
docker compose up -d

查看容器状态：

docker ps

当看到 vmall-mysql 状态为 healthy，说明 MySQL 已经启动。

项目的 Docker 配置会将：

宿主机 localhost:3307 → 容器内 MySQL:3306

映射到后端数据库连接配置。

2. 数据库和表是怎样初始化的

项目没有单独维护一份 CREATE TABLE SQL，初始化过程由三部分完成：

Docker MySQL

docker-compose.yml 中的 MYSQL_DATABASE 负责在第一次使用空数据卷时创建 vmall 数据库。

Hibernate

application.yml 中配置：

spring:
  jpa:
    hibernate:
      ddl-auto: update

后端启动时，Hibernate 会根据 Entity 实体类自动创建或更新 t_user、t_product、t_order 等业务表。

DataInitializer

后端启动完成后，DataInitializer 会读取：

src/main/resources/seed/catalog.json
src/main/resources/seed/banners.json

当商品表为空时，自动导入：

• 6 个分类
• 28 件商品
• 5 张轮播图
• demo 演示账号
• 一条默认收货地址

如果数据库中已经有商品数据，程序会跳过商品和轮播图的重复导入，不会每次启动都重置数据库。

3. 启动 Spring Boot

cd backend
mvn spring-boot:run

后端默认运行在：

http://localhost:8080

可以用浏览器验证：

商品列表：http://localhost:8080/api/products
分类列表：http://localhost:8080/api/categories
轮播图：http://localhost:8080/api/banners
图片资源：http://localhost:8080/images/products/mate70-pro.jpg

六、鸿蒙前端运行

1. 打开工程

使用 DevEco Studio 打开：

frontend/VmallApp

第一次打开工程时，等待 IDE 同步 Hvigor 和 ohpm 依赖。如果出现 Sync Now 或依赖修复提示，按提示完成同步。

2. 配置后端地址

前端需要知道后端电脑的 IP 地址。项目支持两种方式：

• 修改 entry/src/main/ets/common/constants/ApiConfig.ets 中的默认地址
• 运行 App 后进入“我的 → 服务器设置”修改并保存后端地址

如果使用真机，不能把地址写成手机自己的 127.0.0.1，需要填写运行 Spring Boot 的电脑局域网 IPv4，例如：

http://192.168.1.100:8080

手机和电脑需要连接同一个局域网，并确保电脑防火墙允许 8080 端口访问。

模拟器是否可以使用 127.0.0.1 与 DevEco 版本和网络模式有关，遇到连接失败时，优先使用电脑的局域网 IP。

3. 运行应用

在 DevEco Studio 中：

1. 选择模拟器或已连接的真机
2. 检查签名配置
3. 点击 Run
4. 等待应用安装和启动

如果遇到 Hvigor daemon 或 No Idle daemon can be found，可以尝试重启 DevEco Studio、重新同步工程、清理后重新构建，或者更换真实模拟器运行。

七、统一接口设计

后端返回统一结构：

{
  "code": 0,
  "message": "success",
  "data": {}
}

其中：

• code = 0 表示请求成功
• message 表示提示信息
• data 表示具体业务数据
• 需要登录的接口通过 Authorization: Bearer 传递 JWT

主要接口如下：

模块	接口示例	说明
认证	POST /api/auth/register	注册
认证	POST /api/auth/login	登录并返回 JWT
认证	GET /api/auth/me	获取当前用户
商品	GET /api/products	商品列表和搜索
商品	GET /api/products/{id}	商品详情
商品	GET /api/products/recommend	推荐商品
分类	GET /api/categories	分类列表
轮播	GET /api/banners	首页轮播图
购物车	GET /api/cart	查看购物车
购物车	POST /api/cart	加入购物车
购物车	PUT /api/cart/{id}	修改数量或选中状态
订单	POST /api/orders	提交订单
订单	GET /api/orders	查询订单
订单	PUT /api/orders/{id}/pay	支付订单
订单	PUT /api/orders/{id}/cancel	取消订单
订单	PUT /api/orders/{id}/receive	确认收货
地址	GET/POST /api/addresses	查询或新增地址
收藏	GET/POST /api/favorites	查询或收藏商品
AI	POST /api/ai/chat	AI 导购对话

八、核心功能实现

1. JWT 登录认证

用户登录成功后，后端使用 JWT 生成登录令牌：

登录请求
  ↓
校验用户名和 BCrypt 密码
  ↓
生成 JWT
  ↓
前端 preferences 持久化 token
  ↓
后续请求自动添加 Authorization 请求头
  ↓
后端拦截器解析 token 并获得用户 ID

密码不会以明文保存，后端通过 BCrypt 加密后写入用户表。

JWT 适合这种前后端分离的小型项目：后端不需要保存 Session，前端只需要保存 token 即可维持登录状态。

课设演示账号：demo / 123456。正式项目中应该修改默认密码和 JWT 密钥。

2. 购物车合并

用户登录后加入同一件商品时，后端不会简单地插入重复记录，而是根据用户 ID 和商品 ID 查询购物车：

• 已存在：累加商品数量
• 不存在：创建新的购物车记录
• 数量修改时校验库存
• 删除商品时删除对应记录
• 全选时批量修改 selected 状态

3. 下单事务

提交订单时，后端在事务中完成：

1. 校验用户和收货地址
2. 查询购物车中选中的商品
3. 校验商品库存
4. 扣减库存
5. 计算商品金额和订单总金额
6. 创建订单
7. 创建订单项快照
8. 清理已购买的购物车记录

订单项保存商品名称、价格、图片等快照信息，即使商品之后改价，历史订单仍然能够显示下单时的数据。

4. 前端网络层

前端统一封装 HTTP 请求，主要负责：

• 拼接 BASE_URL 和 API 路径
• 设置 JSON 请求头
• 自动添加 JWT
• 解析后端统一响应体
• 处理 401 登录失效
• 统一提示网络错误

这样页面只调用 Api.products()、Api.login() 等方法，不需要在每个页面重复编写网络请求代码。

九、AI 导购实现

AI 导购接口使用 OpenAI 兼容协议：

POST https://opencode.ai/zen/v1/chat/completions

当前项目配置的模型是：

app:
  ai:
    base-url: https://opencode.ai/zen/v1
    api-key: ""
    model: mimo-v2.5-free

后端不会让模型完全自由编造商品，而是先从数据库读取在售商品，拼接成商品目录，再注入 system prompt：

你是华为商城 App 内的 AI 导购员……
只能推荐商品目录中存在的商品……
每件推荐商品后输出 [[product:商品ID]]

模型返回类似：

如果你主要拍照，推荐 HUAWEI Mate 70 Pro[[product:1]]，影像能力更强。

后端解析 [[product:1]]，再根据商品 ID 查询真实商品，最终返回商品卡片。

这种设计结合了：

• 角色提示词
• 商品目录注入
• 多轮对话历史
• 结构化商品标记
• 后端商品卡片解析

它可以看作一个轻量级 RAG 思路：商品事实来自数据库，模型负责理解需求和组织语言。

免费模型可能受到共享额度和并发限制，偶尔返回 429 Too Many Requests。这通常是上游免费服务限流，可以稍后重试，或者在 OpenCode 配置 API Key。AI 不可用时，商品浏览、购物车、下单等普通商城功能不受影响。

十、运行时常见问题

1. 后端连接不上数据库

检查：

docker ps

确认 vmall-mysql 正常运行，并确认后端连接的是 localhost:3307。

如果修改了 Docker 映射端口，也要同步修改 application.yml 的 JDBC URL。

2. 前端提示网络请求失败

重点检查：

• Spring Boot 是否运行在 8080
• ApiConfig.ets 中的地址是否正确
• 真机和电脑是否在同一个 WiFi
• Windows 防火墙是否放行 8080
• 地址末尾不要重复添加 /

3. 表已经存在但没有数据

检查 app.seed.enabled 是否为 true。如果商品表已经有数据，初始化器会主动跳过商品和轮播图导入，这是为了防止重复插入。

如果是全新的演示环境，可以删除 Docker 数据卷后重新初始化，但这会清空数据库中的所有数据，操作前要先备份。

4. AI 导购返回 429

这不是 MySQL 问题，也不一定是项目代码问题，通常是 OpenCode 免费模型的临时限流。等待后重试，或改用当前可用的其他免费模型并重启后端。

5. DevEco 构建失败

可以依次尝试：

1. 重启 DevEco Studio
2. 重新同步 Hvigor/ohpm 依赖
3. 清理工程后重新构建
4. 检查 SDK、API 版本和签名配置
5. 从预览器切换到模拟器或真机运行

十一、项目总结

这个项目将鸿蒙前端、Java 后端、关系型数据库和大模型服务串联起来，形成了一个相对完整的移动端电商系统。

从课程设计角度看，项目包含以下知识点：

1. 使用 ArkUI 声明式语法组织复杂页面
2. 使用 Tabs 和路由完成多页面导航
3. 使用 preferences 保存登录态和服务器地址
4. 使用 REST API 完成前后端分离
5. 使用 JPA 实体映射和事务完成订单业务
6. 使用 JWT 和 BCrypt 实现登录认证
7. 使用 Docker Compose 快速启动 MySQL
8. 使用种子数据自动初始化演示环境
9. 使用大模型完成商品问答和智能推荐
10. 使用结构化标记把 AI 文本转换成真实商品卡片

后续还可以继续扩展：

• 接入真实支付或模拟支付流程
• 增加管理员后台和商品管理
• 增加商品评价和售后模块
• 使用 Redis 缓存热门商品
• 使用 Elasticsearch 优化搜索
• 为 AI 导购增加商品筛选和价格排序工具调用
• 增加 AI 调用失败时的本地推荐降级策略
• 使用 HTTPS 和环境变量管理生产环境密钥

如果你也在做 HarmonyOS 课设，可以先把商品浏览、购物车、订单这条主链路跑通，再逐步增加登录、收藏和 AI 导购等功能，开发和排错会更容易。

项目素材和品牌名称仅用于学习演示。公开发布时建议替换为自有图片和品牌内容，不要把真实数据库密码、JWT 密钥或第三方 API Key 提交到公开仓库。