claude-skills 项目实战Flutter Feature-Based 工程结构完整指南目录分层、pubspec 依赖与入口初始化【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills本指南以 claude-skills 开源仓库中 flutter-expert 技能 的project-structure参考文档为核心系统讲解一套可直接落地的 Flutter 3 Dart 项目工程化方案从lib/的 feature-based 分层目录、pubspec.yaml依赖清单到main.dart与app.dart的入口初始化与路由装配。读完本文你将能够独立搭建一个职责清晰、易于扩展、便于测试的中大型 Flutter 应用骨架并理解每一条约定背后的源码级依据。一、为什么需要 Feature-Based 项目结构在 project-structure.md 中官方技能文档给出了一个核心判断项目结构应当按业务功能feature组织而非按技术类型type组织。传统做法把所有 screens、widgets、models 各自堆进一个大目录当功能模块增多时查找成本、依赖耦合与合并冲突会指数级上升而 feature-based 结构把某个功能涉及的所有代码收敛在同一个子目录内具备三个直接收益内聚性auth功能的数据层、领域层、UI 层彼此相邻改动一个功能只触碰一个目录可迁移性整个功能目录可以独立复制、删除或模块化拆分后续可平滑演进为 package / melos monorepo可测试性domain 层不依赖 Flutter UI配合 test-master 技能 描述的分层测试策略可以做到单测、widget 测试、集成测试各归其位。需要说明的是该参考文档定位是「架构骨架」——它定义了目录约定与入口代码而具体的状态管理选型Riverpod / Bloc与路由配置GoRouter则由技能中另外两份参考文档承担。本文在讲解结构时会自然衔接这些内容让整套结构真正可运行。二、lib/ 完整目录骨架逐层拆解文档给出了如下的目录树这是整篇指南的骨架我们逐层展开说明其职责lib/ ├── main.dart ├── app.dart ├── core/ │ ├── constants/ │ │ ├── colors.dart │ │ └── strings.dart │ ├── theme/ │ │ ├── app_theme.dart │ │ └── text_styles.dart │ ├── utils/ │ │ ├── extensions.dart │ │ └── validators.dart │ └── errors/ │ └── failures.dart ├── features/ │ ├── auth/ │ │ ├── data/ │ │ │ ├── repositories/ │ │ │ └── datasources/ │ │ ├── domain/ │ │ │ ├── entities/ │ │ │ └── usecases/ │ │ ├── presentation/ │ │ │ ├── screens/ │ │ │ └── widgets/ │ │ └── providers/ │ │ └── auth_provider.dart │ └── home/ │ ├── data/ │ ├── domain/ │ ├── presentation/ │ └── providers/ ├── shared/ │ ├── widgets/ │ │ ├── buttons/ │ │ ├── inputs/ │ │ └── cards/ │ ├── services/ │ │ ├── api_service.dart │ │ └── storage_service.dart │ └── models/ │ └── user.dart └── routes/ └── app_router.dart1. core/ —— 与业务无关的全局基础设施core/存放不依赖任何具体业务功能的通用代码是整个应用的「地基」constants/全局常量colors.dart定义色板strings.dart定义文案与本地化字符串避免魔法数字与魔法字符串散落各处theme/app_theme.dart定义ThemeData对应入口中AppTheme.light/AppTheme.dark两个主题text_styles.dart统一文本样式utils/extensions.dart存放 Dart 扩展方法如String判空、BuildContext便捷读取validators.dart集中表单校验逻辑errors/failures.dart定义统一的错误类型如Failure基类及各类子类供 domain 层使用让错误处理在跨功能间保持一致。从软件分层角度看core/不应反向依赖features/这是保证该目录可复用、可单独测试的前提。2. features/ —— 业务功能模块每个业务功能在features/下拥有独立子目录采用「数据层 / 领域层 / 表现层 / 状态层」四层结构。以auth为例目录职责典型内容data/API 调用、本地存储、DTO 映射repositories/仓库实现、datasources/远程/本地数据源domain/纯业务逻辑不依赖 Flutterentities/领域实体、usecases/用例如LoginUseCasepresentation/UI 层screens/页面、widgets/页面内私有组件providers/该功能专属的 Riverpod Providerauth_provider.dart等状态声明注意 domain 层的纯净性domain/只包含纯 Dart 类不 import 任何 Flutter UI 库。这意味着一方面它可以被flutter test以纯单测方式覆盖另一方面它天然具备跨平台复用能力——这与技能中 riverpod-state.md 强调的「UI 与逻辑分离」原则完全一致。data/层则通过 repository 接口定义在 domain与 domain 层解耦实现依赖倒置。3. shared/ —— 跨功能共享组件shared/与core/的区别在于shared/存放与 UI 相关的跨功能复用件而core/存放纯逻辑基础设施。widgets/通用 UI 组件库按buttons/按钮、inputs/输入框、cards/卡片分子目录管理遵循 widget-patterns.md 的组件设计约定const 构造器、key 使用等services/api_service.dart统一的 HTTP 客户端封装、storage_service.dart本地持久化封装可基于 Hive / SharedPreferencesmodels/跨功能共享的数据模型如user.dart。注意与各 feature 内的 entity 区分——后者属于特定业务领域。4. routes/ —— 集中式路由routes/app_router.dart集中维护全应用路由。文档在入口代码中通过routerProvider提供 GoRouter 实例其声明可参考 gorouter-navigation.md 的标准写法例如final goRouter GoRouter( initialLocation: /, redirect: (context, state) { /* 认证守卫逻辑 */ }, routes: [ GoRoute(path: /, builder: (context, state) const HomeScreen()), GoRoute( path: /auth/login, builder: (context, state) const LoginScreen(), ), ], );路由集中在routes/目录后嵌套路由routes:子路由、ShellRoute 持久化 UI、query/path 参数的处理都能在同一处查证避免了路由声明散落在各页面文件中的问题。三、pubspec.yaml 依赖清单为什么选这些包project-structure.md 给出了一个经过实际挑选的依赖清单每一项都对应上文结构中的一个具体职责dependencies: flutter: sdk: flutter # State Management flutter_riverpod: ^2.5.0 riverpod_annotation: ^2.3.0 # Navigation go_router: ^14.0.0 # Networking dio: ^5.4.0 # Code Generation freezed_annotation: ^2.4.0 json_annotation: ^4.8.0 # Storage shared_preferences: ^2.2.0 hive_flutter: ^1.1.0 dev_dependencies: flutter_test: sdk: flutter build_runner: ^2.4.0 riverpod_generator: ^2.4.0 freezed: ^2.5.0 json_serializable: ^6.8.0 flutter_lints: ^4.0.0逐项解读各包与目录结构的对应关系包版本文档给出作用对应结构/文档flutter_riverpod^2.5.0状态管理运行时features/*/providers/详见 riverpod-state.mdriverpod_annotation^2.3.0Riverpod 代码生成注解配合riverpod声明 Notifiergo_router^14.0.0声明式路由routes/app_router.dart详见 gorouter-navigation.mddio^5.4.0网络请求shared/services/api_service.dartfreezed_annotation^2.4.0不可变模型代码生成data/层 DTO 与domain/entities/json_annotation^4.8.0JSON 序列化注解data/层模型shared_preferences^2.2.0轻量 KV 存储shared/services/storage_service.darthive_flutter^1.1.0高性能本地数据库入口处Hive.initFlutter()的初始化对象build_runner^2.4.0代码生成执行器运行dart run build_runner buildriverpod_generator^2.4.0生成 Riverpod Provider配合riverpod_annotationfreezed^2.5.0生成不可变类实现配合freezed_annotationjson_serializable^6.8.0生成fromJson/toJson配合json_annotationflutter_lints^4.0.0官方 lint 规则集保证flutter analyze零警告这个组合的两个特征值得注意「注解 build_runner」的代码生成模式freezed、json_serializable、riverpod_generator配合build_runner把不可变模型、JSON 映射、Provider 声明这三类样板代码在编译期生成。这解释了为何 dev_dependencies 中会同时出现注解包freezed_annotation、json_annotation、riverpod_annotation与生成器包freezed、json_serializable、riverpod_generator、build_runner——前者是运行时依赖后者是构建期工具。存储双轨shared_preferences适合存放用户偏好、token 等小型 KV 数据hive_flutter适合结构化、大数据量场景。入口代码中只初始化了 Hiveawait Hive.initFlutter()说明 SharedPreferences 可以在使用时按需初始化不需要阻塞应用启动。四、Main 入口与 App 装配初始化顺序与路由挂载文档给出了两个入口文件的完整示例它们分工明确main.dart负责「环境初始化」app.dart负责「根组件装配」。main.dart异步初始化必须显式调用 ensureInitialized// main.dart void main() async { WidgetsFlutterBinding.ensureInitialized(); await Hive.initFlutter(); runApp(const ProviderScope(child: MyApp())); }三点关键细节WidgetsFlutterBinding.ensureInitialized()在main()中任何await之前调用。因为一旦使用异步async在await之后的代码就已经离开了 Flutter 引擎默认建立的runApp前的同步阶段必须显式确保 Widgets 绑定初始化完成否则访问平台通道如 Hive 的本地文件系统、SharedPreferences 的插件通道会抛出异常。await Hive.initFlutter()对应当前结构选择在启动阶段完成本地数据库初始化。若你的功能清单不依赖 Hive这一行可安全移除——这正是结构文档将存储抽象进storage_service.dart的意义初始化方式与调用方解耦。ProviderScope包裹根组件这是 Riverpod 的使用前提所有 Provider 都必须在ProviderScope作用域内才能被ref.watch/ref.read。放在这里意味着全局生效。app.dartConsumerWidget MaterialApp.router// app.dart class MyApp extends ConsumerWidget { const MyApp({super.key}); override Widget build(BuildContext context, WidgetRef ref) { final router ref.watch(routerProvider); return MaterialApp.router( routerConfig: router, theme: AppTheme.light, darkTheme: AppTheme.dark, themeMode: ThemeMode.system, ); } }这处实现集中体现了技能文档的多条铁律根组件用ConsumerWidget而非StatefulWidget这与 SKILL.md 中「UseConsumer/ConsumerWidgetfor state (notStatefulWidget)」的约束一一对应。MyApp自身无内部可变状态用ConsumerWidget即可在持有ref的同时避免不必要的 State 生命周期开销。ref.watch(routerProvider)而非ref.read当路由配置如认证状态导致的 redirect 结果作为 Provider 暴露时watch保证路由变化能触发根组件重建。若路由完全静态改用ref.read也不会出错——但保持watch为后续动态路由如登录态切换跳转留出余地。MaterialApp.routerrouterConfig将 GoRouter 实例交给 MaterialApp替代传统routes/onGenerateRoute。此时路由的添加、深链deep link、redirect 全部由routes/app_router.dart统一管理与 gorouter-navigation.md 的GoRouter配置模式完全匹配。ThemeMode.system跟随系统亮/暗模式配合theme与darkTheme两套AppTheme对应core/theme/app_theme.dart中亮暗主题的定义。五、四层职责速查表与技能工作流中的落地位置project-structure.md 用一张表明确了 feature 内部各层的边界LayerResponsibilitydata/API calls, local storage, DTOsdomain/Business logic, entities, use casespresentation/UI screens, widgetsproviders/Riverpod providers for feature把它放回技能 SKILL.md 定义的 Core Workflow 中看这套结构与既有开发流程是咬合的Setup阶段按本结构脚手架项目、写入 pubspec 依赖、配置routes/app_router.dartState阶段在features/*/providers/定义 Riverpod provider或 Bloc随后flutter analyze验证——core/、domain/的纯净分层正是为了让静态分析快速定位跨层污染Widgets阶段在presentation/与shared/widgets/构建 const 优化组件Test阶段domain 层纯单测 presentation 层 widget 测试目录边界天然划分了测试文件的组织范围Optimize阶段flutter run --profile DevTools 分析routes/与providers/的集中化便于定位重建热点。六、落地时的扩展建议与注意事项基于上述结构给出几条可操作的落地建议先在lib/下建立core/、shared/与首个features/功能再逐步迁移存量代码避免一次性大规模重构遵循 domain 层零 Flutter 依赖的原则domain/entities/与domain/usecases/只 import 纯 Dart 与dart:库这是后续模块化拆分与单元测试的基础每次新增依赖都先在 pubspec 中显式声明再flutter pub get若引入代码生成相关包运行dart run build_runner build --delete-conflicting-outputs生成对应文件并让生成的.g.dart/.freezed.dart进入版本控制或配置好.gitignore策略将路由守卫redirect集中在routes/app_router.dart不要让认证判断散落在各页面initState中多目标平台Web / 桌面 / 移动差异代码可参考技能库中 platform-handling 之外的平台实践但本文所述结构本身对平台无感可放心作为通用骨架。七、结语把结构文档变成团队的工程公约本文完整还原了 claude-skills 项目中 flutter-expert 技能 的project-structure参考文档从lib/的 feature-based 四层目录、core/与shared/的职责划分到pubspec.yaml依赖选型再到main.dart/app.dart的入口装配每一层都能在技能文档与参考文件中找到对应的实现依据。把这份结构固化为团队模板后新功能开发的路径会变得高度可预期建目录 → 定义 domain 实体与用例 → 实现 data 仓库 → 声明 providers → 编写 presentation 页面 → 注册路由 → 补测试。这套骨架不追求大而全的框架约束而是用「目录即文档」的方式让架构意图直接可见这也是它作为专家技能参考材料被沉淀进仓库的原因。【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考