Flutter网络与数据持久化

What — 是什么

Flutter 网络与数据持久化是移动端应用的核心基础设施层：网络层负责与后端 API 通信、文件传输和实时消息，持久化层负责本地数据存储、缓存和安全保存敏感信息。两者协同构成了离线优先架构的基础。

核心概念：

• HTTP 网络请求：通过 http 包或 dio 库发起 RESTful API 调用，获取/提交服务端数据
• dio 封装：基于 Interceptor 的请求/响应拦截，统一处理 Token、错误、日志、重试
• 文件传输：multipart/form-data 上传、流式下载、进度监听、断点续传
• WebSocket：全双工实时通信，适用于聊天、推送、协作等场景
• JSON 序列化：json_serializable + build_runner 自动生成序列化代码，替代手写 fromJson/toJson
• SharedPreferences：轻量键值对存储，适合配置项、偏好设置
• SQLite：结构化本地数据库，sqflite 原生操作或 drift 类型安全 ORM
• 安全存储：flutter_secure_storage 利用 Keychain/Keystore 加密存储敏感数据
• 数据缓存：内存缓存 + 磁盘缓存的分层策略，减少网络请求
• 网络检测：connectivity_plus 感知网络状态变化，驱动离线/在线切换
• 离线优先：本地优先读写，网络恢复后同步，保证弱网/断网可用

整体架构：

┌─────────────────────────────────────────────────────────┐
│                    Flutter Application                   │
├─────────────────────────────────────────────────────────┤
│                     UI / State Layer                     │
│            (Provider / Riverpod / Bloc)                  │
├────────────────────┬────────────────────────────────────┤
│    Network Layer   │         Persistence Layer           │
│  ┌──────────────┐  │  ┌───────────┬──────────┬────────┐ │
│  │  dio 封装     │  │  │ Shared    │ SQLite   │ Secure │ │
│  │  Interceptor │  │  │ Prefs     │ (drift)  │ Storage│ │
│  │  Transformer │  │  │ (KV)      │ (RDBMS)  │(Keychain)│
│  ├──────────────┤  │  ├───────────┼──────────┼────────┤ │
│  │  WebSocket   │  │  │  文件系统  │  数据缓存  │ 加密   │ │
│  │  (实时通信)   │  │  │(path_prov)│(内存+磁盘)│ 存储   │ │
│  ├──────────────┤  │  └───────────┴──────────┴────────┘ │
│  │  文件传输     │  │                                    │
│  │ (上传/下载)   │  │                                    │
│  └──────┬───────┘  └────────────────────────────────────┤
│         │                                               │
├─────────┴───────────────────────────────────────────────┤
│              Connectivity (connectivity_plus)            │
│                   网络状态检测                             │
├─────────────────────────────────────────────────────────┤
│                Offline-First Sync Engine                 │
│              (本地优先 · 增量同步 · 冲突解决)               │
└─────────────────────────────────────────────────────────┘

数据流全景：

用户操作
  │
  ▼
State Layer (Riverpod/Bloc)
  │
  ├──── 读操作 ────► 缓存层 ──── 命中? ──► 返回缓存数据
  │                              │ 未命中
  │                              ▼
  │                         网络请求 (dio)
  │                              │
  │                              ▼
  │                         写入缓存 + 返回数据
  │
  ├──── 写操作 ────► 本地持久化 (SQLite/SharedPrefs)
  │                     │
  │                     ▼
  │                同步队列 (离线时入队)
  │                     │
  │                     ▼ (网络恢复)
  │                网络提交 (dio POST/PUT)
  │
  └──── 实时 ────► WebSocket (双向通信)

Why — 为什么

适用场景：

• 移动端 App 必须与后端 API 交互获取数据
• 弱网/断网环境下需要本地缓存和离线能力
• 用户登录态、Token 等敏感信息需要安全存储
• 聊天/推送/协作等场景需要实时通信
• 大文件上传下载需要进度监听和断点续传
• 复杂数据模型需要类型安全的序列化方案

网络库对比：

持久化方案对比：

优缺点：

• ✅ dio 封装：
  • 拦截器机制灵活强大，可统一处理认证、日志、错误
  • 内置取消、进度、FormData，减少样板代码
  • 社区活跃，插件生态丰富
• ❌ dio 封装：
  • 拦截器链调试复杂，执行顺序需仔细控制
  • 过度封装可能隐藏问题
  • 与某些原生平台特性（如 NSAppTransportSecurity）需额外配置
• ✅ SQLite (drift)：
  • 类型安全的 SQL 构建，编译期检查
  • 响应式查询（watch），数据变化自动通知 UI
  • 迁移系统完善
• ❌ SQLite (drift)：
  • 代码生成增加构建时间
  • 学习曲线比 sqflite 陡峭
  • 复杂联表查询仍需手写 SQL

How — 怎么用

快速上手

依赖配置（pubspec.yaml）：

dependencies:
  # 网络请求
  http: ^1.2.0              # 轻量 HTTP 客户端
  dio: ^5.4.0               # 强大的 HTTP 客户端

  # WebSocket
  web_socket_channel: ^3.0.0

  # JSON 序列化
  json_annotation: ^4.9.0

  # 持久化
  shared_preferences: ^2.2.0
  sqflite: ^2.3.0           # SQLite 原生操作
  drift: ^2.15.0            # SQLite ORM
  sqlite3_flutter_libs: ^0.5.0  # drift 依赖
  path_provider: ^2.1.0     # 路径获取
  flutter_secure_storage: ^9.2.0  # 安全存储

  # 网络检测
  connectivity_plus: ^6.0.0

dev_dependencies:
  build_runner: ^2.4.0      # 代码生成工具
  json_serializable: ^6.8.0  # JSON 序列化生成
  drift_dev: ^2.15.0        # drift 代码生成

一、HTTP 网络请求

1.1 http 包基础用法

import 'package:http/http.dart' as http;
import 'dart:convert';

