Flutter 快速搭建新项目：用 Flutter Foundation Kit 一条命令生成带基础架构的 App 模板

Flutter 快速搭建新项目：用 Flutter Foundation Kit 一条命令生成带基础架构的 App 模板

在 Flutter 项目开发中，真正耗时间的往往不是第一个页面，而是项目刚开始时那一堆基础设施：

• 目录结构怎么拆？
• 路由放哪里？
• 依赖注入怎么接？
• 网络层怎么封装？
• 登录态、用户信息、Settings 配置怎么管理？
• 日志、本地存储、通用工具类要不要重新写一遍？

如果每个新项目都从零搭这些内容，成本会很高，而且不同项目之间的结构也容易不统一。

Flutter Foundation Kit 这个项目就是为了解决这个问题：它既提供一个可复用的 Flutter 基础库，也提供一个已经搭好基础架构的模板工程。新项目可以通过一条命令生成，不再是空 Flutter 工程，而是一个可以直接进入业务开发的项目骨架。

项目地址

GitHub 地址：

zh_flutter_foundation_kit GitHub 仓库

Foundation Kit package 信息：

name: flutter_foundation_kit
version: 0.0.3
repository: https://github.com/911hzh/zh_flutter_foundation_kit

说明：当前项目文档和 pubspec.yaml 中确认的包名是 flutter_foundation_kit，仓库地址为上面的 GitHub 地址。公开 pub.dev 页面我暂未检索到，因此这里优先附 GitHub 仓库地址作为当前可确认的包地址。

它主要解决什么问题？

这个项目主要解决 Flutter 新项目的基础能力复用问题。

很多 App 在业务不同的情况下，底层结构其实非常相似，例如：

• 网络请求基础封装
• 日志能力
• 环境配置 Settings
• 登录态 Store
• 用户信息 Store
• 本地安全存储
• SharedPreferences 偏好设置
• Repository 抽象
• 路由入口
• 依赖注入入口
• 第三方 SDK 接入边界
• 通用工具类

这些能力每个项目都要有，但每次都手动搭一遍会很重复。

flutter_foundation_kit 把这些通用能力沉淀为基础 package，同时通过 example 模板提供一个完整的 App 项目结构。这样新项目启动时，不需要从空白目录开始，可以直接在已有架构上写页面、接口、Store 和业务逻辑。

一条命令生成新项目

在仓库根目录执行：

make create helloworldProject

默认会在上级目录生成一个新 Flutter 项目：

../helloworldProject

生成后进入项目：

cd ../helloworldProject
flutter pub get

如果需要指定 app id 和输出目录，也可以这样写：

make create helloworldProject BUNDLE_ID=com.company.helloworld OUTPUT=../apps

这个命令背后会基于仓库里的 example 模板创建新项目。生成出来的不是空工程，而是已经集成基础架构的 Flutter App。

生成后的项目已经有什么？

生成后的项目已经准备好常用分层结构：

lib/
  module/
    usecase/      页面、Cubit、VM、页面内 Widget
    route/        路由表和全局导航 key
    getIt/        依赖注入入口和注册模块
  base/
    api/          示例网络 API、网络模型、RestClientAdapter
    port/         第三方 SDK 或平台能力的业务抽象
    store/        登录态、用户数据、Settings 等共享状态
  infra/          base/port 的具体实现
  e_uikit/        多页面复用 UI 组件

也就是说，一个新项目刚创建出来时，页面层、网络层、状态层、配置层、依赖注入层、路由层和公共 UI 层都已经有明确位置。

后续开发时，可以按下面的规则放代码：

• 新页面放到 lib/module/usecase
• 新路由注册到 lib/module/route/RouteConfig.dart
• 新依赖注册放到 lib/module/getIt
• 新网络 API 放到 lib/base/api
• 新共享状态放到 lib/base/store
• 第三方 SDK 抽象放到 lib/base/port
• 第三方 SDK 实现放到 lib/infra
• 公共 UI 组件放到 lib/e_uikit

