Back to Details

flutter-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Flutter Architecture

Flutter应用架构

Overview

概述

Provides architectural guidance and best practices for building scalable Flutter applications using MVVM pattern, layered architecture, and recommended design patterns from the Flutter team.
本指南提供了使用MVVM模式、分层架构以及Flutter团队推荐的设计模式构建可扩展Flutter应用的架构指导和最佳实践。

Project Structure: Feature-First vs Layer-First

项目结构：功能优先 vs 分层优先

Choose the right project organization based on your app's complexity and team size.
根据应用的复杂度和团队规模选择合适的项目组织方式。

Feature-First (Recommended for teams)

功能优先（推荐团队使用）

Organize code by business features:
lib/
├── features/
│   ├── auth/
│   │   ├── data/
│   │   ├── domain/
│   │   └── presentation/
│   ├── todos/
│   │   ├── data/
│   │   ├── domain/
│   │   └── presentation/
│   └── settings/
│       ├── data/
│       ├── domain/
│       └── presentation/
├── shared/
│   ├── core/
│   ├── data/
│   └── ui/
└── main.dart
When to use:
  • Medium to large apps (10+ features)
  • Team development (2+ developers)
  • Frequently adding/removing features
  • Complex business logic
Benefits:
  • Features are self-contained units
  • Easy to add/remove entire features
  • Clear feature boundaries
  • Reduced merge conflicts
  • Teams work independently on features
See Feature-First Guide for complete implementation details.
按业务功能组织代码：
lib/
├── features/
│   ├── auth/
│   │   ├── data/
│   │   ├── domain/
│   │   └── presentation/
│   ├── todos/
│   │   ├── data/
│   │   ├── domain/
│   │   └── presentation/
│   └── settings/
│       ├── data/
│       ├── domain/
│       └── presentation/
├── shared/
│   ├── core/
│   ├── data/
│   └── ui/
└── main.dart
适用场景：
  • 中大型应用（10个以上功能）
  • 团队开发（2名及以上开发者）
  • 需要频繁添加/移除功能
  • 业务逻辑复杂
优势：
  • 功能为独立的自包含单元
  • 易于添加/移除完整功能
  • 功能边界清晰
  • 减少代码合并冲突
  • 团队可独立开发不同功能
查看功能优先指南获取完整实现细节。

Layer-First (Traditional)

分层优先（传统方式）

Organize code by architectural layers:
lib/
├── data/
│   ├── repositories/
│   ├── services/
│   └── models/
├── domain/
│   ├── use-cases/
│   └── entities/
├── presentation/
│   ├── views/
│   └── viewmodels/
└── shared/
When to use:
  • Small to medium apps
  • Few features (<10)
  • Solo developers or small teams
  • Simple business logic
Benefits:
  • Clear separation by layer
  • Easy to find components by type
  • Less nesting
按架构分层组织代码：
lib/
├── data/
│   ├── repositories/
│   ├── services/
│   └── models/
├── domain/
│   ├── use-cases/
│   └── entities/
├── presentation/
│   ├── views/
│   └── viewmodels/
└── shared/
适用场景：
  • 中小型应用
  • 功能较少（少于10个）
  • 独立开发者或小型团队
  • 业务逻辑简单
优势：
  • 分层边界清晰
  • 易于按组件类型查找
  • 嵌套层级更少

Quick Start

快速入门

Start with these core concepts:
  1. Separation of concerns - Split app into UI and Data layers
  2. MVVM pattern - Use Views, ViewModels, Repositories, and Services
  3. Single source of truth - Repositories hold the authoritative data
  4. Unidirectional data flow - State flows from data → logic → UI
For detailed concepts, see Concepts.
从以下核心概念开始：
  1. 关注点分离 - 将应用拆分为UI层和数据层
  2. MVVM模式 - 使用Views、ViewModels、Repositories和Services
  3. 单一数据源 - Repositories作为数据的权威来源
  4. 单向数据流 - 状态从数据→逻辑→UI流动
如需了解详细概念，请查看核心概念。

Architecture Layers

架构分层