/// http 包 — 最简单的网络请求方式
class HttpExample {
  /// GET 请求
  static Future<void> fetchUsers() async {
    try {
      final uri = Uri.parse('https://api.example.com/users');
      final response = await http.get(
        uri,
        headers: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer token123',
        },
      );

      if (response.statusCode == 200) {
        // 解码 JSON 响应体
        final List<dynamic> data = json.decode(response.body);
        print('用户数量: ${data.length}');
      } else {
        print('请求失败: ${response.statusCode}');
      }
    } catch (e) {
      print('网络异常: $e');
    }
  }

  /// POST 请求
  static Future<void> createUser(Map<String, dynamic> user) async {
    try {
      final uri = Uri.parse('https://api.example.com/users');
      final response = await http.post(
        uri,
        headers: {'Content-Type': 'application/json'},
        body: json.encode(user), // 编码请求体
      );

      if (response.statusCode == 201) {
        print('创建成功: ${response.body}');
      }
    } catch (e) {
      print('创建失败: $e');
    }
  }

  /// PUT 请求 — 全量更新
  static Future<void> updateUser(int id, Map<String, dynamic> user) async {
    final uri = Uri.parse('https://api.example.com/users/$id');
    final response = await http.put(
      uri,
      headers: {'Content-Type': 'application/json'},
      body: json.encode(user),
    );
    // 处理响应...
  }

  /// PATCH 请求 — 部分更新
  static Future<void> patchUser(int id, Map<String, dynamic> fields) async {
    final uri = Uri.parse('https://api.example.com/users/$id');
    final response = await http.patch(
      uri,
      headers: {'Content-Type': 'application/json'},
      body: json.encode(fields),
    );
    // 处理响应...
  }

  /// DELETE 请求
  static Future<void> deleteUser(int id) async {
    final uri = Uri.parse('https://api.example.com/users/$id');
    final response = await http.delete(uri);
    if (response.statusCode == 204) {
      print('删除成功');
    }
  }

  /// 带查询参数的 GET 请求
  static Future<void> searchUsers({
    required String keyword,
    int page = 1,
    int pageSize = 20,
  }) async {
    final uri = Uri.https('api.example.com', '/users', {
      'keyword': keyword,
      'page': page.toString(),
      'pageSize': pageSize.toString(),
    });
    final response = await http.get(uri);
    // 处理响应...
  }

  /// 带超时的请求
  static Future<void> fetchWithTimeout() async {
    try {
      final uri = Uri.parse('https://api.example.com/slow-api');
      final response = await http.get(uri).timeout(
        const Duration(seconds: 10), // 10 秒超时
        onTimeout: () => throw Exception('请求超时'),
      );
    } catch (e) {
      print('超时或网络错误: $e');
    }
  }
}

1.2 dio 库基础用法

import 'package:dio/dio.dart';

/// dio 基础用法 — 比 http 包功能强大得多
class DioBasicExample {
  late final Dio _dio;

  DioBasicExample() {
    // 创建 Dio 实例并配置 BaseOptions
    _dio = Dio(BaseOptions(
      baseUrl: 'https://api.example.com',  // 基础 URL
      connectTimeout: const Duration(seconds: 15), // 连接超时
      receiveTimeout: const Duration(seconds: 15), // 接收超时
      sendTimeout: const Duration(seconds: 15),    // 发送超时
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
      },
      responseType: ResponseType.json,   // 自动 JSON 解码
      validateStatus: (status) => status != null && status < 500, // 自定义状态码校验
    ));
  }

  /// GET 请求
  Future<Response> getUsers({int page = 1}) async {
    return await _dio.get(
      '/users',
      queryParameters: {'page': page, 'size': 20},
    );
  }

  /// POST 请求
  Future<Response> createUser(Map<String, dynamic> data) async {
    return await _dio.post('/users', data: data);
  }

  /// PUT 请求
  Future<Response> updateUser(int id, Map<String, dynamic> data) async {
    return await _dio.put('/users/$id', data: data);
  }

  /// PATCH 请求
  Future<Response> patchUser(int id, Map<String, dynamic> data) async {
    return await _dio.patch('/users/$id', data: data);
  }

  /// DELETE 请求
  Future<Response> deleteUser(int id) async {
    return await _dio.delete('/users/$id');
  }

  /// 并发请求 — 多个接口同时请求
  Future<void> fetchDashboard() async {
    final results = await Future.wait([
      _dio.get('/dashboard/stats'),
      _dio.get('/dashboard/notifications'),
      _dio.get('/dashboard/activities'),
    ]);

    final stats = results[0].data;
    final notifications = results[1].data;
    final activities = results[2].data;
    print('仪表盘数据加载完成');
  }
}

二、dio 封装实战

2.1 BaseOptions 配置

import 'package:dio/dio.dart';
import 'package:flutter/foundation.dart';

/// 全局 Dio 配置 — 单例模式
class DioConfig {
  // 私有构造
  DioConfig._();

  static Dio? _instance;

  /// 获取 Dio 单例
  static Dio get dio {
    _instance ??= _createDio();
    return _instance!;
  }

  /// 创建配置好的 Dio 实例
  static Dio _createDio() {
    final dio = Dio(
      BaseOptions(
        baseUrl: const String.fromEnvironment(
          'API_BASE_URL',
          defaultValue: 'https://api.example.com',
        ),
        connectTimeout: const Duration(seconds: 15),
        receiveTimeout: const Duration(seconds: 15),
        sendTimeout: const Duration(seconds: 15),
        headers: {
          'Content-Type': 'application/json',
          'Accept': 'application/json',
          'X-Platform': defaultTargetPlatform.name, // 平台标识
          'X-Version': '2.0.0',                     // App 版本
        },
        responseType: ResponseType.json,
        // 不抛出非 2xx 异常，统一在拦截器处理
        validateStatus: (status) => status != null && status < 500,
      ),
    );

    // 添加拦截器（执行顺序：按添加顺序 onRequest，按逆序 onResponse/onError）
    dio.interceptors.addAll([
      LogInterceptor(),           // 日志拦截器（最外层）
      AuthInterceptor(),          // 认证拦截器
      ErrorInterceptor(),         // 错误处理拦截器
      RetryInterceptor(dio: dio), // 重试拦截器（最内层）
    ]);

    return dio;
  }

  /// 重置实例（用于切换环境/登出后重建）
  static void reset() {
    _instance = null;
  }
}

2.2 请求拦截器（Token 自动刷新 + 统一错误处理 + 日志拦截）

import 'package:dio/dio.dart';
import 'dart:async';

/// ==================== 认证拦截器 ====================
/// 自动附加 Token + Token 过期自动刷新
class AuthInterceptor extends Interceptor {
  // Token 存储键
  static const _accessTokenKey = 'access_token';
  static const _refreshTokenKey = 'refresh_token';

