.flu-cli.json 完整配置指南

.flu-cli.json 是 Flu CLI 的核心配置文件，用于自定义代码生成规则。通过配置文件，你可以让扩展完美适配你的项目结构。

配置文件位置

配置文件应放在项目根目录：

my_app/
├── lib/
├── pubspec.yaml
└── .flu-cli.json    # 配置文件

初始化配置文件

方式 1：右键菜单（推荐）

在项目根目录右键
选择 Flu: 初始化项目
自动生成 .flu-cli.json

方式 2：命令面板

打开命令面板（Cmd+Shift+P / Ctrl+Shift+P）
输入 Flu: Init
自动生成配置文件

方式 3：手动创建

在项目根目录创建 .flu-cli.json 文件，复制以下内容：

json

{
    "generators": {
        "page": {
            "path": "lib/pages",
            "defaultType": "stateful",
            "withViewModel": true,
            "withBasePage": false
        },
        "viewModel": {
            "path": "lib/viewmodels",
            "withBaseViewModel": false
        },
        "widget": {
            "path": "lib/widgets",
            "defaultType": "stateless"
        },
        "model": {
            "path": "lib/models"
        }
    }
}

配置结构

顶层结构

json

{
  "generators": {
    "page": { ... },
    "viewModel": { ... },
    "widget": { ... },
    "component": { ... },
    "model": { ... },
    "service": { ... },
    "module": { ... }
  }
}

generators

generators 对象包含所有生成器的配置，每个生成器对应一种文件类型。

各生成器详细配置

Page 生成器

完整配置

json

{
    "generators": {
        "page": {
            "path": "lib/pages",
            "defaultType": "stateful",
            "withViewModel": true,
            "withBasePage": false,
            "basePageClass": "BasePage",
            "basePageImport": "package:my_app/core/base/base_page.dart",
            "fileSuffix": "_page"
        }
    }
}

配置项说明

配置项	类型	默认值	说明
`path`	string	`"lib/pages"`	页面生成路径
`defaultType`	string	`"stateful"`	默认页面类型：`stateful` 或 `stateless`
`withViewModel`	boolean	`true`	是否自动生成 ViewModel
`withBasePage`	boolean	`false`	是否继承 BasePage
`basePageClass`	string	`"BasePage"`	BasePage 类名
`basePageImport`	string	-	BasePage 导入路径
`fileSuffix`	string	`"_page"`	文件后缀

使用示例

示例 1：基础配置

json

{
    "generators": {
        "page": {
            "path": "lib/pages",
            "defaultType": "stateful",
            "withViewModel": true
        }
    }
}

生成 home 页面：

lib/pages/
└── home_page.dart

lib/viewmodels/
└── home_viewmodel.dart

示例 2：使用 BasePage

json

{
    "generators": {
        "page": {
            "path": "lib/pages",
            "withBasePage": true,
            "basePageClass": "BasePage",
            "basePageImport": "package:my_app/core/base/base_page.dart"
        }
    }
}

生成的代码：

dart

import 'package:flutter/material.dart';
import 'package:my_app/core/base/base_page.dart';

class HomePage extends BasePage {
  const HomePage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Home')),
      body: Container(),
    );
  }
}

示例 3：模块化路径

json

{
    "generators": {
        "page": {
            "path": "lib/features/{feature}/pages"
        }
    }
}

在 lib/features/user/pages 生成页面时，{feature} 会自动替换为 user。

ViewModel 生成器

完整配置

json

{
    "generators": {
        "viewModel": {
            "path": "lib/viewmodels",
            "withBaseViewModel": false,
            "baseViewModelClass": "BaseViewModel",
            "baseViewModelImport": "package:my_app/core/base/base_viewmodel.dart",
            "fileSuffix": "_viewmodel"
        }
    }
}

配置项说明

配置项	类型	默认值	说明
`path`	string	`"lib/viewmodels"`	ViewModel 生成路径
`withBaseViewModel`	boolean	`false`	是否继承 BaseViewModel
`baseViewModelClass`	string	`"BaseViewModel"`	BaseViewModel 类名
`baseViewModelImport`	string	-	BaseViewModel 导入路径
`fileSuffix`	string	`"_viewmodel"`	文件后缀

使用示例

示例 1：使用 BaseViewModel

json