Flutter apps should be structured in layers:
  • UI Layer: Views (widgets) and ViewModels (UI logic)
  • Data Layer: Repositories (SSOT) and Services (data sources)
  • Domain Layer (optional): Use-cases for complex business logic
See Layers Guide for detailed layer responsibilities and interactions.
Flutter应用应按以下分层构建：
  • UI层：Views（组件）和ViewModels（UI逻辑）
  • 数据层：Repositories（单一数据源）和Services（数据源封装）
  • 领域层（可选）：处理复杂业务逻辑的用例
查看分层指南获取各层的详细职责和交互说明。

Core Components

核心组件

Views

Views

  • Compose widgets for UI presentation
  • Contain minimal logic (animations, simple conditionals, routing)
  • Receive data from ViewModels
  • Pass events via ViewModel commands
  • 组合组件实现UI展示
  • 仅包含少量逻辑（动画、简单条件判断、路由）
  • 从ViewModels接收数据
  • 通过ViewModel命令传递事件

ViewModels

ViewModels

  • Transform repository data into UI state
  • Manage UI state and commands
  • Handle business logic for UI interactions
  • Expose state as streams or change notifiers
  • 将Repository数据转换为UI状态
  • 管理UI状态和命令
  • 处理UI交互相关的业务逻辑
  • 以流或变更通知器的形式暴露状态

Repositories

Repositories

  • Single source of truth for data types
  • Aggregate data from services
  • Handle caching, error handling, retry logic
  • Expose data as domain models
  • 对应数据类型的单一数据源
  • 聚合来自多个Services的数据
  • 处理缓存、错误处理、重试逻辑
  • 以领域模型的形式暴露数据

Services

Services

  • Wrap external data sources (APIs, databases, platform APIs)
  • Stateless data access layer
  • One service per data source
  • 封装外部数据源（API、数据库、平台API）
  • 无状态的数据访问层
  • 每个数据源对应一个Service

Design Patterns

设计模式

Common patterns for robust Flutter apps:
  • Command Pattern - Encapsulate actions with Result handling
  • Result Type - Type-safe error handling
  • Repository Pattern - Abstraction over data sources
  • Offline-First - Optimistic UI updates with sync
See Design Patterns for implementation details.
构建健壮Flutter应用的常用模式：
  • Command Pattern - 结合结果处理封装操作
  • Result Type - 类型安全的错误处理
  • Repository Pattern - 对数据源的抽象
  • Offline-First - 配合同步实现乐观UI更新
查看设计模式指南获取实现细节。

When to Use This Skill

适用场景

Use this skill when:
  • Designing or refactoring Flutter app architecture
  • Choosing between feature-first and layer-first project structure
  • Implementing MVVM pattern in Flutter
  • Creating scalable app structure for teams
  • Adding new features to existing architecture
  • Applying best practices and design patterns
在以下场景使用本指南：
  • 设计或重构Flutter应用架构
  • 在功能优先和分层优先项目结构间做选择
  • 在Flutter中实现MVVM模式
  • 为团队构建可扩展的应用结构
  • 为现有架构添加新功能
  • 应用最佳实践和设计模式

Resources

资源

references/

参考文档/

  • concepts.md - Core architectural principles (separation of concerns, SSOT, UDF)
  • feature-first.md - Feature-first project organization and best practices
  • mvvm.md - MVVM pattern implementation in Flutter
  • layers.md - Detailed layer responsibilities and interactions
  • design-patterns.md - Common patterns and implementations
  • concepts.md - 核心架构原则（关注点分离、单一数据源、单向数据流）
  • feature-first.md - 功能优先项目组织方式及最佳实践
  • mvvm.md - Flutter中MVVM模式的实现
  • layers.md - 各层的详细职责和交互
  • design-patterns.md - 常用模式及实现

assets/

资源文件/

  • command.dart - Command pattern template for encapsulating actions
  • result.dart - Result type for safe error handling
  • examples/ - Code examples showing architecture in practice
  • command.dart - 用于封装操作的Command模式模板
  • result.dart - 用于安全错误处理的Result类型
  • examples/ - 展示架构实践的代码示例