  // 刷新锁 — 防止并发刷新
  bool _isRefreshing = false;
  final List<Completer<void>> _refreshQueue = [];

  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) async {
    // 不需要 Token 的接口白名单
    final whitelist = ['/auth/login', '/auth/register', '/auth/refresh'];
    if (whitelist.contains(options.path)) {
      return handler.next(options);
    }

    // 从安全存储读取 Token
    final token = await _getAccessToken();
    if (token != null) {
      options.headers['Authorization'] = 'Bearer $token';
    }
    handler.next(options);
  }

  @override
  void onError(DioException err, ErrorInterceptorHandler handler) async {
    // 401 表示 Token 过期，尝试刷新
    if (err.response?.statusCode == 401) {
      // 白名单接口 401 不刷新
      final whitelist = ['/auth/login', '/auth/register'];
      if (whitelist.contains(err.requestOptions.path)) {
        return handler.next(err);
      }

      try {
        // 等待刷新完成
        await _refreshToken(err.requestOptions);
        // 用新 Token 重试原请求
        final newToken = await _getAccessToken();
        err.requestOptions.headers['Authorization'] = 'Bearer $newToken';
        final response = await Dio().fetch(err.requestOptions);
        return handler.resolve(response);
      } catch (refreshError) {
        // 刷新失败，跳转登录页
        _handleRefreshFailed();
        return handler.next(err);
      }
    }
    handler.next(err);
  }

  /// 刷新 Token — 加锁防止并发
  Future<void> _refreshToken(RequestOptions requestOptions) async {
    if (_isRefreshing) {
      // 已在刷新中，排队等待
      final completer = Completer<void>();
      _refreshQueue.add(completer);
      return completer.future;
    }

    _isRefreshing = true;
    try {
      final refreshToken = await _getRefreshToken();
      if (refreshToken == null) throw Exception('无 RefreshToken');

      // 创建新 Dio 实例发刷新请求（避免死循环拦截器）
      final refreshDio = Dio(BaseOptions(
        baseUrl: requestOptions.baseUrl,
      ));
      final response = await refreshDio.post('/auth/refresh', data: {
        'refreshToken': refreshToken,
      });

      // 保存新 Token
      final newAccessToken = response.data['accessToken'];
      final newRefreshToken = response.data['refreshToken'];
      await _saveTokens(newAccessToken, newRefreshToken);

      // 通知排队等待的请求
      for (final completer in _refreshQueue) {
        completer.complete();
      }
      _refreshQueue.clear();
    } catch (e) {
      // 刷新失败，通知所有等待的请求
      for (final completer in _refreshQueue) {
        completer.completeError(e);
      }
      _refreshQueue.clear();
      rethrow;
    } finally {
      _isRefreshing = false;
    }
  }

  Future<String?> _getAccessToken() async {
    // 实际项目中从 flutter_secure_storage 读取
    return null; // placeholder
  }

  Future<String?> _getRefreshToken() async {
    return null; // placeholder
  }

  Future<void> _saveTokens(String access, String refresh) async {
    // 实际项目中保存到 flutter_secure_storage
  }

  void _handleRefreshFailed() {
    // 清除 Token，跳转登录页
    // 实际项目中通过 EventBus 或 NavigationService 实现
  }
}

/// ==================== 错误处理拦截器 ====================
/// 统一错误分类 + 业务错误码处理
class ErrorInterceptor extends Interceptor {
  @override
  void onError(DioException err, ErrorInterceptorHandler handler) {
    // 将 DioException 转换为自定义 AppException
    final appError = _convertToAppError(err);

    // 根据业务错误码特殊处理
    if (err.response?.data is Map) {
      final data = err.response!.data as Map;
      final code = data['code'];

      switch (code) {
        case 'USER_BANNED':
          // 用户被封禁，强制退出
          _forceLogout();
          break;
        case 'VERSION_OUTDATED':
          // 版本过旧，提示升级
          _showUpgradeDialog();
          break;
        case 'MAINTENANCE':
          // 服务维护中
          _showMaintenancePage(data['message']);
          break;
      }
    }

    handler.next(appError);
  }

  /// 将 DioException 转为 AppException
  AppException _convertToAppError(DioException err) {
    switch (err.type) {
      case DioExceptionType.connectionTimeout:
      case DioExceptionType.sendTimeout:
      case DioExceptionType.receiveTimeout:
        return AppException(
          code: 'TIMEOUT',
          message: '网络连接超时，请检查网络后重试',
          originalError: err,
        );
      case DioExceptionType.connectionError:
        return AppException(
          code: 'NETWORK_ERROR',
          message: '网络连接失败，请检查网络设置',
          originalError: err,
        );
      case DioExceptionType.badResponse:
        return _handleBadResponse(err.response);
      case DioExceptionType.cancel:
        return AppException(
          code: 'CANCELLED',
          message: '请求已取消',
          originalError: err,
        );
      default:
        return AppException(
          code: 'UNKNOWN',
          message: '未知错误: ${err.message}',
          originalError: err,
        );
    }
  }

  AppException _handleBadResponse(Response? response) {
    final statusCode = response?.statusCode;
    final data = response?.data;

    switch (statusCode) {
      case 400:
        return AppException(
          code: 'BAD_REQUEST',
          message: data?['message'] ?? '请求参数错误',
        );
      case 401:
        return AppException(
          code: 'UNAUTHORIZED',
          message: '登录已过期，请重新登录',
        );
      case 403:
        return AppException(
          code: 'FORBIDDEN',
          message: '没有操作权限',
        );
      case 404:
        return AppException(
          code: 'NOT_FOUND',
          message: '请求的资源不存在',
        );
      case 429:
        return AppException(
          code: 'TOO_MANY_REQUESTS',
          message: '请求过于频繁，请稍后重试',
        );
      case 500:
        return AppException(
          code: 'SERVER_ERROR',
          message: '服务器内部错误',
        );
      case 502:
      case 503:
        return AppException(
          code: 'SERVICE_UNAVAILABLE',
          message: '服务暂时不可用，请稍后重试',
        );
      default:
        return AppException(
          code: 'HTTP_$statusCode',
          message: data?['message'] ?? '请求失败 ($statusCode)',
        );
    }
  }

  void _forceLogout() { /* 跳转登录 */ }
  void _showUpgradeDialog() { /* 显示升级弹窗 */ }
  void _showMaintenancePage(String? message) { /* 维护页面 */ }
}

/// 自定义异常类
class AppException extends DioException {
  final String code;
  final String message;
  final DioException? originalError;

  AppException({
    required this.code,
    required this.message,
    this.originalError,
  }) : super(
    requestOptions: originalError?.requestOptions ?? RequestOptions(),
    error: message,
    response: originalError?.response,
  );

  @override
  String toString() => 'AppException($code): $message';
}

/// ==================== 日志拦截器 ====================
/// 格式化日志输出（开发环境）
class PrettyLogInterceptor extends Interceptor {
  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
    if (kDebugMode) {
      print('┌─────────────────── REQUEST ───────────────────');
      print('│ ${options.method} ${options.uri}');
      print('│ Headers: ${_formatMap(options.headers)}');
      if (options.data != null) {
        print('│ Body: ${_truncate(options.data.toString(), 500)}');
      }
      if (options.queryParameters.isNotEmpty) {
        print('│ Query: ${_formatMap(options.queryParameters)}');
      }
      print('└───────────────────────────────────────────────');
    }
    handler.next(options);
  }

  @override
  void onResponse(Response response, ResponseInterceptorHandler handler) {
    if (kDebugMode) {
      print('┌─────────────────── RESPONSE ──────────────────');
      print('│ ${response.statusCode} ${response.requestOptions.uri}');
      print('│ Duration: ${response.requestOptions.extra['startTime']}ms');
      print('│ Data: ${_truncate(response.data.toString(), 500)}');
      print('└───────────────────────────────────────────────');
    }
    handler.next(response);
  }

  @override
  void onError(DioException err, ErrorInterceptorHandler handler) {
    if (kDebugMode) {
      print('┌─────────────────── ERROR ─────────────────────');
      print('│ ${err.type}: ${err.message}');
      print('│ ${err.requestOptions.method} ${err.requestOptions.uri}');
      if (err.response != null) {
        print('│ Status: ${err.response?.statusCode}');
        print('│ Data: ${_truncate(err.response?.data.toString() ?? '', 300)}');
      }
      print('└───────────────────────────────────────────────');
    }
    handler.next(err);
  }

  String _formatMap(Map map) {
    return map.entries.map((e) => '${e.key}: ${e.value}').join(', ');
  }

  String _truncate(String text, int maxLen) {
    return text.length > maxLen ? '${text.substring(0, maxLen)}...' : text;
  }
}

