生成器配置详解

本文档详细介绍每个生成器的配置选项和使用场景。

配置概览

所有生成器配置都在 .flu-cli.json 的 generators 对象中：

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

Page 生成器

基本配置

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

path - 生成路径

类型: string
默认值: "lib/pages"
说明: 页面文件的生成路径

示例:

// 简单路径
"path": "lib/pages"

// 模块化路径
"path": "lib/features/{feature}/pages"

// UI 层路径
"path": "lib/ui/pages"

defaultType - 默认类型

类型: "stateful" | "stateless"
默认值: "stateful"
说明: 页面的默认类型

示例:

// 默认生成 StatefulWidget
"defaultType": "stateful"

// 默认生成 StatelessWidget
"defaultType": "stateless"

选择建议:

• stateful: 需要状态管理的页面（推荐）
• stateless: 简单的静态页面

withViewModel - 生成 ViewModel

类型: boolean
默认值: true
说明: 是否自动生成对应的 ViewModel

示例:

// 自动生成 ViewModel（推荐）
"withViewModel": true

// 不生成 ViewModel
"withViewModel": false

withBasePage - 继承 BasePage

类型: boolean
默认值: false
说明: 是否继承自定义的 BasePage

示例:

"withBasePage": true,
"basePageClass": "BasePage",
"basePageImport": "package:my_app/core/base/base_page.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(),
    );
  }
}

basePageClass - BasePage 类名

类型: string
默认值: "BasePage"
说明: BasePage 的类名

basePageImport - BasePage 导入路径

类型: string
说明: BasePage 的导入路径

格式: package:项目名/路径

fileSuffix - 文件后缀

类型: string
默认值: "_page"
说明: 生成文件的后缀

示例:

// 生成 home_page.dart
"fileSuffix": "_page"

// 生成 home_view.dart
"fileSuffix": "_view"

// 生成 home_screen.dart
"fileSuffix": "_screen"

ViewModel 生成器

基本配置

{
    "generators": {
        "viewModel": {
            "path": "lib/viewmodels",
            "withBaseViewModel": false,
            "fileSuffix": "_viewmodel"
        }
    }
}

path - 生成路径

类型: string
默认值: "lib/viewmodels"

示例:

"path": "lib/viewmodels"
"path": "lib/features/{feature}/viewmodels"
"path": "lib/features/{feature}/controllers"

withBaseViewModel - 继承 BaseViewModel

类型: boolean
默认值: false

示例:

"withBaseViewModel": true,
"baseViewModelClass": "BaseViewModel",
"baseViewModelImport": "package:my_app/core/base/base_viewmodel.dart"

生成的代码:

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

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

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

baseViewModelClass - BaseViewModel 类名

类型: string
默认值: "BaseViewModel"

baseViewModelImport - BaseViewModel 导入路径

类型: string

fileSuffix - 文件后缀

类型: string
默认值: "_viewmodel"

示例:

"fileSuffix": "_viewmodel"  // home_viewmodel.dart
"fileSuffix": "_controller" // home_controller.dart
"fileSuffix": "_vm"         // home_vm.dart

Widget 生成器

基本配置

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

path - 生成路径

类型: string
默认值: "lib/widgets"

示例:

"path": "lib/widgets"
"path": "lib/shared/widgets"
"path": "lib/features/{feature}/widgets"

defaultType - 默认类型

类型: "stateful" | "stateless"
默认值: "stateless"

选择建议:

• stateless: 无状态组件（推荐）
• stateful: 有状态组件

fileSuffix - 文件后缀

类型: string
默认值: ""

示例:

"fileSuffix": ""         // custom_button.dart
"fileSuffix": "_widget"  // custom_button_widget.dart

Component 生成器

配置项与 Widget 生成器相同。

基本配置

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

Widget vs Component

• Widget: 通用的、可复用的 UI 组件
• Component: 业务相关的、特定功能的组件

Model 生成器

基本配置

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

path - 生成路径

类型: string
默认值: "lib/models"

示例:

"path": "lib/models"
"path": "lib/data/models"
"path": "lib/features/{feature}/models"
"path": "lib/features/{feature}/domain/entities"

fileSuffix - 文件后缀

类型: string
默认值: "_model"

示例:

"fileSuffix": "_model"   // user_model.dart
"fileSuffix": "_entity"  // user_entity.dart
"fileSuffix": ""         // user.dart

Service 生成器

基本配置

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

path - 生成路径

类型: string
默认值: "lib/services"

示例:

"path": "lib/services"
"path": "lib/data/services"
"path": "lib/features/{feature}/services"
"path": "lib/features/{feature}/data/datasources"

fileSuffix - 文件后缀

类型: string
默认值: "_service"

示例:

"fileSuffix": "_service"     // user_service.dart
"fileSuffix": "_api"         // user_api.dart
"fileSuffix": "_datasource"  // user_datasource.dart

Module 生成器

基本配置

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

path - 生成路径

类型: string
默认值: "lib/features/{feature}"

说明: 必须包含 {feature} 占位符

structure - 目录结构

类型: string[]
说明: 模块内的目录结构

示例:

Lite 项目:

"structure": [
  "pages",
  "viewmodels",
  "widgets",
  "models",
  "services"
]

Modular 项目:

"structure": [
  "pages",
  "viewmodels",
  "widgets",
  "services",
  "models"
]

Clean Architecture:

"structure": [
  "domain/entities",
  "domain/repositories",
  "domain/usecases",
  "data/models",
  "data/datasources",
  "data/repositories",
  "presentation/pages",
  "presentation/viewmodels",
  "presentation/widgets"
]

配置模板

Lite 项目

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

Modular 项目

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

Clean Architecture 项目

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

最佳实践

1. 使用一致的命名

保持文件后缀的一致性：

{
    "generators": {
        "page": { "fileSuffix": "_page" },
        "viewModel": { "fileSuffix": "_viewmodel" },
        "model": { "fileSuffix": "_model" },
        "service": { "fileSuffix": "_service" }
    }
}

2. 合理使用 BasePage/BaseViewModel

如果项目有统一的基类，配置继承：

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

3. 模块化路径

使用 {feature} 占位符实现模块化：

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

4. 团队统一配置

将 .flu-cli.json 提交到 Git，确保团队使用统一配置。

常见问题

如何修改默认类型？

修改 defaultType 配置：

{
    "generators": {
        "page": {
            "defaultType": "stateless" // 改为 stateless
        }
    }
}

如何不生成 ViewModel？

设置 withViewModel 为 false：

{
    "generators": {
        "page": {
            "withViewModel": false
        }
    }
}

如何自定义文件后缀？

修改 fileSuffix 配置：

{
    "generators": {
        "page": {
            "fileSuffix": "_view" // 生成 xxx_view.dart
        }
    }
}

配置不生效？

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

下一步

• 📖 查看 .flu-cli.json 配置 了解配置文件
• 🔧 学习 高级配置 掌握高级用法
• 💡 查看 最佳实践 学习推荐配置

相关链接

• 快速开始
• 生成文件
• .flu-cli.json 配置