13 Flutter 专题：两周出一个调通工作台 API 的跨端 APP

按 08 总纲路径 C：Flutter 是卫星，P1 按需。本模块不是主线课程，不要在没有 APP 项目时提前学它——卫星语言最容易"学完就忘"，只有项目逼着你用，两周才能出活。

安装细节（下载链接、PATH 配置截图）属于 09 环境模块；这里只给"为跑通工作台 APP 所必需的最小步骤"。版本锁死 stable 3.47.6（随包 Dart 3.13.5），不选 master/beta。

2.1 装 Flutter SDK（stable 3.47.6）与国内镜像

1. 从官方归档页取 stable 3.47.6 的 zip，解压到不含空格、不含中文的路径，例如 D:\dev\flutter（不要放 C:\Program Files，权限会坑你）。完整归档清单见 https://docs.flutter.dev/install/archive。
2. 把 D:\dev\flutter\bin 加入用户 PATH（系统属性 → 环境变量 → 用户变量 Path → 新建）。
3. 设两个国内镜像环境变量（用户变量，否则 pub 极慢）：

# PowerShell（用户变量，永久生效；重开终端后生效）

[Environment]::SetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL","https://storage.flutter-io.cn","User")
[Environment]::SetEnvironmentVariable("PUB_HOSTED_URL","https://pub.flutter-io.cn","User")
# 重开 PowerShell 后验证
echo $env:FLUTTER_STORAGE_BASE_URL
flutter --version   # 应输出 Flutter 3.47.6 / Dart 3.13.5

2.2 flutter doctor 全绿的最小路径

打开新的 PowerShell，运行 flutter doctor -v。按下面三块逐个修：

目标状态：至少 [✓] Flutter 与 [✓] Windows 桌面开发 两项绿；Android 项可黄。跑 flutter doctor 看到这两项绿就进 §3。

2.3 VS2022 C++ 工作负载为什么必须装

Flutter 的 Windows 桌面端不是"套个 WebView"，而是用 C++ 写的桌面壳（win32 runner），构建时需要 MSVC 编译器和 CMake。缺了它，flutter build windows 会在链接阶段报错（见 §8 报错表第 6 条）。装 VS2022 Community 版即可，免费；只勾"使用 C++ 的桌面开发"一个工作负载，别全装（省磁盘）。

你不是零基础。这一节不教"什么是变量"，只列 Dart 和你已知语言的差异点，半小时扫完，够读懂后面的示例代码。

3.1 类型与变量

3.2 函数与类

// 箭头函数：单行函数体，对照 JS/Go 的闭包
int add(int a, int b) => a + b;

// 命名参数（花括号）：对照 Python 关键字参数；required 必传
String greet({required String name, String title = ''}) => '$title $name';

// 类：默认无 setter/setter 魔法，就是普通字段
class Task {
  final int id;
  String title;
  bool done;
  Task({required this.id, required this.title, this.done = false});
}

// mixin：Dart 的代码复用手段（对照 Java interface default / Go 无）
mixin Loggable {
  void log(String msg) => print('[LOG] $msg');
}
class Api with Loggable {
  void call() => log('called');   // 直接拿到 log 方法
}

3.3 异步：Future / async / await（重点，HTTP 全靠它）

Dart 单线程 + 事件循环，异步模型和 JS 几乎一模一样：Future<T> 就是 JS 的 Promise<T>，async/await 语义完全相同。和 Go 的 goroutine 不是一回事——Dart 没有抢占式线程，靠 await 挂起点让事件循环跑别的任务。

// 对照 JS：const r = await fetch(url).then(r => r.json())
Future<List<Task>> fetchTasks() async {
  final resp = await http.get(Uri.parse('/api/v1/tasks'));
  if (resp.statusCode == 200) {
    return parseTasks(resp.body);   // 同步函数直接返回，包在 Future 里
  }
  throw Exception('HTTP ${resp.statusCode}');
}

// 调用处照样 await；错误用 try/catch（对照 Java/JS）
try {
  final tasks = await fetchTasks();
} catch (e) {
  print('失败: $e');
}

3.4 空安全（你最容易踩的新东西）

3.5 集合

// List / Map / Set，都是字面量，对照 JS 数组与对象
final List<String> names = ['a', 'b'];
final Map<String, dynamic> json = {'code': 0, 'data': []};

// 展开与 if-in-list：Flutter UI 里天天用
final items = [
  'header',
  if (showExtra) 'extra',      // 集合 if
  ...names,                     // 展开
];
names.map((n) => n.toUpperCase()).toList();   // 链式，同 JS

扫完这节就够了：Dart 对你而言 = "带空安全的 TypeScript，跑在 Flutter 上"。剩下的语法细节在写 §5/§6 代码时遇到再查，不要现在去读 Dart 官方语言之旅。