2.3 重试拦截器

/// 重试拦截器 — 网络异常自动重试
class RetryInterceptor extends Interceptor {
  final Dio dio;
  final int maxRetries;        // 最大重试次数
  final Duration retryDelay;   // 重试间隔
  final Set<String> retryableMethods; // 可重试的 HTTP 方法

  RetryInterceptor({
    required this.dio,
    this.maxRetries = 3,
    this.retryDelay = const Duration(seconds: 1),
    this.retryableMethods = const {'GET', 'PUT', 'DELETE'},
  });

  @override
  void onError(DioException err, ErrorInterceptorHandler handler) async {
    // 仅对可重试方法且符合重试条件的错误重试
    if (!_shouldRetry(err)) {
      return handler.next(err);
    }

    // 获取已重试次数
    final retryCount = (err.requestOptions.extra['retryCount'] as int?) ?? 0;
    if (retryCount >= maxRetries) {
      return handler.next(err);
    }

    // 指数退避等待
    final delay = Duration(
      milliseconds: retryDelay.inMilliseconds * (1 << retryCount), // 1s, 2s, 4s...
    );
    await Future.delayed(delay);

    // 更新重试计数
    err.requestOptions.extra['retryCount'] = retryCount + 1;

    try {
      final response = await dio.fetch(err.requestOptions);
      handler.resolve(response);
    } on DioException catch (e) {
      // 重试仍失败，继续传递
      handler.next(e);
    }
  }

  bool _shouldRetry(DioException err) {
    // 仅特定方法重试（POST 等非幂等方法一般不重试）
    if (!retryableMethods.contains(err.requestOptions.method)) {
      return false;
    }
    // 仅特定错误类型重试
    return err.type == DioExceptionType.connectionTimeout ||
        err.type == DioExceptionType.receiveTimeout ||
        err.type == DioExceptionType.connectionError;
  }
}

2.4 Transformer 自定义转换

import 'package:dio/dio.dart';
import 'dart:convert';

/// 自定义 Transformer — 统一处理响应数据包装
/// 适配后端标准格式: { "code": 0, "message": "ok", "data": {...} }
class AppTransformer extends BackgroundTransformer {
  @override
  Future<Response> transformResponse(
    RequestOptions options,
    ResponseBody responseBody,
  ) async {
    // 先调用默认转换
    final response = await super.transformResponse(options, responseBody);

    if (response.data is Map) {
      final map = response.data as Map<String, dynamic>;

      // 后端标准格式解包
      final code = map['code'];
      final message = map['message'] ?? '';
      final data = map['data'];

      // 业务错误码判断
      if (code != 0 && code != 200) {
        // 业务错误，转为 DioException
        throw DioException(
          requestOptions: options,
          response: Response(
            requestOptions: options,
            statusCode: response.statusCode,
            data: {'code': code, 'message': message, 'data': data},
          ),
          error: message,
          type: DioExceptionType.badResponse,
        );
      }

      // 解包 data 字段，简化后续使用
      response.data = data;
    }

    return response;
  }
}

2.5 CancelToken 取消请求

/// CancelToken 使用场景 — 页面退出时取消未完成请求
class CancelTokenExample {
  final Dio _dio = DioConfig.dio;

  // 页面级别的 CancelToken
  CancelToken? _cancelToken;

  /// 进入页面时创建 CancelToken
  void onPageInit() {
    _cancelToken = CancelToken();
  }

  /// 发起请求时绑定 CancelToken
  Future<void> fetchUserProfile(String userId) async {
    try {
      final response = await _dio.get(
        '/users/$userId',
        cancelToken: _cancelToken,
      );
      // 处理响应...
    } on DioException catch (e) {
      if (CancelToken.isCancel(e)) {
        print('请求已取消: ${e.message}');
      } else {
        print('请求失败: ${e.message}');
      }
    }
  }

  /// 页面销毁时取消所有请求
  void onPageDispose() {
    _cancelToken?.cancel('页面已退出');
    _cancelToken = null;
  }

  /// 手动取消特定请求
  void cancelSearch() {
    _cancelToken?.cancel('用户取消搜索');
    // 重新创建 CancelToken 以便后续请求
    _cancelToken = CancelToken();
  }
}

三、RESTful API 调用规范

/// RESTful API Repository 封装
/// 规范: 每个资源一个 Repository，方法命名遵循 REST 语义
class UserRepository {
  final Dio _dio = DioConfig.dio;

  /// 列表查询 — GET /users
  Future<PageResult<User>> getUsers({
    int page = 1,
    int size = 20,
    String? keyword,
    String? role,
  }) async {
    final response = await _dio.get('/users', queryParameters: {
      'page': page,
      'size': size,
      if (keyword != null) 'keyword': keyword,
      if (role != null) 'role': role,
    });
    return PageResult.fromJson(response.data, User.fromJson);
  }

  /// 详情查询 — GET /users/:id
  Future<User> getUserById(int id) async {
    final response = await _dio.get('/users/$id');
    return User.fromJson(response.data);
  }

  /// 创建 — POST /users
  Future<User> createUser(CreateUserRequest request) async {
    final response = await _dio.post('/users', data: request.toJson());
    return User.fromJson(response.data);
  }

  /// 全量更新 — PUT /users/:id
  Future<User> updateUser(int id, UpdateUserRequest request) async {
    final response = await _dio.put('/users/$id', data: request.toJson());
    return User.fromJson(response.data);
  }

  /// 部分更新 — PATCH /users/:id
  Future<User> patchUser(int id, Map<String, dynamic> fields) async {
    final response = await _dio.patch('/users/$id', data: fields);
    return User.fromJson(response.data);
  }

  /// 删除 — DELETE /users/:id
  Future<void> deleteUser(int id) async {
    await _dio.delete('/users/$id');
  }

  /// 批量删除 — DELETE /users/batch
  Future<void> batchDeleteUsers(List<int> ids) async {
    await _dio.delete('/users/batch', data: {'ids': ids});
  }
}

/// 分页结果通用模型
class PageResult<T> {
  final List<T> items;
  final int total;
  final int page;
  final int size;

  PageResult({
    required this.items,
    required this.total,
    required this.page,
    required this.size,
  });

  factory PageResult.fromJson(
    Map<String, dynamic> json,
    T Function(Map<String, dynamic>) fromJsonT,
  ) {
    return PageResult(
      items: (json['items'] as List).map((e) => fromJsonT(e)).toList(),
      total: json['total'] as int,
      page: json['page'] as int,
      size: json['size'] as int,
    );
  }

  bool get hasMore => page * size < total;
}

四、文件上传与下载

4.1 文件上传（multipart/formData）

