patbond-flutter/doc/project_structure.md

Patbond Flutter 项目结构说明

项目概况

这是一个标准 Flutter 新项目，项目名是 patbond_flutter。目前还没有真正的业务代码，只有 Flutter 模板生成的计数器 Demo。

核心信息：

• 入口文件：lib/main.dart
• 依赖配置：pubspec.yaml
• 当前依赖很少：只有 Flutter SDK、cupertino_icons、flutter_lints
• 业务结构尚未搭建
• 支持的平台包括：Android、iOS、Web、Linux、macOS、Windows

顶层目录说明

lib/

这是之后主要写代码的地方。

当前只有：

lib/main.dart

里面是 Flutter 默认的计数器 Demo，包括：

• main()：应用启动入口
• MyApp：根组件，创建 MaterialApp
• MyHomePage：默认首页
• _MyHomePageState：计数器状态逻辑

以后项目的大部分页面、组件、状态管理、接口请求、业务逻辑都会放在 lib/ 下面。

pubspec.yaml

Flutter 项目的核心配置文件。

它负责：

• 项目名称
• Dart SDK 版本
• 第三方依赖
• 图片、字体等资源声明
• Flutter 配置

以后添加依赖会改这里，比如：

dependencies:
  dio: ^x.x.x
  go_router: ^x.x.x
  flutter_riverpod: ^x.x.x

如果要添加图片资源，也会在这里配置：

flutter:
  assets:
    - assets/images/

pubspec.lock

依赖锁定文件。

它记录当前项目实际安装的依赖版本。一般不要手动改，由 flutter pub get 自动生成和更新。

analysis_options.yaml

Dart / Flutter 代码检查规则配置。

当前使用的是：

include: package:flutter_lints/flutter.yaml

也就是 Flutter 推荐的默认 lint 规则。

以后如果团队有代码规范，可以在这里加规则，比如是否强制单引号、是否允许 print 等。

test/

测试目录。

当前只有：

test/widget_test.dart

这是 Flutter 默认生成的计数器测试，用来测试点击按钮后数字是否增加。

当删掉默认计数器页面后，这个测试大概率也要同步修改或删除，否则测试会失败。

android/

Android 原生工程目录。

里面是 Android 平台相关配置，例如：

• 包名
• Gradle 配置
• AndroidManifest
• 权限
• 启动图标
• 原生插件注册

平时写 Flutter UI 不需要经常碰它。

什么时候会改：

• 修改 Android 应用包名
• 添加相机、定位、蓝牙等权限
• 配置 Firebase、推送、地图 SDK
• 修改 Android 启动页、图标、签名

ios/

iOS 原生工程目录。

里面是 Xcode 工程配置，例如：

• Runner.xcworkspace
• Info.plist
• iOS 权限
• Bundle ID
• iOS 插件配置

什么时候会改：

• 修改 iOS Bundle ID
• 添加相机、相册、定位等权限描述
• 配置推送、登录、支付、地图
• 修改 iOS 启动页、图标、签名

web/

Flutter Web 平台目录。

主要文件：

• index.html
• manifest.json
• favicon.png
• icons/

如果要把项目跑成 Web 应用，会用到这里。

什么时候会改：

• 改网页标题
• 改 favicon
• 配置 PWA
• 添加 Web 端脚本
• 配置第三方 Web SDK

linux/、macos/、windows/

桌面端平台目录。

如果项目只做移动端，这几个目录通常不用管。

它们的作用类似 android/ 和 ios/，只是对应桌面端平台。

build/

构建产物目录。

由 Flutter 自动生成。

不要手动改，也不应该提交重要业务代码到这里。

.dart_tool/

Dart / Flutter 工具生成的缓存目录。

不要手动改。

.idea/、patbond_flutter.iml

JetBrains / Android Studio / IntelliJ 的 IDE 配置文件。

通常不写业务逻辑。

.metadata

Flutter 项目元信息。

一般不需要手动改。

README.md

项目说明文档。

现在大概率还是模板内容。以后可以写：

• 项目介绍
• 如何运行
• 环境要求
• 常用命令
• 目录结构
• 开发规范

应该从哪里开始写

第一步应该从 lib/ 开始，不要先改平台目录。

当前项目还处于默认模板阶段，建议先把 lib/ 组织起来。

推荐的最小起步结构：

lib/
  main.dart
  app/
    app.dart
    router.dart
    theme.dart
  features/
    home/
      home_page.dart
  shared/
    widgets/
    constants/
    utils/

含义：

main.dart

只保留启动逻辑，例如：

void main() {
  runApp(const App());
}

app/app.dart

放全局 MaterialApp，例如主题、路由、全局配置。

app/router.dart

如果项目有多个页面，路由放这里。

前期简单项目可以先不用路由库，直接用 Flutter 自带 Navigator。如果页面比较多，可以考虑 go_router。

app/theme.dart

统一管理颜色、字体、按钮样式等主题配置。

features/

按功能模块放业务代码。

例如：

features/
  home/
  auth/
  profile/
  bond/
  settings/

每个功能模块下面可以继续放：

pages/
widgets/
models/
services/

但一开始不要拆太细，避免目录很多但没内容。

shared/

放跨多个功能复用的东西，例如：

• 通用组件
• 常量
• 工具函数
• 通用样式
• 网络层
• 本地存储封装

实际开发顺序建议

1. 先确定产品的第一个页面，例如首页、登录页、仪表盘、列表页。然后把默认计数器 Demo 替换掉。
2. 清理 lib/main.dart，不要继续在 main.dart 里堆所有页面。可以把根 App 和首页拆出去。
3. 建立最小目录结构，建议先建 lib/app/app.dart 和 lib/features/home/home_page.dart，先不要一口气创建很多空目录。
4. 确定状态管理方案。如果只是简单页面，先用 StatefulWidget；如果会有登录状态、接口数据、多个页面共享状态，建议尽早选一个方案，例如 riverpod、provider、bloc。
5. 确定路由方案。页面少可以先用 Navigator.push；页面多、需要登录拦截、深链接，建议用 go_router。
6. 添加资源目录。如果要放图片、图标、字体，可以加 assets/images/、assets/icons/、assets/fonts/，然后在 pubspec.yaml 注册。
7. 再处理 Android / iOS 配置。只有当需要权限、包名、签名、推送、第三方 SDK 时，才去改 android/ 和 ios/。

当前这个项目最重要的文件

现在最应该关注这几个：

lib/main.dart
pubspec.yaml
analysis_options.yaml
test/widget_test.dart

其中真正开始写业务，入口是：

lib/main.dart

但不建议长期把所有代码写在 main.dart 里。

建议的下一步

如果准备正式开始项目，建议先做这件事：

把默认计数器 Demo 改成干净的应用骨架：

lib/
  main.dart
  app/
    app.dart
    theme.dart
  features/
    home/
      home_page.dart

然后首页先写一个简单的 HomePage，后续所有功能都从 features/ 下面扩展。

这个项目还很干净，最适合先把结构搭好，再开始写业务页面。