Flutter JSON Factory

一个面向 VS Code / Cursor 的 Flutter 模型生成插件，参考 FlutterJsonBeanFactory 的使用体验，提供从 JSON 快速生成 Dart Model 的能力，并支持在已有实体文件上重新生成序列化代码。

插件定位

这不是一个通用代码生成框架，而是一个偏“开发提效”的模型生成插件。目标是减少下面几类重复劳动：

• 把接口 JSON 手动改成 Dart 类
• 补 fromJson / toJson
• 在 native、json_serializable、freezed 三种风格之间切换
• 修改字段后重新刷序列化代码
• 将模型统一输出到 Flutter 项目指定目录

核心能力

• 从编辑器选中 JSON 生成模型
• 从 .json / .jsonc 文件生成模型
• 从剪贴板生成模型
• 在资源管理器里右键某个目录，直接生成到当前目录
• 自动识别 Flutter 项目 pubspec.yaml 中的 flutter_json.generated_path
• 原生模式自动生成公共工具类 base/json_factory_helper.dart
• 支持嵌套对象
• 支持对象数组
• 支持日期字符串推断为 DateTime
• 支持 native
• 支持 json_serializable
• 支持 freezed
• 支持根据当前 Dart 文件字段重新生成序列化代码

适用场景

• Flutter 接口模型初始化
• 接口字段变更后的快速回刷
• 项目内统一模型生成风格
• Cursor / VS Code 中替代 JetBrains 版工作流

命令列表

• Flutter JSON Factory: Generate Dart Model from JSON
• Flutter JSON Factory: Generate Dart Model from Clipboard
• Flutter JSON Factory: Regenerate Current Dart File Serialization

使用方式

方式一：从编辑器内容生成

1. 打开一个 .json 文件，或者在任意编辑器里选中一段 JSON。
2. 执行 Flutter JSON Factory: Generate Dart Model from JSON。
3. 输入根类名，例如 UserInfoResponse。
4. 选择生成模式： Native / json_serializable / freezed
5. 生成结果会写入目标目录，或者按设置打开为一个新的 Dart 文档。

方式二：从剪贴板生成

1. 复制 JSON。
2. 执行 Flutter JSON Factory: Generate Dart Model from Clipboard。
3. 输入根类名。
4. 选择生成模式。

方式三：右键目录生成

1. 在资源管理器里右键某个目录。
2. 选择 Flutter JSON Factory: Generate Dart Model from JSON。
3. 粘贴 JSON。
4. 输入类名。
5. 模型会直接生成到你右键的目录中。

方式四：修改字段后重生成

1. 打开一个已有 Dart 实体文件。
2. 修改字段，例如增加、删除、改名。
3. 执行 Flutter JSON Factory: Regenerate Current Dart File Serialization。
4. 插件会按当前字段重新生成序列化代码。

说明：

• native 模式会重建 fromJson / toJson / copyWith
• json_serializable 模式会重建类定义与 @JsonKey
• freezed 模式会重建 abstract class、const factory 与 fromJson

输出目录规则

1. 目录右键时

优先使用你右键选择的目录作为输出目录。

2. Flutter 项目中普通生成时

如果检测到 Flutter 项目根目录，并且 flutterJsonFactory.preferProjectOutput = true，插件会优先读取 pubspec.yaml：

flutter_json:
  generated_path: lib/generated/json/**

然后把模型写入该目录。

3. 未检测到项目目录时

插件会直接打开一个新的未保存 Dart 文档。

生成模式说明

Native

生成普通 Dart 类，包含：

• 字段
• 构造函数
• fromJson
• toJson
• copyWith

适合：

• 不想依赖代码生成器
• 需要直接落地可读代码
• 小型项目或快速验证

json_serializable

生成内容包含：

• @JsonSerializable(explicitToJson: true)
• part 'xxx.g.dart'
• 必要的 @JsonKey(...)

依赖示例：

dependencies:
  json_annotation: ^4.9.0

dev_dependencies:
  build_runner: ^2.4.0
  json_serializable: ^6.8.0

生成后执行：

dart run build_runner build --delete-conflicting-outputs

freezed

生成内容包含：

• @freezed
• abstract class Xxx with _$Xxx
• const factory
• part 'xxx.freezed.dart'
• part 'xxx.g.dart'

依赖示例：

dependencies:
  freezed_annotation: ^2.4.0
  json_annotation: ^4.9.0

dev_dependencies:
  build_runner: ^2.4.0
  freezed: ^2.5.0
  json_serializable: ^6.8.0

生成后执行：

dart run build_runner build --delete-conflicting-outputs

配置项

• flutterJsonFactory.generationMode 默认生成模式
• flutterJsonFactory.nullable 是否默认生成可空字段
• flutterJsonFactory.useFinalFields 原生模式字段是否为 final
• flutterJsonFactory.includeCopyWith 原生模式是否生成 copyWith
• flutterJsonFactory.includeJsonSerializableHint 是否写入生成标记注释
• flutterJsonFactory.defaultOutputMode 未命中项目输出目录时，输出到新文档还是替换当前文件
• flutterJsonFactory.preferProjectOutput 是否优先写入 Flutter 项目配置目录

示例

输入：

{
  "code": 200,
  "message": "ok",
  "data": {
    "id": 1,
    "name": "Codex",
    "created_at": "2026-03-18T10:00:00Z",
    "tags": ["flutter", "json"]
  }
}

可生成类似：

class ApiResponse {
  final int? code;
  final String? message;
  final ApiResponseData? data;

  const ApiResponse({
    this.code,
    this.message,
    this.data,
  });

  factory ApiResponse.fromJson(Map<String, dynamic> json) {
    return ApiResponse(
      code: json['code'] == null ? null : (json['code'] as num).toInt(),
      message: json['message']?.toString(),
      data: json['data'] == null
          ? null
          : ApiResponseData.fromJson(json['data'] as Map<String, dynamic>),
    );
  }
}

调试插件

1. 用 VS Code 打开本项目。
2. 按 F5。
3. 会启动一个 Extension Development Host 窗口。
4. 在新窗口中打开 Flutter 项目进行测试。

安装到 Cursor / VS Code

本项目支持直接打包 .vsix：

npm install
npm run package:vsix

安装方式：

1. 打开 Cursor 或 VS Code
2. 打开扩展面板
3. 点击右上角 ...
4. 选择 Install from VSIX...
5. 选择生成的 .vsix 文件

发布说明

本项目已补充本地发布脚本：

npm run publish:marketplace
npm run publish:openvsx

但真正发布到商店还需要你自己的发布者身份和 token。详细步骤见：

• PUBLISHING.md

已知限制

• 当前“重生成”更适合生成型实体文件
• 若文件里混有大量手写业务方法，建议拆分实体类再使用
• 数组空值和高度动态结构会退回为 dynamic

致谢

灵感和使用方式参考：

• FlutterJsonBeanFactory