{
    "generators": {
        "viewModel": {
            "path": "lib/viewmodels",
            "withBaseViewModel": true,
            "baseViewModelClass": "BaseViewModel",
            "baseViewModelImport": "package:my_app/core/base/base_viewmodel.dart"
        }
    }
}

生成的代码：

dart

import 'package:my_app/core/base/base_viewmodel.dart';

class HomeViewModel extends BaseViewModel {
  @override
  Future<void> init() async {
    // TODO: 初始化逻辑
  }

  Future<void> loadData() async {
    setLoading(true);
    try {
      // TODO: 加载数据
    } catch (e) {
      handleError(e);
    } finally {
      setLoading(false);
    }
  }
}

完整配置

json

{
    "generators": {
        "widget": {
            "path": "lib/widgets",
            "defaultType": "stateless",
            "fileSuffix": ""
        }
    }
}

配置项说明

配置项	类型	默认值	说明
`path`	string	`"lib/widgets"`	Widget 生成路径
`defaultType`	string	`"stateless"`	默认类型：`stateful` 或 `stateless`
`fileSuffix`	string	`""`	文件后缀（通常为空）

Component 生成器

完整配置

json

{
    "generators": {
        "component": {
            "path": "lib/components",
            "defaultType": "stateless",
            "fileSuffix": ""
        }
    }
}

配置项与 Widget 生成器相同。

Model 生成器

完整配置

json

{
    "generators": {
        "model": {
            "path": "lib/models",
            "fileSuffix": "_model"
        }
    }
}

配置项说明

配置项	类型	默认值	说明
`path`	string	`"lib/models"`	Model 生成路径
`fileSuffix`	string	`"_model"`	文件后缀

Service 生成器

完整配置

json

{
    "generators": {
        "service": {
            "path": "lib/services",
            "fileSuffix": "_service"
        }
    }
}

配置项说明

配置项	类型	默认值	说明
`path`	string	`"lib/services"`	Service 生成路径
`fileSuffix`	string	`"_service"`	文件后缀

Module 生成器

完整配置

json

{
    "generators": {
        "module": {
            "path": "lib/features/{feature}",
            "structure": [
                "pages",
                "viewmodels",
                "widgets",
                "services",
                "models"
            ]
        }
    }
}

配置项说明

配置项	类型	默认值	说明
`path`	string	`"lib/features/{feature}"`	Module 生成路径
`structure`	array	见上	模块目录结构

占位符

配置中支持以下占位符：

表示功能模块名称，会根据生成位置自动推断。

示例：

配置：

json

{
    "generators": {
        "page": {
            "path": "lib/features/{feature}/pages"
        },
        "viewModel": {
            "path": "lib/features/{feature}/viewmodels"
        }
    }
}

在 lib/features/user/pages 生成页面时：

{feature} = user
Page 路径：lib/features/user/pages/xxx_page.dart
ViewModel 路径：lib/features/user/viewmodels/xxx_viewmodel.dart

完整配置示例

示例 1：Lite 项目

json

{
    "generators": {
        "page": {
            "path": "lib/pages",
            "defaultType": "stateful",
            "withViewModel": true
        },
        "viewModel": {
            "path": "lib/viewmodels"
        },
        "widget": {
            "path": "lib/widgets",
            "defaultType": "stateless"
        },
        "model": {
            "path": "lib/models"
        },
        "service": {
            "path": "lib/services"
        }
    }
}

示例 2：Modular 项目

json

{
    "generators": {
        "page": {
            "path": "lib/features/{feature}/pages",
            "defaultType": "stateful",
            "withViewModel": true,
            "withBasePage": true,
            "basePageClass": "BasePage",
            "basePageImport": "package:my_app/core/base/base_page.dart"
        },
        "viewModel": {
            "path": "lib/features/{feature}/viewmodels",
            "withBaseViewModel": true,
            "baseViewModelClass": "BaseViewModel",
            "baseViewModelImport": "package:my_app/core/base/base_viewmodel.dart"
        },
        "widget": {
            "path": "lib/features/{feature}/widgets",
            "defaultType": "stateless"
        },
        "model": {
            "path": "lib/features/{feature}/models"
        },
        "service": {
            "path": "lib/features/{feature}/services"
        },
        "module": {
            "path": "lib/features/{feature}",
            "structure": [
                "pages",
                "viewmodels",
                "widgets",
                "services",
                "models"
            ]
        }
    }
}