Flutter 的世界观只有一句话：一切皆 Widget，UI 是 Widget 树，build 方法就是"用当前状态算出这一帧长什么样"。没有 XML 模板、没有虚拟 DOM diff 之外的魔法——你在 build 里 new 一堆 Widget，框架负责高效地画到屏幕上。

4.1 Stateless vs Stateful：什么时候用哪个

// 最小 StatefulWidget：计数器（你将来在 §5 用 Riverpod 替代 setState）
class Counter extends StatefulWidget {
  @override
  State<Counter> createState() => _CounterState();
}
class _CounterState extends State<Counter> {
  int _n = 0;
  @override
  Widget build(BuildContext context) {
    return Column(children: [
      Text('点击了 $_n 次'),
      ElevatedButton(
        onPressed: () => setState(() => _n++),   // setState 触发重建
        child: const Text('+1'),
      ),
    ]);
  }
}

4.2 布局：四个核心组件先记死

4.3 常用组件（本模块够用即可）

// 文字 / 按钮 / 输入框 / 卡片：一次认全
Text('你好', style: TextStyle(fontSize: 16, fontWeight: FontWeight.bold)),

ElevatedButton(onPressed: () {}, child: Text('登录')),
TextButton(onPressed: () {}, child: Text('取消')),

TextField(
  decoration: InputDecoration(labelText: '用户名', hintText: '请输入'),
  onChanged: (v) => username = v,
),

Card(
  elevation: 2,
  child: ListTile(
    title: Text('任务标题'),
    subtitle: Text('备注'),
    trailing: Checkbox(value: false, onChanged: (v) {}),
  ),
),

// 列表的标准写法：ListView.builder（懒加载，长列表专用）
ListView.builder(
  itemCount: tasks.length,
  itemBuilder: (ctx, i) => Card(child: ListTile(title: Text(tasks[i].title))),
)

4.4 路由：Navigator 与 go_router 的选型

4.5 主题：MaterialApp 一处管全局

MaterialApp(
  title: '工作台 APP',
  theme: ThemeData(
    colorSchemeSeed: const Color(0xFF0e7a6b),  // 主色，一套色板自动派生
    useMaterial3: true,
  ),
  home: const LoginPage(),   // 初始页；登录成功后换成 TaskPage
)

核心理解：Flutter 没有"找控件 id 改文字"这套（对照 Android View / jQuery）。你只写"在状态 S 下应该长什么样"，状态变了就重新调 build。这和 Vue3 的响应式思路一致，你迁移成本很低。

2026 年现状一句话：Provider 是入门最小包，Riverpod 是作者重写的现代化版本（编译安全、不依赖 BuildContext），Bloc 是事件驱动的重武器。本模块 APP 规模小，但要接 dio 异步流，直接上 Riverpod——一次写对，不用将来从 Provider 迁移。

5.1 选型规则（照此二选一）

5.2 第一步：pubspec.yaml 锁依赖

# flutter create workbench_app 之后，编辑 pubspec.yaml 的 dependencies：

dependencies:
  flutter:
    sdk: flutter
  flutter_riverpod: ^3.3.1      # 状态管理（2026-10 核验 latest 3.3.1）
  dio: ^5.11.1                  # HTTP 客户端（2026-10 核验 latest 5.11.1）

# 然后运行（会生成 pubspec.lock = 锁文件，唯一事实来源）
#   flutter pub get

版本纪律：上面写的是"兼容区间"（^），实际装进项目的版本由 pubspec.lock 锁定。换机器/换同事，flutter pub get 会按 lock 还原，不会飘。AI 若建议你升到 3.x 更高 minor，按 08 §7 规则 5 默认拒绝。

5.3 第二步：从计数器到任务列表的完整最小实现

下面 3 个文件拼起来就是一个"全局计数器 + 任务列表"的 Riverpod 最小骨架（HTTP 接工作台在 §6 补全）。

文件 1：lib/main.dart

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'tasks_page.dart';

void main() => runApp(const ProviderScope(child: MyApp()));

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: '工作台 APP',
      theme: ThemeData(colorSchemeSeed: const Color(0xFF0e7a6b), useMaterial3: true),
      home: const TasksPage(),
    );
  }
}

文件 2：lib/tasks_provider.dart（状态定义）

import 'package:flutter_riverpod/flutter_riverpod.dart';

// ① 一个最简单的状态：计数器（用 StateNotifierProvider，对照 Vue ref）
final counterProvider = StateProvider<int>((ref) => 0);

// ② 任务列表状态：状态类 + Notifier（ Riverpod 3.x 推荐写法）
class Task {
  final int id;
  final String title;
  bool done;
  Task({required this.id, required this.title, this.done = false});
}

class TasksNotifier extends Notifier<List<Task>> {
  @override
  List<Task> build() => [];   // 初始状态

