项目架构

良好的项目架构让代码可维护、可扩展。本文介绍 Flutter 项目的目录组织方式、代码规范和大型项目架构参考。

目录结构组织

基础分层结构（推荐入门）

lib/
├── main.dart                # 入口：只做初始化和启动
├── app.dart                 # 根 Widget（MaterialApp / GoRouter）
├── pages/                   # 页面
│   ├── home_page.dart
│   ├── login_page.dart
│   └── profile_page.dart
├── widgets/                 # 可复用组件
│   ├── loading.dart
│   ├── state_view.dart
│   └── primary_button.dart
├── models/                  # 数据模型
│   ├── user.dart
│   └── product.dart
├── services/                # 服务（网络请求、本地存储等）
│   ├── api_service.dart
│   └── storage_service.dart
├── providers/               # 状态管理（使用 Provider/Riverpod 时）
│   ├── user_provider.dart
│   └── cart_provider.dart
├── utils/                   # 工具函数
│   ├── validators.dart
│   └── date_formatter.dart
└── extensions/              # 扩展方法
    ├── string_extension.dart
    └── context_extension.dart

按特性分层结构（适合大型项目）

lib/
├── main.dart
├── app.dart
├── features/                # 按业务特性组织
│   ├── auth/                # 认证模块
│   │   ├── auth_page.dart
│   │   ├── auth_provider.dart
│   │   ├── auth_service.dart
│   │   └── models/
│   ├── product/             # 商品模块
│   │   ├── product_list_page.dart
│   │   ├── product_detail_page.dart
│   │   ├── product_provider.dart
│   │   └── models/
│   └── cart/                # 购物车模块
│       ├── cart_page.dart
│       └── cart_provider.dart
├── shared/                  # 共享代码
│   ├── widgets/
│   ├── utils/
│   └── extensions/
└── core/                   # 核心基础设施
    ├── network/
    ├── storage/
    └── theme/

选择指南

项目规模	推荐结构
小型（< 10 页面）	基础分层结构
中型（10~30 页面）	基础分层 + 适当拆分
大型（30+ 页面）	按特性分层

---

代码规范

analysis_options.yaml

include: package:flutter_lints/flutter.yaml

linter:
  rules:
    prefer_const_constructors: true    # 优先用 const
    prefer_single_quotes: true          # 优先用单引号
    avoid_print: true                   # 避免用 print
    always_declare_return_types: true   # 声明返回类型
    prefer_final_fields: true           # 优先用 final
    prefer_final_locals: true           # 局部变量优先用 final

analyzer:
  exclude:
    - "**/*.g.dart"        # 代码生成文件
    - "**/*.freezed.dart"

# 第三方 lint 插件
# plugins:
#   riverpod_lint: 3.1.3

命名规范

类型	规范	示例
文件名	snake_case	user_profile_page.dart
类名	PascalCase	UserProfilePage
变量/方法	camelCase	userName, fetchData()
常量	camelCase	maxRetryCount
私有成员	_ 前缀	_count, _handleClick()
Provider	xxxProvider	userProvider, cartProvider

文件组织规范

• 一个文件一个类（或一组紧密相关的类）
• 文件名与主类名对应：user_profile_page.dart → UserProfilePage
• import 顺序：dart → flutter → package → 相对路径

// 1. Dart 核心库
import 'dart:async';
import 'dart:convert';

// 2. Flutter 框架
import 'package:flutter/material.dart';

// 3. 第三方包
import 'package:provider/provider.dart';
import 'package:dio/dio.dart';

// 4. 项目内文件
import 'package:my_app/models/user.dart';
import 'package:my_app/services/api_service.dart';

---

架构模式参考

简单架构（适合入门）

UI（Widget）→ 直接调用 Service → 网络/存储
                ↑
            setState / Provider

MVVM 架构（适合中型项目）

View（Widget）→ ViewModel（ChangeNotifier / Notifier）→ Model（数据）
                                                    → Service（网络/存储）

Clean Architecture（适合大型项目）

Presentation Layer → Domain Layer → Data Layer
   (UI/ViewModel)     (Use Cases)    (Repository/Service)

建议

• 入门阶段：不需要纠结架构，先写功能
• 项目变大时：逐步引入 Provider 和 Service 层
• 大型项目：考虑 MVVM 或 Clean Architecture
• 不要过度设计——架构是为了解决问题，不是为了展示技术

下一步

• 代码生成与 build_runner — json_serializable / freezed
• 测试 — 单元测试 / Widget 测试