import 'package:dio/dio.dart';
import 'dart:typed_data';

/// 文件上传示例
class FileUploadService {
  final Dio _dio = DioConfig.dio;

  /// 单文件上传
  Future<String> uploadSingleFile(String filePath) async {
    final formData = FormData.fromMap({
      'file': await MultipartFile.fromFile(
        filePath,
        filename: filePath.split('/').last, // 文件名
      ),
      'category': 'avatar', // 附加字段
    });

    final response = await _dio.post('/upload', data: formData);
    return response.data['url']; // 返回文件 URL
  }

  /// 多文件上传
  Future<List<String>> uploadMultipleFiles(List<String> filePaths) async {
    // 构建多文件 FormData
    final files = await Future.wait(
      filePaths.map((path) => MultipartFile.fromFile(
        path,
        filename: path.split('/').last,
      )),
    );

    final formData = FormData.fromMap({
      'files': files, // 同名字段传递 List
      'category': 'gallery',
    });

    final response = await _dio.post('/upload/batch', data: formData);
    return (response.data['urls'] as List).cast<String>();
  }

  /// 上传字节数据（如拍照后的内存图片）
  Future<String> uploadBytes({
    required Uint8List bytes,
    required String fileName,
    String contentType = 'image/jpeg',
  }) async {
    final formData = FormData.fromMap({
      'file': MultipartFile.fromBytes(
        bytes,
        filename: fileName,
        contentType: DioMediaType.parse(contentType), // 指定 Content-Type
      ),
    });

    final response = await _dio.post('/upload', data: formData);
    return response.data['url'];
  }

  /// 带进度监听的上传
  Future<String> uploadWithProgress(
    String filePath, {
    CancelToken? cancelToken,
  }) async {
    final formData = FormData.fromMap({
      'file': await MultipartFile.fromFile(filePath),
    });

    final response = await _dio.post(
      '/upload',
      data: formData,
      cancelToken: cancelToken,
      onSendProgress: (sent, total) {
        // sent: 已发送字节, total: 总字节
        if (total > 0) {
          final progress = (sent / total * 100).toStringAsFixed(1);
          print('上传进度: $progress% ($sent/$total)');
          // 实际项目中通知 UI 更新进度条
        }
      },
    );
    return response.data['url'];
  }

  /// 分片上传（大文件）
  Future<String> uploadChunked({
    required String filePath,
    required int chunkSize, // 每片大小（字节）
    CancelToken? cancelToken,
  }) async {
    final file = File(filePath);
    final fileSize = await file.length();
    final fileName = filePath.split('/').last;
    final totalChunks = (fileSize / chunkSize).ceil();

    // 1. 获取上传 ID
    final initResp = await _dio.post('/upload/init', data: {
      'fileName': fileName,
      'fileSize': fileSize,
      'chunkSize': chunkSize,
      'totalChunks': totalChunks,
    });
    final uploadId = initResp.data['uploadId'];

    // 2. 逐片上传
    for (var i = 0; i < totalChunks; i++) {
      final offset = i * chunkSize;
      final end = (offset + chunkSize > fileSize) ? fileSize : offset + chunkSize;
      final chunk = file.openRead(offset, end);

      final formData = FormData.fromMap({
        'chunk': MultipartFile.fromStream(
          () => chunk,
          end - offset,
          filename: '$fileName.part$i',
        ),
        'uploadId': uploadId,
        'chunkIndex': i,
        'totalChunks': totalChunks,
      });

      await _dio.post(
        '/upload/chunk',
        data: formData,
        cancelToken: cancelToken,
        onSendProgress: (sent, total) {
          // 整体进度 = (已完成片数 * chunkSize + 当前片已传) / fileSize
          final overallProgress =
              (i * chunkSize + sent) / fileSize * 100;
          print('整体进度: ${overallProgress.toStringAsFixed(1)}%');
        },
      );
    }

    // 3. 通知合并
    final mergeResp = await _dio.post('/upload/merge', data: {
      'uploadId': uploadId,
      'fileName': fileName,
    });
    return mergeResp.data['url'];
  }
}

4.2 文件下载（进度监听 + 断点续传）

import 'package:dio/dio.dart';
import 'package:path_provider/path_provider.dart';
import 'dart:io';

/// 文件下载服务
class FileDownloadService {
  final Dio _dio = DioConfig.dio;

  /// 基础下载
  Future<String> downloadFile(String url, String savePath) async {
    await _dio.download(url, savePath);
    return savePath;
  }

  /// 带进度监听的下载
  Future<String> downloadWithProgress(
    String url, {
    CancelToken? cancelToken,
    Function(int, int)? onProgress, // received, total
  }) async {
    final savePath = await _getSavePath(url);

    await _dio.download(
      url,
      savePath,
      cancelToken: cancelToken,
      onReceiveProgress: (received, total) {
        if (total > 0) {
          final progress = (received / total * 100).toStringAsFixed(1);
          print('下载进度: $progress%');
          onProgress?.call(received, total);
        }
      },
    );
    return savePath;
  }

  /// 断点续传下载
  /// 原理: 检查本地已下载文件大小，用 Range 请求头续传
  Future<String> downloadWithResume(
    String url, {
    CancelToken? cancelToken,
    Function(int, int)? onProgress,
  }) async {
    final savePath = await _getSavePath(url);
    final file = File(savePath);

    // 检查已下载的字节数
    int downloadedBytes = 0;
    if (await file.exists()) {
      downloadedBytes = await file.length();
      print('已有部分下载: $downloadedBytes bytes');
    }

    // 设置 Range 请求头
    final options = Options();
    if (downloadedBytes > 0) {
      options.headers = {'Range': 'bytes=$downloadedBytes-'};
    }

    // 使用 openWrite 以追加模式写入
    final raf = await file.open(mode: FileMode.append);

    try {
      await _dio.get(
        url,
        options: Options(
          responseType: ResponseType.stream, // 流式接收
          headers: downloadedBytes > 0
              ? {'Range': 'bytes=$downloadedBytes-'}
              : null,
        ),
        cancelToken: cancelToken,
        onReceiveProgress: (received, total) {
          // total 为完整文件大小，received 为当前会话已接收
          final overallReceived = downloadedBytes + received;
          final overallTotal = downloadedBytes + total;
          onProgress?.call(overallReceived, overallTotal);
        },
      ).then((response) async {
        // 流式写入文件
        final stream = response.data as ResponseBody;
        await for (final chunk in stream.stream) {
          await raf.writeFrom(chunk);
        }
      });
    } finally {
      await raf.close();
    }

    return savePath;
  }

  /// 根据下载 URL 生成保存路径
  Future<String> _getSavePath(String url) async {
    final dir = await getApplicationDocumentsDirectory();
    final fileName = url.split('/').last.split('?').first;
    return '${dir.path}/downloads/$fileName';
  }
}

五、WebSocket 实时通信

import 'package:web_socket_channel/web_socket_channel.dart';
import 'package:web_socket_channel/status.dart' as status;
import 'dart:async';
import 'dart:convert';

