Flutter | 商城项目完整实战

一、项目是什么

flutter_shop 是一个 Flutter 电商 Demo，实现了移动端商城常见的核心体验：

底部四 Tab：首页、分类、购物车、我的
首页信息流：轮播、分类入口、特惠推荐、爆款、猜你喜欢
下拉刷新 + 滚动加载更多
登录 / 退出登录：表单校验、Token 持久化、请求自动鉴权

用 StatefulWidget + 分层目录 把网络、模型、页面拆开，适合作为 Flutter 入门到进阶的练手工程。

二、技术栈

类别	选型	作用
框架	Flutter 3.x	UI 与跨端运行
网络	`dio` ^5.9	HTTP 请求、拦截器
本地存储	`shared_preferences` ^2.5	Token、记住密码
UI 组件	`tdesign_flutter` ^0.2.7	图标、设计规范
轮播	`carousel_slider` ^5.1	首页 Banner

三、目录结构与分层思路

复制代码

lib/
├── main.dart                 # 入口，runApp(getRootWidget())
├── routes/index.dart         # 命名路由：/、/login
├── constants/index.dart      # BASE_URL、接口路径、成功码
├── api/                      # 按业务拆分的 API 函数
│   ├── home.dart
│   └── login.dart
├── viewmodels/               # 数据模型（fromJson）
│   ├── home.dart
│   └── login.dart
├── utils/                    # 通用能力
│   ├── DioRequest.dart       # Dio 单例 + 拦截器
│   ├── LoginStorage.dart     # 登录态本地存储
│   ├── LoginValidator.dart   # 表单校验
│   └── ToastUtils.dart       # SnackBar 提示
├── pages/                    # 页面
│   ├── Main/index.dart       # 底部导航 + IndexedStack
│   ├── Home/home.dart
│   ├── Login/index.dart
│   └── User/user.dart
└── components/Home/          # 首页可复用区块组件
    ├── ShopSlider.dart
    ├── ShopCategory.dart
    ├── ShopSuggestion.dart
    ├── ShopHot.dart
    └── ShopMoreList.dart

分层原则（实现思路）：

constants：环境配置与接口路径集中管理，改域名只改一处。
utils/DioRequest ：所有请求走同一套超时、状态码、业务 code 判断。
api + viewmodels ：页面不直接拼 URL，只调用 getBannerListAPI() 等语义化方法，JSON 解析集中在 fromJson。
components ：首页大块 UI 拆成独立 Widget，父页面只负责拉数据和 setState。
pages：管生命周期、路由跳转、用户交互。

这是典型的 「常量 → 网络层 → API → 模型 → 页面/组件」 流水线，后续加购物车、订单接口时，只需新增 api/order.dart 和对应 model，不必动 Dio 封装。

四、核心功能实现思路

4.1 应用入口与路由

main.dart 极其精简，真正的根组件在 routes/index.dart：

dart 复制代码

MaterialApp(
  initialRoute: "/",
  routes: {
    "/": (context) => MainPage(),
    "/login": (context) => LoginPage(),
  },
);

主框架 /：MainPage 用 IndexedStack 保留四个 Tab 的状态（切换 Tab 不销毁子页面）。
登录页 /login：从「我的」Navigator.pushNamed 进入，登录成功 pop(context, true) 带回结果刷新用户信息。

命名路由适合页面不多的 Demo；页面增多后可升级为 onGenerateRoute 或 go_router。

4.2 网络层：Dio 单例与统一响应

后端约定响应格式：

json 复制代码

{ "code": "1", "msg": "...", "result": { ... } }

DioRequest 的核心设计：

构造时 配置 baseUrl、超时时间。
请求拦截器 ：从 LoginStorage 读取 token，自动设置 Authorization: Bearer <token>。
_handleResponse ：code == '1' 时返回 result，否则 throw Exception(msg)，页面用 try/catch + Toast 提示用户。

对外暴露 get / post，业务 API 例如：

dart 复制代码

Future<LoginResult> loginAPI({required String account, required String password}) async {
  final response = await dioRequest.post(
    HttpConstants.LOGIN,
    data: {'account': account, 'password': password},
  );
  return LoginResult.fromJson(response as Map<String, dynamic>);
}

学习点 ：拦截器里做鉴权，比在每个 API 里手写 Header 更可维护；统一解包 result 能减少页面层的重复判断。

4.3 首页：CustomScrollView + Sliver 组合

首页 HomeView 使用 CustomScrollView + 多个 SliverToBoxAdapter / ShopMoreList（内部 SliverGrid），好处是：

整块页面 一个滚动轴，体验接近原生商城 App；
「猜你喜欢」用 双列网格 ，通过 SliverChildBuilderDelegate 按需构建子项。

数据加载策略：

首次进入 ：Future.microtask 触发 RefreshIndicator.show()，走 _onRefresh 并行拉 Banner、分类、特惠、爆款、推荐。
加载更多 ：ScrollController 监听距底部 50px，递增 limit = page * 8 请求推荐列表（与「我的」页同款逻辑）。

学习点 ：RefreshIndicator 必须包在可滚动且可 overscroll 的组件外；SliverMainAxisGroup + pinned 标题可实现「推荐标题吸顶」（用户页已用）。

4.4 登录：表单、接口、持久化

流程：

复制代码

用户输入 → LoginValidator 校验 → loginAPI POST /login
→ saveUserInfo(token/昵称/头像) → 可选 rememberPassword → pop 回我的页

校验：手机号 ^1[3-9]\d{9}$，密码 6--20 位。
记住密码 ：与登录态分离存储；退出登录只 clearUserInfo()，不清账号密码，符合常见产品逻辑。
测试账号 ：13200000001 / 123456（需 11 位手机号才通过校验）。