这对团队协作和 AI 辅助开发都比较友好，因为目录边界清晰，后续新增功能时不容易乱放代码。

Foundation Kit 提供了哪些基础能力？

flutter_foundation_kit 本身是一个 Flutter 基础库 package。业务项目推荐统一导入：

import 'package:flutter_foundation_kit/flutter_foundation_kit.dart';

它主要提供下面这些能力。

1. 网络层

项目提供 REST 请求相关抽象和默认实现：

• RestClient
• RestClientImpl
• RestClientAdapter
• NetworkProxy
• RestResponse
• RestRequestError

默认实现基于 Dio，但业务侧可以通过 RestClientAdapter 自定义 baseUrl、公共 headers、请求前处理和错误处理。

示例：

class AppRestClientAdapter extends RestClientAdapter {
  @override
  String getBaseUrl() => 'https://api.example.com';

  @override
  Future<Map<String, String>> getHeaders() async {
    return {'X-App': 'demo'};
  }
}

2. 日志能力

日志部分提供统一协议和默认实现：

• LoggerProtocol
• LoggerFactory
• LoggerConfiguration
• DefaultLoggerImpl
• LoggerTagImpl

业务代码可以依赖日志协议，而不是直接绑定具体第三方 logger 包。后续如果要替换日志实现，也会更容易。

3. Settings 配置能力

项目提供 Settings 抽象和加载流程：

• SettingsBase
• SettingsLoader
• AppEnvironment

可以用于区分 development、production、test 等环境，并从不同 asset 配置文件加载应用配置。

4. Store 状态容器

基础库提供轻量 Store 抽象：

• StoreBase
• AuthStore
• UserStore

StoreBase 基于 ValueNotifier，适合承载登录态、用户信息、配置等共享状态。模板项目里也已经提供了登录态和用户状态的示例实现。

5. 本地存储

项目提供安全存储和偏好设置端口：

• Repository
• KeychainPort
• PreferenceRepositoryPort
• KeyChainImpl
• PreferenceRepositoryImpl

其中 KeyChainImpl 基于 flutter_keychain，适合保存 token 等敏感数据；PreferenceRepositoryImpl 基于 shared_preferences，适合保存普通偏好设置。

6. 通用工具类

基础库还包含一些常用工具：

• JsonUtil
• Lazyload
• Polling
• Codable
• MetaError
• LocalizedError
• BuildContextExtension
• ListExtention
• Generator

这些工具可以减少项目中重复写 JSON 编解码、异步懒加载、轮询、错误模型等代码的成本。

这个项目的技术点

从项目结构看，Flutter Foundation Kit 的核心技术点可以概括为一句话：

把 Flutter 新项目最容易重复搭建的基础设施，提前沉淀成可复用 package + 可生成模板。

下面这几个点，是这个项目比较值得关注的地方。

1. Package Core 和 App Template 分离

核心思想：基础能力归基础库，业务结构归模板项目。

flutter_foundation_kit 的 lib/ 目录只放可复用基础能力，不放具体业务页面、路由表或 App 专属依赖注入。

业务项目结构放在 example 模板中，通过 make create <ProjectName> 复制生成。

这样做的好处是：

• 基础能力可以被多个项目复用
• 模板项目可以承载推荐目录结构
• package core 不会被具体业务污染
• 新项目可以快速生成并继续开发

2. Port / Infra 分层

核心思想：业务层依赖抽象，不直接绑定第三方 SDK。

模板项目推荐把第三方 SDK 或平台能力拆成两层：

lib/base/port/<ability>/      定义业务侧接口
lib/infra/<ability>/          实现接口并调用具体 SDK

页面和 Cubit 不直接依赖具体 SDK，而是依赖业务抽象。

这样后续做这些事情会更简单：

• 替换第三方 SDK
• 编写 mock 测试
• 做多环境切换
• 将平台能力和业务代码解耦

这也是模板项目里非常重要的工程化边界。