/// WebSocket 服务 — 自动重连 + 心跳保活
class WebSocketService {
  static const _heartbeatInterval = Duration(seconds: 30);
  static const _reconnectDelay = Duration(seconds: 3);
  static const _maxReconnectAttempts = 5;

  WebSocketChannel? _channel;
  String? _url;
  String? _token;
  int _reconnectAttempts = 0;
  bool _isManualClose = false;

  // 心跳定时器
  Timer? _heartbeatTimer;
  // 重连定时器
  Timer? _reconnectTimer;

  // 消息流控制器
  final _messageController = StreamController<String>.broadcast();
  Stream<String> get messageStream => _messageController.stream;

  // 连接状态
  final _connectionStateController = StreamController<WsState>.broadcast();
  Stream<WsState> get connectionState => _connectionStateController.stream;

  /// 连接 WebSocket
  Future<void> connect(String url, {String? token}) async {
    _url = url;
    _token = token;
    _isManualClose = false;

    try {
      _updateState(WsState.connecting);

      // 构建 WebSocket URL（含 Token 认证）
      final wsUrl = token != null
          ? '$url?token=$token'
          : url;

      _channel = WebSocketChannel.connect(Uri.parse(wsUrl));

      // 监听消息
      _channel!.stream.listen(
        _onMessage,
        onError: _onError,
        onDone: _onDone,
        cancelOnError: false,
      );

      _updateState(WsState.connected);
      _reconnectAttempts = 0;
      _startHeartbeat();
    } catch (e) {
      print('WebSocket 连接失败: $e');
      _scheduleReconnect();
    }
  }

  /// 发送消息
  void send(String message) {
    if (_channel != null) {
      _channel!.sink.add(message);
    }
  }

  /// 发送 JSON 消息
  void sendJson(Map<String, dynamic> data) {
    send(json.encode(data));
  }

  /// 断开连接
  void disconnect() {
    _isManualClose = true;
    _stopHeartbeat();
    _reconnectTimer?.cancel();
    _channel?.sink.close(status.goingAway);
    _updateState(WsState.disconnected);
  }

  /// 收到消息回调
  void _onMessage(dynamic message) {
    // 收到消息，重置心跳计时
    _resetHeartbeat();

    if (message is String) {
      // 心跳响应，不需要广播
      if (message == 'pong' || message == '{"type":"pong"}') {
        return;
      }
      _messageController.add(message);
    }
  }

  /// 错误回调
  void _onError(dynamic error) {
    print('WebSocket 错误: $error');
    _updateState(WsState.error);
    _scheduleReconnect();
  }

  /// 连接关闭回调
  void _onDone() {
    print('WebSocket 连接关闭');
    _stopHeartbeat();
    _updateState(WsState.disconnected);
    if (!_isManualClose) {
      _scheduleReconnect();
    }
  }

  /// 启动心跳
  void _startHeartbeat() {
    _heartbeatTimer?.cancel();
    _heartbeatTimer = Timer.periodic(_heartbeatInterval, (_) {
      send('ping'); // 或 sendJson({'type': 'ping'});
    });
  }

  /// 收到消息后重置心跳计时
  void _resetHeartbeat() {
    _stopHeartbeat();
    _startHeartbeat();
  }

  /// 停止心跳
  void _stopHeartbeat() {
    _heartbeatTimer?.cancel();
    _heartbeatTimer = null;
  }

  /// 计划重连
  void _scheduleReconnect() {
    if (_isManualClose) return;
    if (_reconnectAttempts >= _maxReconnectAttempts) {
      print('达到最大重连次数，停止重连');
      _updateState(WsState.failed);
      return;
    }

    _reconnectAttempts++;
    final delay = Duration(
      seconds: _reconnectDelay.inSeconds * _reconnectAttempts, // 递增延迟
    );

    print('将在 ${delay.inSeconds}s 后重连 (第 $_reconnectAttempts 次)');

    _reconnectTimer?.cancel();
    _reconnectTimer = Timer(delay, () {
      if (_url != null) {
        connect(_url!, token: _token);
      }
    });
  }

  void _updateState(WsState state) {
    _connectionStateController.add(state);
  }

  void dispose() {
    disconnect();
    _messageController.close();
    _connectionStateController.close();
  }
}

/// WebSocket 连接状态枚举
enum WsState {
  disconnected,
  connecting,
  connected,
  error,
  failed,
}

WebSocket 在 Widget 中使用：

import 'package:flutter/material.dart';

/// 聊天页面 — WebSocket 实时通信示例
class ChatPage extends StatefulWidget {
  const ChatPage({super.key});

  @override
  State<ChatPage> createState() => _ChatPageState();
}

class _ChatPageState extends State<ChatPage> {
  final _wsService = WebSocketService();
  final _messageController = TextEditingController();
  final List<ChatMessage> _messages = [];
  StreamSubscription? _subscription;

  @override
  void initState() {
    super.initState();
    _connectWebSocket();
  }

  void _connectWebSocket() async {
    // 连接 WebSocket
    await _wsService.connect(
      'wss://api.example.com/ws/chat',
      token: 'user_token_here',
    );

    // 监听消息
    _subscription = _wsService.messageStream.listen((message) {
      final data = json.decode(message) as Map<String, dynamic>;
      setState(() {
        _messages.add(ChatMessage(
          content: data['content'] as String,
          sender: data['sender'] as String,
          isMe: false,
          timestamp: DateTime.now(),
        ));
      });
    });
  }

  void _sendMessage() {
    final text = _messageController.text.trim();
    if (text.isEmpty) return;

    // 发送消息
    _wsService.sendJson({
      'type': 'chat',
      'content': text,
      'timestamp': DateTime.now().toIso8601String(),
    });

    setState(() {
      _messages.add(ChatMessage(
        content: text,
        sender: 'me',
        isMe: true,
        timestamp: DateTime.now(),
      ));
    });
    _messageController.clear();
  }

  @override
  void dispose() {
    _subscription?.cancel();
    _wsService.dispose();
    _messageController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Chat')),
      body: Column(
        children: [
          // 消息列表
          Expanded(
            child: ListView.builder(
              itemCount: _messages.length,
              itemBuilder: (context, index) {
                final msg = _messages[index];
                return ListTile(
                  title: Text(msg.content),
                  subtitle: Text(msg.sender),
                );
              },
            ),
          ),
          // 输入区
          Padding(
            padding: const EdgeInsets.all(8.0),
            child: Row(
              children: [
                Expanded(
                  child: TextField(
                    controller: _messageController,
                    decoration: const InputDecoration(
                      hintText: '输入消息...',
                      border: OutlineInputBorder(),
                    ),
                    onSubmitted: (_) => _sendMessage(),
                  ),
                ),
                IconButton(
                  icon: const Icon(Icons.send),
                  onPressed: _sendMessage,
                ),
              ],
            ),
          ),
        ],
      ),
    );
  }
}

class ChatMessage {
  final String content;
  final String sender;
  final bool isMe;
  final DateTime timestamp;