示例 3：Clean Architecture 项目

json

{
    "generators": {
        "page": {
            "path": "lib/features/{feature}/presentation/pages",
            "defaultType": "stateful",
            "withViewModel": true
        },
        "viewModel": {
            "path": "lib/features/{feature}/presentation/viewmodels",
            "withBaseViewModel": true,
            "baseViewModelClass": "BaseViewModel",
            "baseViewModelImport": "package:my_app/core/base/base_viewmodel.dart"
        },
        "widget": {
            "path": "lib/features/{feature}/presentation/widgets",
            "defaultType": "stateless"
        },
        "model": {
            "path": "lib/features/{feature}/data/models"
        },
        "service": {
            "path": "lib/features/{feature}/data/datasources"
        },
        "module": {
            "path": "lib/features/{feature}",
            "structure": [
                "domain/entities",
                "domain/repositories",
                "domain/usecases",
                "data/models",
                "data/datasources",
                "data/repositories",
                "presentation/pages",
                "presentation/viewmodels",
                "presentation/widgets"
            ]
        }
    }
}

配置验证

扩展会自动验证配置文件：

有效配置

json

{
    "generators": {
        "page": {
            "path": "lib/pages"
        }
    }
}

无效配置

json

{
    "generators": {
        "page": {
            "path": 123 // 错误：path 必须是字符串
        }
    }
}

如果配置无效，扩展会：

显示错误提示
使用默认配置
在输出面板显示详细错误信息

常见问题

配置不生效？

确认配置文件在项目根目录
检查 JSON 格式是否正确
重新加载 VSCode 窗口

如何重置配置？

删除 .flu-cli.json 文件，重新初始化。

多个项目如何共享配置？

创建配置模板文件
复制到每个项目
根据项目调整

配置文件应该提交到 Git 吗？

推荐提交，这样团队成员可以使用统一的配置。

在 .gitignore 中不要忽略 .flu-cli.json。

.flu-cli.json 完整配置指南 ​

目录 ​

配置文件位置 ​

初始化配置文件 ​

方式 1：右键菜单（推荐） ​

方式 2：命令面板 ​

方式 3：手动创建 ​

配置结构 ​

顶层结构 ​

generators ​

各生成器详细配置 ​

Page 生成器 ​

完整配置 ​

配置项说明 ​

使用示例 ​

示例 1：基础配置 ​

示例 2：使用 BasePage ​

示例 3：模块化路径 ​

ViewModel 生成器 ​

完整配置 ​

配置项说明 ​

使用示例 ​

示例 1：使用 BaseViewModel ​

Widget 生成器 ​

完整配置 ​

配置项说明 ​

Component 生成器 ​

完整配置 ​

Model 生成器 ​

完整配置 ​

配置项说明 ​

Service 生成器 ​

完整配置 ​

配置项说明 ​

Module 生成器 ​

完整配置 ​

配置项说明 ​

占位符 ​

​

完整配置示例 ​

示例 1：Lite 项目 ​

示例 2：Modular 项目 ​

示例 3：Clean Architecture 项目 ​

配置验证 ​

有效配置 ​

无效配置 ​

常见问题 ​

配置不生效？ ​

如何重置配置？ ​

多个项目如何共享配置？ ​

配置文件应该提交到 Git 吗？ ​

.flu-cli.json 完整配置指南

目录

配置文件位置

初始化配置文件

方式 1：右键菜单（推荐）

方式 2：命令面板

方式 3：手动创建

配置结构

顶层结构

generators

各生成器详细配置

Page 生成器

完整配置

配置项说明

使用示例

示例 1：基础配置

示例 2：使用 BasePage

示例 3：模块化路径

ViewModel 生成器

完整配置

配置项说明

使用示例

示例 1：使用 BaseViewModel

Widget 生成器

完整配置

配置项说明

Component 生成器

完整配置

Model 生成器

完整配置

配置项说明

Service 生成器

完整配置

配置项说明

Module 生成器

完整配置

配置项说明

占位符

完整配置示例

示例 1：Lite 项目

示例 2：Modular 项目

示例 3：Clean Architecture 项目

配置验证

有效配置

无效配置

常见问题

配置不生效？

如何重置配置？

多个项目如何共享配置？

配置文件应该提交到 Git 吗？