Flutter与Dart Frog¶

KanjiIQ使用Flutter构建前端，使用Dart Frog构建后端——统一的Dart生态系统简化了开发、测试和部署。

Flutter Web¶

为什么选择Flutter？¶

单一代码库：从同一源码构建Web、iOS、Android和桌面应用
Material Design 3：以最少的自定义样式实现原生般的UI
强大的i18n支持：内置基于ARB的本地化，支持51种语言
离线支持：通过sqflite包使用SQLite进行本地数据缓存

构建流程¶

Flutter Web生成静态资源（HTML、JS、CSS、图片），由Nginx提供服务：

# From Dockerfile.frontend (simplified)
FROM ubuntu:22.04 AS builder
# Install Flutter SDK
RUN flutter gen-l10n          # Generate 51 localization files
RUN flutter build web --release

FROM nginx:alpine
COPY --from=builder /app/frontend/build/web /usr/share/nginx/html

构建参数：

API_URL — 后端API端点（默认为相对路径/api/）
CACHEBUST — 在CI/CD中强制全新构建（基于时间戳）

状态管理¶

KanjiIQ使用Provider进行状态管理：

MultiProvider(
  providers: [
    ChangeNotifierProvider(create: (_) => StudyProvider()),
    // Locale, connectivity, sync providers
  ],
  child: MyApp(),
)

选择Provider而非其他方案（Riverpod、BLoC）是因为其简洁性——KanjiIQ的状态需求很直接（闪卡会话状态、区域偏好、连接状态）。

路由¶

GoRouter处理声明式路由，支持：

深度链接（基于URL的导航）
重定向守卫（认证检查）
嵌套路由，支持页面层级结构

Dart Frog后端¶

为什么选择Dart Frog？¶

与前端相同的语言：可以共享Dart模型
轻量级：框架开销最小，类似Express.js
基于中间件：清晰的请求管道，支持可组合的中间件
热重载：通过dart_frog dev快速迭代开发

请求生命周期¶

graph LR
    R[HTTP Request] --> MW[Middleware Stack]
    MW --> RH[Route Handler]
    RH --> DB[(PostgreSQL)]
    DB --> RH
    RH --> RS[JSON Response]

每个路由是routes/目录中的一个Dart文件。Dart Frog使用基于文件的路由：

backend/routes/
├── _middleware.dart           # Global middleware
├── api/v1/
│   ├── kanji/
│   │   ├── index.dart         # GET /api/v1/kanji
│   │   ├── [id].dart          # GET /api/v1/kanji/:id
│   │   └── random/
│   │       └── index.dart     # GET /api/v1/kanji/random
│   └── admin/
│       ├── _middleware.dart    # Admin auth middleware
│       └── ...

构建流程¶

# From Dockerfile.backend (simplified)
FROM dart:stable AS builder
RUN dart pub global activate dart_frog_cli
RUN dart_frog build

FROM dart:stable
COPY --from=builder /app/build /app
CMD ["./server"]

构建步骤将Dart编译为独立的服务器二进制文件，所有路由均已预注册。

共享Dart生态系统¶

前端和后端都受益于相同的Dart工具链：

工具	用途
`dart analyze`	对两个代码库进行静态分析
`dart format`	一致的代码风格
`dart test`	单元测试和集成测试
`pub.dev`	共享的包仓库

移动端就绪¶

Flutter前端为多平台部署而设计：

Web：当前已部署（主要目标）
iOS/Android：可通过flutter build apk / flutter build ipa构建
桌面端：支持flutter build macos / linux / windows

离线优先架构（SQLite缓存、连接检测、后台同步）从一开始就考虑了移动端需求。