跨平台开发 / 系统课时

处理陈旧代码与生成冲突

处理陈旧代码与生成冲突

生成代码失败时,最容易浪费时间的是反复执行 build_runner,却没有确认源码、依赖和旧产物是否一致。本节给出一条从 part 声明到缓存清理的定位路径,并说明如何识别“能编译但仍在使用旧字段映射”的陈旧生成代码。

学习目标

  • 按固定顺序检查 part 声明、生成依赖和冲突产物
  • 识别 stale generated code 导致的编译错误与旧字段映射
  • 使用最小化的清理与重新生成流程恢复一致状态

先判断是源码问题还是生成物问题

以 lib/user.dart 为例,Freezed 与 json_serializable 依赖两个生成文件。文件名必须与源文件 basename 对齐,fromJson 入口也要指向正确的生成函数。

dart
import 'package:freezed_annotation/freezed_annotation.dart';

part 'user.freezed.dart';
part 'user.g.dart';

@freezed
abstract class User with _$User {
  const factory User({
    required String id,
    @Default('guest') String role,
  }) = _User;

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
}

这段源码的生效行为是:Freezed 生成不可变模型相关代码,json_serializable 生成 JSON 映射代码。验证时应同时看到 user.freezed.dart 与 user.g.dart,而不是只出现其中一个。

常见现象可以先按下面的线索归类:

现象 优先检查
Target of URI hasn't been generated part 文件名、生成命令是否执行成功
_$UserFromJson 未定义 fromJson 工厂、user.g.dart、json_serializable 相关依赖
生成器报告 conflicting outputs 旧生成物或手工创建了同名文件
源码已改字段但 JSON 仍按旧名字解析 生成文件未刷新,或正在运行旧构建产物

按顺序排除生成冲突

不要一开始就删除整个项目缓存。先从最便宜的检查开始:确认 part、保存源文件、确认依赖解析正常,再执行一次允许删除冲突输出的构建。

bash
dart run build_runner build --delete-conflicting-outputs
dart analyze

预期结果

text
build_runner: exit code 0
dart analyze: No issues found!

实际生成器日志会随版本和项目规模变化,因此应以退出码、生成文件是否刷新以及分析器是否通过为准。

如果仍然失败,再清理 build_runner 自己维护的构建图并重新生成:

bash
dart run build_runner clean
dart run build_runner build --delete-conflicting-outputs

预期结果

text
build_runner: exit code 0
generated files: regenerated from current source

clean 的目的不是“修好所有问题”,而是丢弃 build_runner 的旧构建状态。若 part 写错、注解不合法或依赖版本互不兼容,清理后仍会失败。

生成代码冲突的定位顺序

识别“编译通过但逻辑仍旧”的陈旧代码

陈旧生成物不一定表现为编译错误。更危险的情况是模型源码已经把字段从 user_name 改成 display_name,但运行中的应用仍使用旧 .g.dart,于是接口解析结果看起来像“后端没传值”。

定位这类问题时,不要直接修改 .g.dart 或 .freezed.dart。先比较源文件修改时间与生成文件是否同步更新,再搜索生成文件中的 JSON key 是否仍是旧值。重新生成后,执行针对该字段的解析测试,确认新映射真正生效。

依赖版本冲突要从约束关系处理

如果生成器报的是 API 不兼容、builder 无法加载或 annotation 类型不匹配,问题通常不在缓存,而在依赖约束。此时先查看解析结果,再根据报错调整 freezed、freezed_annotation、json_serializable、json_annotation 与 build_runner 的兼容版本,不要靠反复 clean 碰运气。

bash
dart pub deps --style=compact

预期结果

text
exit code: 0
dependency graph: resolved

真正的验收标准是三件事同时成立:当前源码能重新生成、静态分析通过、关键 JSON 字段的测试按新契约通过。只看到“生成命令成功”还不足以证明陈旧逻辑已经被清除。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理陈旧代码与生成冲突

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通