  ChatMessage({
    required this.content,
    required this.sender,
    required this.isMe,
    required this.timestamp,
  });
}

六、JSON 序列化与反序列化

6.1 手写 fromJson / toJson（简单场景）

/// 手写序列化 — 适合模型数量少的小项目
class User {
  final int id;
  final String name;
  final String email;
  final String? avatar;   // 可空字段
  final Role role;
  final DateTime createdAt;

  User({
    required this.id,
    required this.name,
    required this.email,
    this.avatar,
    required this.role,
    required this.createdAt,
  });

  /// 从 JSON Map 创建对象
  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'] as int,
      name: json['name'] as String,
      email: json['email'] as String,
      avatar: json['avatar'] as String?,   // 可空类型
      role: Role.values.firstWhere(
        (e) => e.name == json['role'],
        orElse: () => Role.user,           // 默认值
      ),
      createdAt: DateTime.parse(json['createdAt'] as String),
    );
  }

  /// 转为 JSON Map
  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'name': name,
      'email': email,
      'avatar': avatar,
      'role': role.name,
      'createdAt': createdAt.toIso8601String(),
    };
  }
}

enum Role { admin, user, guest }

6.2 json_serializable + build_runner（推荐）

import 'package:json_annotation/json_annotation.dart';

// 关联生成的文件
part 'user_model.g.dart';

/// 使用 json_serializable 自动生成序列化代码
/// 1. 编写模型 + 添加注解
/// 2. 运行: dart run build_runner build --delete-conflicting-outputs
/// 3. 自动生成 user_model.g.dart

@JsonSerializable(explicitToJson: true) // 嵌套对象也序列化
class UserModel {
  final int id;

  @JsonKey(name: 'user_name') // JSON 字段名与 Dart 属性名不同
  final String userName;

  @JsonKey(defaultValue: '') // 缺失时的默认值
  final String email;

  @JsonKey(fromJson: _avatarFromJson, toJson: _avatarToJson) // 自定义转换
  final String avatarUrl;

  @JsonKey(unknownEnumValue: Role.user) // 未知枚举值的默认值
  final Role role;

  @JsonKey(name: 'created_at')
  final DateTime createdAt;

  // 嵌套对象 — 需要该类也有 JsonSerializable 注解
  final AddressModel? address;

  // 列表类型
  @JsonKey(defaultValue: [])
  final List<String> tags;

  UserModel({
    required this.id,
    required this.userName,
    this.email = '',
    required this.avatarUrl,
    required this.role,
    required this.createdAt,
    this.address,
    this.tags = const [],
  });

  // 生成代码的入口
  factory UserModel.fromJson(Map<String, dynamic> json) =>
      _$UserModelFromJson(json);
  Map<String, dynamic> toJson() => _$UserModelToJson(this);

  // 自定义 JSON 转换函数
  static String _avatarFromJson(dynamic value) {
    if (value is String && value.isNotEmpty) {
      return value.startsWith('http') ? value : 'https://cdn.example.com$value';
    }
    return 'https://cdn.example.com/default.png';
  }

  static String _avatarToJson(String url) => url;
}

@JsonSerializable()
class AddressModel {
  final String city;
  final String street;

  AddressModel({required this.city, required this.street});

  factory AddressModel.fromJson(Map<String, dynamic> json) =>
      _$AddressModelFromJson(json);
  Map<String, dynamic> toJson() => _$AddressModelToJson(this);
}

build_runner 命令：

# 一次性生成
dart run build_runner build --delete-conflicting-outputs

# 持续监听文件变化自动生成
dart run build_runner watch --delete-conflicting-outputs

# 清理生成文件
dart run build_runner clean

七、SharedPreferences 键值对存储

import 'package:shared_preferences/shared_preferences.dart';

/// SharedPreferences 封装 — 类型安全的键值存储
/// 适合: 用户偏好、配置项、简单标记
/// 不适合: 大量数据、结构化数据、敏感信息
class PrefsService {
  static SharedPreferences? _prefs;

  /// 初始化（在 main() 中调用）
  static Future<void> init() async {
    _prefs = await SharedPreferences.getInstance();
  }

  static SharedPreferences get _instance {
    if (_prefs == null) throw Exception('PrefsService 未初始化');
    return _prefs!;
  }

  // ============ 类型安全存取 ============

  /// String
  static String? getString(PrefKey key) => _instance.getString(key.name);
  static Future<bool> setString(PrefKey key, String value) =>
      _instance.setString(key.name, value);

  /// int
  static int? getInt(PrefKey key) => _instance.getInt(key.name);
  static Future<bool> setInt(PrefKey key, int value) =>
      _instance.setInt(key.name, value);

  /// double
  static double? getDouble(PrefKey key) => _instance.getDouble(key.name);
  static Future<bool> setDouble(PrefKey key, double value) =>
      _instance.setDouble(key.name, value);

  /// bool
  static bool? getBool(PrefKey key) => _instance.getBool(key.name);
  static Future<bool> setBool(PrefKey key, bool value) =>
      _instance.setBool(key.name, value);

  /// StringList
  static List<String>? getStringList(PrefKey key) =>
      _instance.getStringList(key.name);
  static Future<bool> setStringList(PrefKey key, List<String> value) =>
      _instance.setStringList(key.name, value);

  // ============ 便捷方法 ============

  /// 删除指定键
  static Future<bool> remove(PrefKey key) => _instance.remove(key.name);

  /// 清除所有数据
  static Future<bool> clear() => _instance.clear();

  /// 检查键是否存在
  static bool contains(PrefKey key) => _instance.containsKey(key.name);

  /// 读取复杂对象（JSON 序列化后存储）
  static T? getObject<T>(
    PrefKey key,
    T Function(Map<String, dynamic>) fromJson,
  ) {
    final jsonStr = _instance.getString(key.name);
    if (jsonStr == null) return null;
    return fromJson(json.decode(jsonStr) as Map<String, dynamic>);
  }

  /// 存储复杂对象（序列化为 JSON 字符串）
  static Future<bool> setObject(PrefKey key, dynamic object) {
    return _instance.setString(key.name, json.encode(object));
  }
}

/// 键名枚举 — 防止拼写错误
enum PrefKey {
  themeMode,        // 主题模式: 'light' / 'dark' / 'system'
  locale,           // 语言: 'zh' / 'en'
  accessToken,      // 访问令牌（实际应存 flutter_secure_storage）
  isFirstLaunch,    // 是否首次启动
  lastReadArticleId,// 最后阅读的文章 ID
  recentSearches,   // 最近搜索词列表
  fontSize,         // 字体大小
  pushEnabled,      // 推送通知开关
}

在 main() 中初始化：

void main() async {
  WidgetsFlutterBinding.ensureInitialized(); // 必须在 async main 中调用

  // 初始化 SharedPreferences
  await PrefsService.init();

  // 读取偏好设置
  final themeMode = PrefsService.getString(PrefKey.themeMode) ?? 'system';
  final isFirstLaunch = PrefsService.getBool(PrefKey.isFirstLaunch) ?? true;

  runApp(MyApp(themeMode: themeMode, isFirstLaunch: isFirstLaunch));
}