  void add(String title) {
    state = [...state, Task(id: state.length + 1, title: title)];
  }

  void toggle(int id) {
    state = [
      for (final t in state)
        if (t.id == id) Task(id: t.id, title: t.title, done: !t.done) else t,
    ];
  }

  void remove(int id) {
    state = state.where((t) => t.id != id).toList();
  }
}

文件 3：lib/tasks_page.dart（UI 消费状态）

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'tasks_provider.dart';

class TasksPage extends ConsumerWidget {
  const TasksPage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final tasks = ref.watch(tasksProvider);   // 监听，状态变就重建
    final counter = ref.watch(counterProvider);

    return Scaffold(
      appBar: AppBar(title: Text('任务列表（已 $counter 次交互）')),
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          ref.read(tasksProvider.notifier).add('新任务');
          ref.read(counterProvider.notifier).state++;
        },
        child: const Icon(Icons.add),
      ),
      body: ListView.builder(
        itemCount: tasks.length,
        itemBuilder: (ctx, i) {
          final t = tasks[i];
          return Card(
            child: ListTile(
              title: Text(t.title,
                  style: TextStyle(
                      decoration: t.done ? TextDecoration.lineThrough : null)),
              leading: Checkbox(
                value: t.done,
                onChanged: (_) => ref.read(tasksProvider.notifier).toggle(t.id),
              ),
              trailing: IconButton(
                icon: const Icon(Icons.delete, color: Colors.red),
                onPressed: () => ref.read(tasksProvider.notifier).remove(t.id),
              ),
            ),
          );
        },
      ),
    );
  }
}

跑一下：flutter run -d windows，点 FAB 加任务、勾完成、点删除。这就是"计数器 → 任务列表"的完整闭环——§6 把 Notifier 里的本地数组换成真正的工作台 HTTP 请求即可。

这是本模块的真正验收点。严格按 workbench-contract 的端点写：不新增任何端点，请求/响应结构与 11 工作台后端完全一致。

6.1 为什么选 dio 而不是 http

6.2 端点对齐表（只准用这些）

统一响应信封：{"code":0,"data":{...},"msg":""}，错误时 code 非 0。所有受保护请求带 Authorization: Bearer <jwt>。

6.3 完整代码：lib/api.dart（dio 单例 + 拦截器 + 401 处理）

import 'package:dio/dio.dart';

// ★ 本机地址：Windows 桌面跑用 localhost；Android 模拟器跑必须用 10.0.2.2
// （Android 模拟器里 localhost 指它自己，不是你的电脑）
const String baseUrl = String.fromEnvironment(
  'BASE_URL',
  defaultValue: 'http://localhost:8080',
);

class Api {
  Api._() {
    dio = Dio(BaseOptions(
      baseUrl: baseUrl,
      connectTimeout: const Duration(seconds: 5),
      receiveTimeout: const Duration(seconds: 5),
    ));
    // 拦截器：每个请求自动塞 token；401 自动清 token 并跳登录
    dio.interceptors.add(InterceptorsWrapper(
      onRequest: (opt, handler) {
        if (_token != null) {
          opt.headers['Authorization'] = 'Bearer $_token';
        }
        handler.next(opt);
      },
      onError: (e, handler) {
        if (e.response?.statusCode == 401) {
          _token = null;
          // 这里发一个全局事件/改状态，让 UI 切回登录页（见 6.5）
        }
        handler.next(e);
      },
    ));
  }

  static final Api instance = Api._();
  late final Dio dio;
  String? _token;

  // ① 登录拿 JWT
  Future<void> login(String username, String password) async {
    final resp = await dio.post('/api/v1/auth/login', data: {
      'username': username,
      'password': password,
    });
    final body = resp.data as Map;
    if (body['code'] != 0) throw Exception(body['msg']);
    _token = body['data']['token'] as String;
  }

  // ② 任务模型（对齐工作台契约：id/title/note/done/created_at/updated_at）
  Task taskFromJson(Map<dynamic, dynamic> j) => Task(
        id: (j['id'] as num).toInt(),
        title: j['title'] as String,
        note: (j['note'] ?? '') as String,
        done: (j['done'] ?? false) as bool,
      );

  // ③ 列表
  Future<List<Task>> listTasks() async {
    final resp = await dio.get('/api/v1/tasks');
    final body = resp.data as Map;
    if (body['code'] != 0) throw Exception(body['msg']);
    return (body['data'] as List).map((e) => taskFromJson(e)).toList();
  }

  // ④ 新建
  Future<void> createTask(String title, String note) async {
    final resp = await dio.post('/api/v1/tasks',
        data: {'title': title, 'note': note, 'done': false});
    if ((resp.data as Map)['code'] != 0) throw Exception(resp.data['msg']);
  }