学习点 ：异步登录要注意 mounted 再 setState / Navigator.pop；提交中禁用按钮并显示 CircularProgressIndicator 防止重复提交。

4.5 我的页：登录态展示与退出

initState 调用 _loadUserInfo()，根据 token 是否存在决定展示「立即登录」或昵称 + 网络头像。
登录返回 true 时重新 _loadUserInfo()。
退出：AlertDialog 二次确认 → LoginStorage.clearUserInfo() → setState 恢复未登录 UI。

学习点 ：showDialog 返回 Future<bool?>，只有用户点确定才执行副作用；这是移动端 destructive action 的标配交互。

五、数据流示意

#mermaid-svg-dC33UTaEz2CXYalZ{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-dC33UTaEz2CXYalZ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-dC33UTaEz2CXYalZ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-dC33UTaEz2CXYalZ .error-icon{fill:#552222;}#mermaid-svg-dC33UTaEz2CXYalZ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-dC33UTaEz2CXYalZ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-dC33UTaEz2CXYalZ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-dC33UTaEz2CXYalZ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-dC33UTaEz2CXYalZ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-dC33UTaEz2CXYalZ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-dC33UTaEz2CXYalZ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-dC33UTaEz2CXYalZ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-dC33UTaEz2CXYalZ .marker.cross{stroke:#333333;}#mermaid-svg-dC33UTaEz2CXYalZ svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-dC33UTaEz2CXYalZ p{margin:0;}#mermaid-svg-dC33UTaEz2CXYalZ .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-dC33UTaEz2CXYalZ .cluster-label text{fill:#333;}#mermaid-svg-dC33UTaEz2CXYalZ .cluster-label span{color:#333;}#mermaid-svg-dC33UTaEz2CXYalZ .cluster-label span p{background-color:transparent;}#mermaid-svg-dC33UTaEz2CXYalZ .label text,#mermaid-svg-dC33UTaEz2CXYalZ span{fill:#333;color:#333;}#mermaid-svg-dC33UTaEz2CXYalZ .node rect,#mermaid-svg-dC33UTaEz2CXYalZ .node circle,#mermaid-svg-dC33UTaEz2CXYalZ .node ellipse,#mermaid-svg-dC33UTaEz2CXYalZ .node polygon,#mermaid-svg-dC33UTaEz2CXYalZ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-dC33UTaEz2CXYalZ .rough-node .label text,#mermaid-svg-dC33UTaEz2CXYalZ .node .label text,#mermaid-svg-dC33UTaEz2CXYalZ .image-shape .label,#mermaid-svg-dC33UTaEz2CXYalZ .icon-shape .label{text-anchor:middle;}#mermaid-svg-dC33UTaEz2CXYalZ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-dC33UTaEz2CXYalZ .rough-node .label,#mermaid-svg-dC33UTaEz2CXYalZ .node .label,#mermaid-svg-dC33UTaEz2CXYalZ .image-shape .label,#mermaid-svg-dC33UTaEz2CXYalZ .icon-shape .label{text-align:center;}#mermaid-svg-dC33UTaEz2CXYalZ .node.clickable{cursor:pointer;}#mermaid-svg-dC33UTaEz2CXYalZ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-dC33UTaEz2CXYalZ .arrowheadPath{fill:#333333;}#mermaid-svg-dC33UTaEz2CXYalZ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-dC33UTaEz2CXYalZ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-dC33UTaEz2CXYalZ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-dC33UTaEz2CXYalZ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-dC33UTaEz2CXYalZ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-dC33UTaEz2CXYalZ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-dC33UTaEz2CXYalZ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-dC33UTaEz2CXYalZ .cluster text{fill:#333;}#mermaid-svg-dC33UTaEz2CXYalZ .cluster span{color:#333;}#mermaid-svg-dC33UTaEz2CXYalZ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-dC33UTaEz2CXYalZ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-dC33UTaEz2CXYalZ rect.text{fill:none;stroke-width:0;}#mermaid-svg-dC33UTaEz2CXYalZ .icon-shape,#mermaid-svg-dC33UTaEz2CXYalZ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-dC33UTaEz2CXYalZ .icon-shape p,#mermaid-svg-dC33UTaEz2CXYalZ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-dC33UTaEz2CXYalZ .icon-shape .label rect,#mermaid-svg-dC33UTaEz2CXYalZ .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-dC33UTaEz2CXYalZ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-dC33UTaEz2CXYalZ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-dC33UTaEz2CXYalZ :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} Remote
Core
API
UI
HomeView
LoginPage
UserView
home.dart
login.dart
DioRequest
LoginStorage
meikou-api.itheima.net

六、项目亮点

亮点

结构清晰，新人能按目录快速定位代码。
网络层与业务解耦，接口常量、成功码统一。
首页 Sliver 布局 + 组件化，贴近真实商城列表体验。
登录闭环完整：登录 → Token 注入 → 展示用户信息 → 确认退出。

页面效果

七、学习总结

通过 flutter_shop，可以系统练到：

Flutter 布局 ：Scaffold、BottomNavigationBar、IndexedStack、CustomScrollView、Sliver 网格。
异步编程 ：async/await、Future.microtask、mounted 守卫。
网络实战：Dio 配置、拦截器、RESTful POST 登录、Bearer Token。
本地持久化：SharedPreferences 存 Token 与「记住密码」。
表单与交互 ：Form + validator、showDialog 确认、SnackBar 反馈。
工程化习惯：分层、常量、单例、组件拆分。

八、本地运行

bash 复制代码

cd project/flutter_shop
flutter pub get
flutter run