★ FEATURED ARTICLE 说来也巧我们团队从三年前就把injectableinject_generator这套自动依赖注入方案钉在了所有 Flutter 工程里大到几十个模块的货架项目小到内部工具全部用注解声明依赖、用 build_runner 自动生成注册代码。上个月开始把主力 App 往鸿蒙环境迁本以为最头痛的会是原生层适配结果真正卡了我们整整一周的反而是这个看起来平台无关的自动化依赖注入生成器。这篇文章就把整个适配过程完整记录下来inject_generator 到底在生成什么、鸿蒙环境下为什么跑不通、我们是怎么一层层定位并解决的以及最终的兜底方案设计。如果你正在搞鸿蒙 Flutter 工程解耦或者准备把现有的 get_it / injectable 体系平移到鸿蒙这篇文章应该能帮你少走不少弯路。1. 背景说明鸿蒙大型工程为什么离不开依赖注入生成器1.1 inject_generator 在 Flutter 工程里到底扮演什么角色先给还不熟悉这套方案的朋友把概念理清。inject_generator是依赖注入框架injectable的代码生成器它与容器get_it配合把手动编写依赖注册代码这件重复劳动彻底自动化。你只需要在类上打一个injectable注解然后运行一句dart run build_runner build它就会扫描所有源码、分析构造函数签名并生成一个*.gr.dart文件里面包含了完整的 get_it 注册逻辑。拿我们项目里的老代码举例injectable class AuthService { final ApiClient _api; final TokenStore _store; AuthService(this._api, this._store); }生成后会自动产生类似这样的代码gh.lazySingletonAuthService( () AuthService( ghApiClient(), ghTokenStore(), ), );这背后解决的问题非常实在。没有这套机制的时候大型工程的根目录会挂一个几百行的service_locator.dart每新增一个 Service 就要手动加注册、手动维护构造函数参数顺序一旦漏了一个默默依赖另一个模块的实现类运行时立刻炸给你看。而有了生成器pubspec.yaml里加依赖、类上打注解、重新 build完事。这就是大型工程解耦最喜欢它的原因。1.2 鸿蒙 Flutter 工程的工程现状与迁移痛点鸿蒙侧的 Flutter 生态和 Android/iOS 不太一样。目前可用的 Flutter 分支主要是 OpenHarmony SIG 社区维护的版本它有自己的引擎构建链、插件实现方式和构建工具链。这意味着两件事第一原生插件可能找不到匹配的鸿蒙实现第二纯 Dart 层的库虽然理论上不受平台影响但实际编译运行时会暴露很多隐藏的平台假设。团队里有些人一开始很乐观inject_generator 生成的是纯 Dart 代码啊鸿蒙肯定直接就能跑。这句话只对了一半。我们的第一版迁移方案确实把 pubspec 里的依赖换成鸿蒙分支后编译能过、运行也能启动但只要进入页面加载依赖的瞬间就出现各种 Type X is not registered、invalid type 异常。更深层的问题在于鸿蒙工程里 Flutter 往往以 XComponent 的方式嵌入 UIAbility页面生命周期和 Activity 模式有差异而且鸿蒙环境对dart:io之类 Dart 库的支持实现并不完全一致injectable 在生成代码中做的平台分支判断、EnvironmentFilter 行为都可能踩到我们完全没想到的坑。这套东西运行在 Flutter 上并不意味着天然可平移它仍然需要专门做一轮鸿蒙化适配。1.3 本次适配的目标界定在动手前我们把鸿蒙化适配拆成了四个可验收的目标能生成build_runner 能在鸿蒙 Flutter 工程里正常执行产出正确的.gr.dart文件能注册生成代码能在鸿蒙环境的 Dart VM 上完成依赖装配不报类型冲突能注入getItT()或者构造函数自动注入能拿到正确的实例生命周期符合声明配置可兜底一旦生成器因为环境差异失效工程不能处于瘫痪状态必须有一套不依赖代码生成的手写注册方案做降级。这个目标清单推荐大家也抄一份。适配不是跑通 demo就结束的后面每一层的验证都对应一类典型的鸿蒙适配问题。2. 机制拆解inject_generator 生成链路的底层逻辑2.1 一套注解如何映射为一套容器 API要适配它首先得理解它内部的工作方式。injectable 的注解看起来简单实际上映射的是一套非常精细的 get_it API。几个常用的映射关系是注解生成后的注册调用实例化时机injectableregisterFactory每次获取都创建一个新实例lazySingletonregisterLazySingleton首次获取时创建之后复用singletonregisterSingleton获取前预先初始化之后复用factoryParamregisterFactoryParam调用时传入运行时参数disposableregisterDisposable容器重置时执行清理回调看到这个映射表你就能明白为什么日常开发中大家习惯用lazySingleton—— 启动时不创建全部依赖只在某个页面首次用到 Service 时才把整条依赖链实例化这正好符合大型工程延迟初始化、按需加载的性能诉求。鸿蒙适配中的第一个隐患也在这里有些依赖需要在初始化阶段访问系统能力比如读取鸿蒙侧的配置、订阅 Ability 生命周期事件。如果开发者在singleton的构造器里直接访问Activity/UIAbilityContext生成代码在 Diapatcher 阶段执行时就会因为上下文尚未就绪而失败。这类问题不是生成器本身造成的但适配时你必须提前在注解设计上规避。2.2 从 build_runner 到 gr.dart 的完整流水线inject_generator 的源码实现基于 Dart 官方的source_genanalyzer体系。它不是一个简单的字符串拼接工具而是两段式工作流第一段是静态分析。build_runner 启动后它会遍历工程里所有 Dart 文件构建一套完整的类型分析图——包括每个类的构造函数参数、可选参数、泛型参数、依赖类型是不是也存在于注解扫描范围。这个过程和编译器前端的语义分析非常像它必须精确知道AuthService(ApiClient api, TokenStore store)中的ApiClient和TokenStore分别指向哪个类型才能生成正确的取值代码。第二段是代码模板渲染。分析完成后生成器会拿分析结果去填充自己的代码模板。默认情况下输出的是一个$initGetIt方法的定义在模板中它会把每个被扫描到的类型归类到对应的 get_it 注册调用里。最终得到的.gr.dart长得像下面这样// GENERATED CODE - DO NOT MODIFY BY HAND final GetIt getIt GetIt.instance; Futurevoid $initGetIt( GetIt getIt, { String? environment, EnvironmentFilter? environmentFilter, }) async { final gh GetItHelper(getIt, environment, environmentFilter); gh.lazySingletonApiClient(() ApiClient(ghDio())); gh.lazySingletonAuthService(() AuthService(ghApiClient(), ghTokenStore())); gh.lazySingletonTokenStore(() TokenStore()); }这段生成代码是需要被你手动调用一次的工程里通常有一个di/injection.dart里写InjectableInit() Futurevoid configureDependencies() async $initGetIt(getIt);$initGetIt这个名字在后面适配过程中还会有戏份因为如果生成失败或者缺失我们可以自己手写一个同名方法做无缝替换。2.3 生成代码在运行时的真实行为生成出来的注册方法本质上是把类型映射到工厂闭包。当你调用getItAuthService()时get_it 内部会找注册表中 key 对应的工厂函数执行闭包然后沿着闭包内部的ghApiClient()继续递归获取依赖。这个递归获取的过程就是依赖注入的魔法所在。它有三个典型特性适配时必须心里有数第一注册顺序对最终结果没有影响。因为 get_it 的注册表是 Map查找依赖不依赖注册顺序生成器默认自己处理了对错顺序的容错。第二循环依赖不会被自动发现。如果A构造依赖B、B构造依赖A生成代码会导致运行时的无限递归最终栈溢出。injectable 建了一部分循环检测但只对直接循环敏感间接循环还是得靠运行期炸一下才知道。第三环境Environment是一个黑盒过滤机制。通过Environment(prod)或EnvironmentFilter可以让同一个生成文件在不同环境只注册不同的实现。这也意味着如果你没有给鸿蒙环境配单独的 EnvironmentFilter它就会走默认分支而这默认分支里可能引用了在鸿蒙上未实现的 NoSql 存储或通道。3. 鸿蒙化适配的真正难点平台假设与工具链差异3.1 平台感知代码是首要排查对象inject_generator 在部分版本中会生成带有平台判断的代码。比如最近几个版本会检查kIsWeb和defaultTargetPlatform来区分移动端和 Web 端的实现。逻辑本身没问题但在鸿蒙的 Flutter 引擎分支里defaultTargetPlatform返回的枚举值可能不在它预设的TargetPlatform.android.name/TargetPlatform.iOS.name分支中这就可能导致生成代码走到某个意外兜底分支注册到错误的实现类。另一个隐蔽问题是dart.library.js_interop。新版 injectable 为了支持 Wasm / Web 打破了原有的条件导入策略而鸿蒙的 Dart 分支对 JS 互操作的原生支持程度和版本有关如果遇到Failed to load package:.../web.dart through package config之类的报错十有八九就是这个位置出了问题。实操建议适配第一步先把生成的.gr.dart全文通读一遍专门看那些import了 web 相关库、引用了kIsWeb或平台枚举的文件。我们的策略是不让生成器去感知鸿蒙平台强制它走非 Web分支鸿蒙特有的差异全部放到注入类自己内部处理。3.2 构建工具链差异与生成器执行环境build_runner 的执行依赖完整的 Dart 工具链包括 pub 缓存、process 调用、文件系统监听。在鸿蒙开发环境里我们遇到过一个特别简单但特别耗时间的问题同时装了 DevEco Studio 自带的环境和命令行 Flutter 工具两者的 Dart 版本不一致第一次执行 build_runner 时它走的是 DevEco 的内置引擎结果analyzer版本冲突直接报了一屏错误。后来我们用命令行统一接管flutter_harmonyos pub get dart run build_runner build --delete-conflicting-outputs注意dart run和flutter pub get必须来自同一套 SDK 路径。DevEco Studio 里的构建按钮虽然方便但你在 CI 或者命令行执行 build_runner 时环境变量PATH里排在最前面的必须是鸿蒙 Flutter 分支的bin目录。另一个工具链差异是插件包管理。鸿蒙 Flutter 分支的 pub 源会有一部分特有的 fork 包如果pubspec.lock里混入了官方 Flutter 解析出来的依赖闭包在解析时可能报 cannot find matching package 的错误。我们的解决方式很笨但有效把pubspec.lock删掉用鸿蒙分支的flutter_harmonyos pub get重新解析一次先保证基础依赖树干净再往工程里加 injectable 相关的东西。3.3 依赖版本冲突是大概率事件injectable 的生成器对analyzer、source_gen、build这三个包的版本非常敏感。官方 Flutter 的较新版本中这些依赖通常会随着 Flutter SDK 的升级而收窄版本范围。鸿蒙 Flutter 分支因为基于特定版本的 Flutter 分支它们的analyzer版本往往比官方最新版低一截这就导致Because injectable_generator x.y.z depends on analyzer ^0.7.0 and harmony_flutter depends on analyzer 0.6.x, injectable_generator is forbidden.这种版本冲突的解法一般是降级 injectable。我们当前用的版本组合是包名版本范围说明injectable2.4.x采用 2.4 系列避开要求过高的分析器版本injectable_generator2.4.x与 injectable 小版本严格对齐get_it^7.7.07.x 系列在鸿蒙分支的 Dart 环境表现稳定build_runner^2.4.0锁在这个版本避免新版对 SDK 的更高要求注意这只是一个可供借鉴的基线组合不意味着每个工程都可以直接照抄。你的鸿蒙 Flutter 分支具体基于哪个 Dart 版本决定了analyzer的上限因此在pubspec.yaml里可以给 injectable 系列用宽松的 caret 范围并配合 lock 文件锁定而不是一上来就图新。4. 鸿蒙化适配实现方案从改造到兜底4.1 搭建可复现的开发环境基线开始适配前先把一套干净的开发环境固定下来。我们的标准顺序是下载并配置 OpenHarmony SIG 维护的 Flutter 分支 SDK确保flutter_harmonyos doctor通过将flutter_harmonyos、dart都放入环境变量并用which验证它们指向同一套 bin 目录从鸿蒙 Flutter 分支的官方示例工程拷贝一份最小可运行模板先在模拟器跑通一个空壳应用在空壳工程里加入 get_it、injectable、injectable_generator、build_runner先跑一次构建生成验证工具链本身没有版本冲突。这四步做完你才有底气进行真正的业务工程改造。我们第一次偷懒直接在老工程上原地换 SDK结果光排查依赖冲突就花了三天。4.2 pubspec 与 build.yaml 的配置改造在pubspec.yaml中除了上述依赖版本组合外还需要注意 dev_dependencies 部分dev_dependencies: build_runner: ^2.4.0 injectable_generator: 2.4.1build_runner 不是业务代码里的运行期依赖不要放到 dependencies 里。injectable_generator 同理。运行期只需要injectable和get_it。如果你是第一次在鸿蒙工程中使用 injectable还需要确认生成器默认的构建配置可用。多数情况下不用额外写 build.yamlinjectable 会自动扫描 lib 目录。不过为了更精细地控制扫描范围我们加了一份targets: $default: builders: injectable_generator: generate_for: - lib/**/*.dart options: # 关闭自动注册到全局的某些扩展行为 auto_register: false注意auto_register: false只是我们为了配合工程里存在多套初始化逻辑而做的选择。如果一开始不知道这个配置的含义不要随意开启。保持默认值先跑通最小链路再考虑生成范围和生成开关。4.3 兜底手写 Injector 替代生成代码再怎么说适配方案也逃不掉一个核心问题如果 inject_generator 在这个鸿蒙分支上实在无法正常工作怎么办我们的答案是一个不依赖代码生成器的手写定位器。它担负的任务很简单——把同样一套注册逻辑用人类更容易理解的手写代码表达出来。实现思路如下// di/manual_locator.dart import package:get_it/get_it.dart; final GetIt manualLocator GetIt.instance; void configureManualDependencies() { manualLocator ..registerLazySingletonTokenStore(() TokenStore()) ..registerLazySingletonApiClient(() ApiClient()) ..registerLazySingletonAuthService( () AuthService( manualLocatorApiClient(), manualLocatorTokenStore(), ), ); }这个手写方案的价值在于它让整个业务工程不依赖 build_runner 的输出。即使某天鸿蒙的版更新导致生成器彻底不可用你只需要把di/injection.dart里的启动方法从$initGetIt替换成configureManualDependencies业务侧调用点完全不用改因为它们都是通过locatorT()访问依赖的。这一步是整个适配方案的压舱石也是我在所有技术分享中反复强调的做平台适配时先设计好降级路径再去做兼容改造不要上来就啃硬骨头。4.4 main 入口装配与生成初始化方法在鸿蒙 Flutter 工程里入口装配和普通 Flutter 没有太大差异。我们需要在 runApp 之前初始化依赖容器。为了兼容生成代码和手写兜底两种模式我们把 initializerName 定成一个统一的符号// di/injection.dart import package:get_it/get_it.dart; import package:injectable/injectable.dart; final GetIt locator GetIt.instance; InjectableInit( initializerName: r$initGetIt, preferForInitialization: true, ) Futurevoid configureDependencies() async { await $initGetIt(locator); }当生成器正常工作时$initGetIt来自自动生成的.gr.dart当生成器不可用时在di/manual_locator.dart里手动定义Futurevoid $initGetIt(GetIt getIt) async { configureManualDependencies(); }这样入口文件和业务代码就不会跟着适配方案反复改动。这一点在后续鸿蒙仓库与多端仓库共享时特别重要因为你希望 main.dart 是平台无关的。5. 实战鸿蒙 Flutter 工程里的一次完整依赖注入落地5.1 示例工程结构与领域划分我们用一个贴近实际的例子工程需要支持用户登录、读取配置、请求远程数据。按模块划分了几个目录lib/ main.dart # 入口负责初始化 DI di/ injection.dart # 全局装配入口 manual_locator.dart # 手写兜底注册 data/ token_store.dart # Token 存储单例 network/ api_client.dart # 网络客户端注入 Dio service/ auth_service.dart # 认证服务依赖网络和存储 page/ login_page.dart # UI 层消费 AuthService我刻意不在这个示例里使用面向抽象接口那套复杂的工厂模式因为入门阶段先把这个注入链路看清更重要。真正的大型工程里模块之间通过abstract interface隔离注入类只依赖抽象接口不在数据层暴露具体实现这会进一步降低鸿蒙迁移时编译层面的耦合度。5.2 从注解到实例装配的完整动作序列第一步在业务类上打注解// data/token_store.dart lazySingleton class TokenStore { String? token; String? read() token; }// network/api_client.dart injectable class ApiClient { final Dio dio; ApiClient(this.dio) { dio.options.baseUrl https://api.example.com; } }// service/auth_service.dart lazySingleton class AuthService { final ApiClient _api; final TokenStore _store; AuthService(this._api, this._store); Futurevoid login(String username, String password) async { // 真正登录逻辑会访问 _api 与 _store } }第二步运行构建命令flutter_harmonyos pub get dart run build_runner build --delete-conflicting-outputs这一步如果没有任何输出请回头查 3.2 节的环境变量。正常的话每个带有注解的库文件旁边会多出*.gr.dart文件。第三步在main.dart中装配并启动// main.dart void main() async { WidgetsFlutterBinding.ensureInitialized(); await configureDependencies(); runApp(const HarmonyApp()); }第四步在登录页里消费依赖。这里的关键是不要在 Widget 构造函数里直接拿依赖而是用后置方式来取让页面自身的 Widget 依赖保持干净class LoginPage extends StatelessWidget { const LoginPage({super.key}); override Widget build(BuildContext context) { final AuthService authService locatorAuthService(); // build UI... } }生成代码会帮你把AuthService - ApiClient - Dio这条链全部在运行时准备好页面上完全感受不到类型是怎么被实例化的。这也是解耦最直接的好处登录页不需要知道 AuthService 依赖哪些底层组件后续替换实现时也不会改动 UI 层。5.3 与鸿蒙 Ability 生命周期协同的注册策略普通 Flutter 应用里依赖容器通常在 main 方法里注册一次后全局永存。但鸿蒙的 UIAbility 生命周期和 Android 的 Activity 有差异最重要的是它可能以元服务的形式出现支持服务卡片和短期窗口Ability 在退到后台时并不保证立即销毁这在依赖注入的作用域设计中非常容易犯错。我们的策略是以 UIAbility 为一个生命周期边界在 Ability 创建时 push 一个容器作用域销毁时 reset。injectable 和 get_it 天然支持作用域链管理// 鸿蒙侧 FlutterAbility 的生命周期回调中 class MainAbility : FlutterAbility { override void onWindowStageCreate(Object windowStage) { locator.pushNewScope(scopeName: main_scene); super.onWindowStageCreate(windowStage); } override void onWindowStageDestroy() { locator.resetScope(scopeName: main_scene); super.onWindowStageDestroy(); } }简单说一下原理get_it 的pushNewScope会创建新的叶子作用域新注册到叶子里的依赖在resetScope时统一销毁注册在根作用域的全局单例则保留。这对鸿蒙场景很有用页面级缓存、临时网络请求对象都注册到叶子作用域Ability 重建时它们不会泄漏。我们没有把容器扩展和组件作用域做太复杂毕竟在鸿蒙生态里元服务、卡片这些形态才刚刚普及保持简单逻辑遇到性能瓶颈再升级作用域设计。6. 常见问题与排查技巧实录6.1 构建期问题速查表现象原因处理方式dart run build_runner build报Failed to load builderinjectable_generator 版本与 analyzer 冲突降级到 2.4.x 系列见 3.3 版本组合构建能过但没有生成.gr.dartbuild.yaml 的 generate_for 范围错误检查 build.yaml 里是否把 lib 子目录排除生成的代码带着大量 Web import生成器按平台判断走了 Web 分支使用环境变量强制非 Web或更新 interop 依赖依赖树解析报版本冲突lock 文件混入了官方 Flutter 解析结果删 lock 重新flutter_harmonyos pub getDevEco Studio 里构建和命令行 build_runner 互相覆盖两个 SDK 并存统一 PATH确认which flutter_harmonyos指向的目标6.2 运行期注册失败与生命周期问题的排查运行期最常见的报错是FlutterError (TypeError: Instance of X is not registered for type X)这个报错有九个字可以送给大家别只看最后一行。它一般发生在依赖链深层的某个类型。最有效的方式是在$initGetIt生成代码中按注册顺序里由后往前逐个添加打印日志看看到底哪一个类型的工厂闭包没有被调用。也可以利用 GetIt 的调试接口if (kDebugMode) { getIt.allReady(); getIt.allowReassignment true; }allowReassignment在调试时有妙用如果存在重复注册它会以后面的覆盖前面的策略兜住从而把你的注册冲突从崩溃问题转变成可观察的覆盖问题。然后你再去看生成的代码里为什么出现了同一个类型的两个注册。多数情况是你在两个不同的 Library 中都声明了同一个类的不同配置注解扫描器把它们都纳入生成范围导致重复注册。另一个和鸿蒙生命周期相关的坑如果你的singleton依赖构造函数里要读取UIAbilityContext而它是在onWindowStageCreate之前被注册的那么它拿到的可能是空上下文。建议做法是凡是需要在运行时获取系统上下文的依赖全部改成lazySingleton并且允许在调用点才去取系统服务而不是构造时直接读上下文。6.3 针对鸿蒙长期维护的三个建议第一生成代码尽量少提交进源码库。虽然很多人喜欢把*.gr.dart也提交到 git方便其他人免构建直接编译但在鸿蒙分支频繁更新的阶段我建议把这些文件放入.gitignore。原因很简单持续集成里如果换了鸿蒙 Flutter 版本生成代码往往需要跟随一起变你不提交它CI 每次都会基于当前 SDK 重新生成少了一类代码和SDK版本不匹配的隐性故障。第二为依赖容器单独建一个中间抽象层。不要直接在业务代码里到处写getItT()而是统一封装为locatorT()。这个建议并不是鸿蒙专属但鸿蒙适配中特别值钱因为你可能在某个版本里需要把 get_it 换成鸿蒙侧自研的容器届时只需要改一个文件而不是把几千个调用点翻出来改。第三在工程里维护依赖注入的架构测试。比如一个测试断言所有标注了lazySingleton的类在注册时没有读取系统上下文这类测例用纯 Dart 就能写跑在 CI 上也很快。它能防止后续业务同学在鸿蒙工程里写下一个构造时访问系统能力的定时炸弹。最后再分享一条我个人的经验这次适配给我最大的教训是平台相关的代码生成器永远不要默认它是平台无关的。inject_generator 在设计上留了很大的平台假设空间只不过 Android 和 iOS 都是移动端感受不到差异到鸿蒙这个新的运行环境那些假设就被一一放大了。所以如果你也在搞鸿蒙 Flutter 工程解耦我建议你从准备一个可随时启用的手写注册兜底开始再把 build_runner 的产物当成可再生成文件而不是交付物最后才去逐条核对版本组合、平台分支、生命周期边界。顺序反过来很容易陷入生成器跑通了一个 demo 就以为自己适配完成的假象里。这套方案已经在我们实际工程里跑了小半年稳定性和可维护性都验证过。后续如果要升级到 injectable 的 3.x 或更高版本只需要重新跑一遍 4.2 节的版本组合验证再对照 6.1 的速查表排查一遍整套流程是可以复用的。希望这份指南能帮你把鸿蒙化适配从玄学变回工程学。
阅读完成 · 觉得有帮助？