3. GetIt 依赖注入

核心思想：对象创建和依赖注册集中管理。

模板项目已经集成 GetIt + injectable，并提供依赖初始化入口：

lib/module/getIt/Injection.dart
lib/module/getIt/Injection.config.dart
lib/module/getIt/RegisterModule.dart
lib/module/getIt/GetItInstanceName.dart

新增 Store、Repository、网络客户端、第三方 SDK adapter 时，可以统一在这里注册。

这样业务页面不需要关心对象怎么创建，只需要使用已经注册好的依赖。

4. 路由入口统一

核心思想：页面跳转有统一入口，避免路由散落在各处。

模板项目提供：

lib/module/route/RouteConfig.dart
lib/module/route/GlobalNavigatorKey.dart

新增页面后，可以统一注册路由；需要全局导航时，也有统一入口。

对于中大型 Flutter 项目来说，路由统一管理可以明显降低后期维护成本。

5. AI 友好的项目结构

核心思想：让人和 AI 都能快速理解项目边界。

项目文档中明确提到，它提供 README.md、architecture.md、ai.md 等说明，方便 AI Agent 快速理解框架目的和边界。

这点对于现在的开发方式很实用。目录清晰、边界明确、文档完备，AI 辅助写代码时更容易知道代码应该放在哪里，也能减少错误修改 package core 或业务模板的概率。

使用这个项目的优势

总结下来，使用这个项目的优势主要有下面几个。

1. 快速启动新 Flutter 项目

通过：

make create helloworldProject

就可以得到一个带基础架构的项目，而不是空白 Flutter 工程。

2. 减少重复搭建成本

网络、日志、Settings、Store、本地存储、Repository、工具类等基础能力已经沉淀到基础库中，不需要每个项目重新写一遍。

3. 目录结构清晰

页面、路由、依赖注入、网络、Store、第三方 SDK 抽象、基础设施实现、公共 UI 都有明确目录，适合团队协作。

4. 便于扩展和替换

项目通过 抽象协议、Port/Infra、Adapter 等方式降低业务代码和具体插件的耦合。

默认实现可以直接用；不满足业务时，也可以替换成自己的实现。

5. 适合持续演进

基础库和模板项目分离，通用能力放 package core，业务模板放 example。后续可以逐步扩展网络、日志、存储、配置、模板页面等能力。

一句话总结：它不是单纯的工具类集合，而是一套可复用、可生成、可扩展的 Flutter 新项目基础模板。

适合哪些场景？

这个项目适合下面几类场景：

• 新建 Flutter App，希望快速拥有基础架构
• 团队内部多个 Flutter 项目希望统一目录规范
• 想减少网络、日志、配置、Store、本地存储等重复代码
• 希望让 AI Agent 更容易理解项目结构并辅助开发
• 想基于一个模板持续沉淀团队 Flutter 工程实践

如果你已有 Flutter 项目，也可以只接入 flutter_foundation_kit 基础库；如果你准备新建项目，则可以直接使用 example 模板生成完整项目。

后续如何扩展？

如果你对这个库感兴趣，可以通过 GitHub PR 的方式参与扩展。

可以扩展的方向包括：

• 通用工具类：补充更多可复用工具能力
• 网络层能力：完善请求、响应、错误处理和调试能力
• Store 示例：增加更多状态管理使用示例
• Settings 配置：扩展更多环境配置加载场景
• Port / Infra 示例：增加更多第三方 SDK 接入示例
• 模板项目：优化目录结构、示例页面和生成体验
• 测试与文档：补充测试用例、快速上手说明和架构说明
• 发布维护：推进 package 发布和版本维护

这个项目目前的定位很清晰：

让 Flutter 新项目不再从零搭基础设施，而是在一个稳定、清晰、可扩展的基础上开始业务开发。

如果你也经常创建 Flutter 项目，或者正在维护团队内部 Flutter 工程模板，可以关注这个项目：

zh_flutter_foundation_kit GitHub 仓库

---