八、SQLite 数据库

8.1 sqflite 原生操作

import 'package:sqflite/sqflite.dart';
import 'package:path/path.dart' as p;

/// sqflite 数据库操作 — 原生 SQL 方式
class AppDatabase {
  static Database? _database;

  /// 获取数据库实例
  Future<Database> get database async {
    _database ??= await _initDatabase();
    return _database!;
  }

  /// 初始化数据库
  Future<Database> _initDatabase() async {
    final dbPath = await getDatabasesPath();
    final path = p.join(dbPath, 'app.db');

    return await openDatabase(
      path,
      version: 3, // 数据库版本号，每次 schema 变更递增
      onCreate: _onCreate,         // 首次创建时执行
      onUpgrade: _onUpgrade,       // 版本升级时执行
      onConfigure: _onConfigure,   // 数据库配置（如外键支持）
    );
  }

  /// 数据库配置
  Future<void> _onConfigure(Database db) async {
    // 启用外键约束（默认关闭）
    await db.execute('PRAGMA foreign_keys = ON');
  }

  /// 创建表
  Future<void> _onCreate(Database db, int version) async {
    // 一次性执行所有版本的建表语句
    await db.execute('''
      CREATE TABLE users (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        name TEXT NOT NULL,
        email TEXT UNIQUE NOT NULL,
        avatar TEXT,
        role TEXT NOT NULL DEFAULT 'user',
        created_at INTEGER NOT NULL,
        updated_at INTEGER NOT NULL
      )
    ''');

    await db.execute('''
      CREATE TABLE articles (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        title TEXT NOT NULL,
        content TEXT NOT NULL,
        author_id INTEGER NOT NULL,
        status TEXT NOT NULL DEFAULT 'draft',
        published_at INTEGER,
        created_at INTEGER NOT NULL,
        FOREIGN KEY (author_id) REFERENCES users(id) ON DELETE CASCADE
      )
    ''');

    await db.execute('''
      CREATE TABLE article_tags (
        article_id INTEGER NOT NULL,
        tag TEXT NOT NULL,
        PRIMARY KEY (article_id, tag),
        FOREIGN KEY (article_id) REFERENCES articles(id) ON DELETE CASCADE
      )
    ''');

    // 创建索引
    await db.execute(
      'CREATE INDEX idx_articles_author ON articles(author_id)',
    );
    await db.execute(
      'CREATE INDEX idx_articles_status ON articles(status)',
    );
    await db.execute(
      'CREATE INDEX idx_article_tags_tag ON article_tags(tag)',
    );
  }

  /// 数据库升级迁移
  Future<void> _onUpgrade(Database db, int oldVersion, int newVersion) async {
    // 逐版本迁移，避免跳版问题
    if (oldVersion < 2) {
      // v1 → v2: 添加 articles 表的 summary 字段
      await db.execute('ALTER TABLE articles ADD COLUMN summary TEXT');
    }
    if (oldVersion < 3) {
      // v2 → v3: 添加 bookmarks 表
      await db.execute('''
        CREATE TABLE bookmarks (
          id INTEGER PRIMARY KEY AUTOINCREMENT,
          article_id INTEGER NOT NULL,
          user_id INTEGER NOT NULL,
          created_at INTEGER NOT NULL,
          UNIQUE(article_id, user_id),
          FOREIGN KEY (article_id) REFERENCES articles(id) ON DELETE CASCADE,
          FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
        )
      ''');
    }
  }
}

sqflite CRUD 操作：

/// 用户数据访问对象 (DAO)
class UserDao {
  final AppDatabase _db = AppDatabase();

  /// 插入 — INSERT
  Future<int> insert(User user) async {
    final db = await _db.database;
    return await db.insert(
      'users',
      user.toMap(),
      conflictAlgorithm: ConflictAlgorithm.replace, // 冲突时替换
    );
  }

  /// 批量插入 — BATCH INSERT
  Future<void> insertBatch(List<User> users) async {
    final db = await _db.database;
    final batch = db.batch();
    for (final user in users) {
      batch.insert('users', user.toMap(),
          conflictAlgorithm: ConflictAlgorithm.ignore);
    }
    await batch.commit(noResult: true); // 无需返回结果，性能更优
  }

  /// 查询所有 — SELECT
  Future<List<User>> getAll() async {
    final db = await _db.database;
    final maps = await db.query(
      'users',
      columns: ['id', 'name', 'email', 'avatar', 'role', 'created_at'],
      orderBy: 'created_at DESC', // 按创建时间倒序
    );
    return maps.map((m) => User.fromMap(m)).toList();
  }

  /// 条件查询 — WHERE
  Future<List<User>> search(String keyword) async {
    final db = await _db.database;
    final maps = await db.query(
      'users',
      where: 'name LIKE ? OR email LIKE ?',
      whereArgs: ['%$keyword%', '%$keyword%'],
      limit: 20,
    );
    return maps.map((m) => User.fromMap(m)).toList();
  }

  /// 单条查询
  Future<User?> getById(int id) async {
    final db = await _db.database;
    final maps = await db.query(
      'users',
      where: 'id = ?',
      whereArgs: [id],
      limit: 1,
    );
    if (maps.isEmpty) return null;
    return User.fromMap(maps.first);
  }

  /// 更新 — UPDATE
  Future<int> update(User user) async {
    final db = await _db.database;
    return await db.update(
      'users',
      {
        ...user.toMap(),
        'updated_at': DateTime.now().millisecondsSinceEpoch,
      },
      where: 'id = ?',
      whereArgs: [user.id],
    );
  }

  /// 删除 — DELETE
  Future<int> delete(int id) async {
    final db = await _db.database;
    return await db.delete('users', where: 'id = ?', whereArgs: [id]);
  }

  /// 事务操作 — 保证原子性
  Future<void> transferRole(int fromId, int toId) async {
    final db = await _db.database;
    await db.transaction((txn) async {
      // 检查原用户角色
      final maps = await txn.query(
        'users',
        columns: ['role'],
        where: 'id = ?',
        whereArgs: [fromId],
      );
      if (maps.isEmpty) throw Exception('用户不存在');

      // 转移角色
      await txn.update(
        'users',
        {'role': 'user'},
        where: 'id = ?',
        whereArgs: [fromId],
      );
      await txn.update(
        'users',
        {'role': maps.first['role']},
        where: 'id = ?',
        whereArgs: [toId],
      );
    });
  }

  /// 原始 SQL 查询（复杂联表）
  Future<List<Map<String, dynamic>>> getArticleStats(int userId) async {
    final db = await _db.database;
    return await db.rawQuery('''
      SELECT
        u.name AS author_name,
        COUNT(a.id) AS article_count,
        SUM(CASE WHEN a.status = 'published' THEN 1 ELSE 0 END) AS published_count
      FROM users u
      LEFT JOIN articles a ON a.author_id = u.id
      WHERE u.id = ?
      GROUP BY u.id
    ''', [userId]);
  }
}