  // ⑤ 更新（标记完成同理，传完整 done）
  Future<void> updateTask(Task t) async {
    await dio.put('/api/v1/tasks/${t.id}',
        data: {'title': t.title, 'note': t.note, 'done': t.done});
  }

  // ⑥ 删除
  Future<void> deleteTask(int id) async {
    await dio.delete('/api/v1/tasks/$id');
  }
}

// 与 §5 同一份 Task 模型（实际项目里放 models/task.dart，这里合并展示）
class Task {
  final int id;
  String title;
  String note;
  bool done;
  Task({required this.id, required this.title, this.note = '', this.done = false});
}

6.4 把 §5 的 Notifier 换成"真接后端"

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'api.dart';

// 异步任务列表：用 FutureProvider 直接包 dio 调用
final tasksProvider = FutureProvider<List<Task>>((ref) async {
  return Api.instance.listTasks();   // GET /api/v1/tasks
});

// UI 里消费 AsyncValue：loading / error / data 三态一个都不漏
// ref.watch(tasksProvider).when(
//   loading: () => const CircularProgressIndicator(),
//   error: (e, _) => Text('加载失败: $e'),
//   data: (list) => ListView(...),
// );

6.5 登录页与 401 切回登录

• 登录页：两个 TextField（用户名/密码）+ 一个按钮，onPressed 调 Api.instance.login(u, p)；成功后 Navigator.pushReplacement 到任务页。
• 401 处理：6.3 拦截器里捕获 401 后清 token；再用 Riverpod 暴露一个 authStateProvider（enum: unknown / loggedIn），它变 loggedOut 时 MaterialApp 的 home 自动切回登录页——这就是"token 过期被踢回登录"。
• 错误处理纪律：网络层 throw，UI 层 when(error:…) 或 try/catch 弹 SnackBar 显示后端返回的 msg；不要吞异常（对照 08 §6.3 调试纪律）。

6.6 运行时怎么连到本机工作台

# Windows 桌面直接跑（默认 BASE_URL=http://localhost:8080，无需改动）

flutter run -d windows

# Android 模拟器跑：必须用 10.0.2.2 代替 localhost
flutter run -d emulator-5554 --dart-define=BASE_URL=http://10.0.2.2:8080

对照 12 Vue3：你在 Vue3 里用 axios + Pinia 写过的那套（拦截器塞 token、401 跳登录、统一信封解包），这里 dio + Riverpod 是一一对应的，概念平移即可，没有新范式。

开发用 flutter run 热重载；交付物用下面两条命令。iOS 一句话：需要 Mac + Xcode，本模块不展开。

7.1 Windows 桌面：出 exe

flutter build windows --release
# 产物在：build\windows\x64\release\
# 里面 workbench_app.exe 连同 data\ 目录一起拷贝即可运行（绿色版）

前提：§2.2 的 VS2022"使用 C++ 的桌面开发"工作负载已装。无需签名就能自己用/内网分发；要上微软商店再另做 MSIX。

7.2 Android：出 APK（gradle + 签名简述）

1. 首次打 release 包前要签名：用 JDK 自带 keytool 生成 keystore（一个命令，密码自己记牢，丢了就永远没法更新这个 APP）：

keytool -genkey -v -keystore workbench.jks -keyalg RSA -keysize 2048 -validity 10000 -alias workbench

2. 在 android/ 下建 key.properties（不要提交进 git），再在 android/app/build.gradle.kts 的 signingConfigs 里读它——这是标准做法，具体 gradle 语法在你第一个真实打包任务时让 AI 按 Flutter 官方"Android 发布"文档生成，本模块不抄长配置。
3. 构建：

flutter build apk --release
# 产物：build\app\outputs\flutter-apk\app-release.apk，拷到手机安装即可

7.3 iOS（一句话）

iOS 构建必须有一台 Mac（Xcode 是苹果独占），且需要 Apple Developer 账号签名才能装到真机。你当前是 Windows 机器，本模块不做 iOS；将来真要发 App Store 再借/买 Mac，按 Xcode Archive 流程走。

卡住了先查这张表。报错原文、原因、解决一一对应；还不行就按 08 §6.3 把报错原文喂给 AI。

本模块只认一个验收：APP 真的登录了你的工作台，并能操作任务列表。复制下面清单逐条打勾。

全部打勾 = 本模块结业：你交付了一个真正接工作台的跨端 APP，而不是一个 demo。把这套 dio 拦截器 + Riverpod 任务列表骨架 fork 进你的 assets/scaffolds/（见 08 §5），下一个 APP 项目直接复用——这就是四件套里"架子"的卫星版。

本模块所有版本号与端点均来自 versions.md 与 workbench-contract；Dart 包版本由本模块在 pub.dev 现场核验。

来源表

（编者整理：本模块的"两周路线、选型规则、报错表、验收清单"为基于 07 报告与 08 总纲路径 C 的执行化设计，无外部独立来源。）