01. 项目初始化与 HarmonyOS 环境搭建深度指南

项目地址: https://gitcode.com/Goway_Hui/gitcode-pocket

1. 项目背景与技术选型

1.1 为什么选择 Flutter for OpenHarmony？

本项目 GitCode Pocket 是一个纯粹的 Flutter 鸿蒙化项目。随着 HarmonyOS NEXT (OpenHarmony) 生态的崛起，原生应用开发需求激增。Flutter 作为跨平台 UI 框架的佼佼者，通过 Flutter for OpenHarmony 项目实现了对鸿蒙系统的原生支持。

选择 Flutter 开发鸿蒙应用的优势在于：

• 高性能渲染：基于 Skia/Impeller 图形引擎，直接对接鸿蒙系统的 XComponent，绕过中间层，实现 120Hz 流畅体验。
• Dart 语言优势：强类型、AOT 编译，保证了应用在鸿蒙设备上的运行效率。
• 生态复用：虽然本项目只针对鸿蒙，但大量纯 Dart 逻辑（状态管理、网络层）可复用现有的 Flutter 生态库。

1.2 鸿蒙原生开发视角

与传统 Android/iOS 开发不同，鸿蒙应用基于 ArkUI 和 Ability 框架。在本项目中，Flutter 页面实际上是托管在鸿蒙的 EntryAbility 中的一个 XComponent 容器里。理解这一点对于后续处理生命周期和原生交互至关重要。

2. 鸿蒙开发环境深度配置

要开发 Flutter 鸿蒙应用，环境配置比标准 Flutter 更为严格。请务必按照以下步骤操作。

2.1 基础工具链

1. DevEco Studio: 请下载 DevEco Studio 5.0 或更高版本（Next Release）。这是鸿蒙开发的唯一官方 IDE，用于编译 HAP 包和调试 ArkTS 代码。
2. Command Line Tools: 确保安装了 ohpm (OpenHarmony Package Manager) 和 hvigor 构建工具。

2.2 Flutter for OpenHarmony SDK

标准 Flutter SDK 暂不包含鸿蒙支持，我们需要使用社区维护的 fork 版本。

# 1. 克隆仓库 
git clone -b master https://gitcode.com/openharmony-tpc/flutter_flutter.git flutter_ohos

# 2. 配置环境变量
export PATH="$PATH:/path/to/flutter_ohos/bin"
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

# 3. 预下载构件
flutter --Version

# 4. 验证安装
flutter doctor -v

注意：确保 flutter doctor 输出中包含 OpenHarmony 相关的工具链检测通过。

3. 工程创建与鸿蒙模块解析

3.1 初始化项目

使用 flutter create 命令并指定平台为 ohos。

flutter create --platforms ohos gitcode_pockets

3.2 鸿蒙工程结构深度解析 (ohos/)

生成的 ohos 目录是一个标准的鸿蒙原生工程，我们需要深入理解其结构：

ohos/
├── build-profile.json5      # 构建配置文件，定义签名、SDK版本
├── hvigorfile.ts            # 构建脚本 (类似 Gradle)
├── entry/                   # 主模块
│   ├── src/
│   │   ├── main/
│   │   │   ├── ets/
│   │   │   │   ├── entryability/
│   │   │   │   │   └── EntryAbility.ets  # [核心] Flutter 引擎的宿主
│   │   │   │   └── pages/
│   │   │   │       └── Index.ets         # 启动页面，承载 XComponent
│   │   │   ├── module.json5              # 模块配置 (权限、Ability声明)
│   │   │   └── resources/                # 鸿蒙原生资源 (图标、国际化)

核心修改点：
打开 ohos/entry/src/main/module.json5，这是应用的“身份证”。我们需要在这里配置网络权限，因为 Flutter 的网络请求最终会映射为鸿蒙系统的网络调用。

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:dependency_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO"
      }
    ]
  }
}

4. 架构设计：Clean Architecture + Feature-First

为了支撑大型鸿蒙应用的开发，我们采用高可维护性的架构。

4.1 目录结构规范

lib/
├── core/                   # 基础设施层
│   ├── constants/          # AppColors, AppStrings
│   ├── error/              # Failure, Exception 定义
│   ├── network/            # Dio 封装, 拦截器
│   └── utils/              # Logger, DateUtil
├── data/                   # 数据层 (Data Layer)
│   ├── datasources/        # 远程 API, 本地 DB
│   ├── models/             # DTO (Data Transfer Object)
│   └── repositories/       # Repository 实现
├── domain/                 # 领域层 (Domain Layer) - 可选，本项目简化合并至 Data
│   └── entities/           # 纯粹的业务实体
├── features/               # 业务功能层 (Presentation Layer)
│   ├── home/               # 首页模块
│   ├── search/             # 搜索模块
│   └── ...
└── main.dart               # 程序入口

4.2 依赖注入 (Dependency Injection)

使用 get_it 和 injectable 实现依赖注入，确保模块间的解耦。

final getIt = GetIt.instance;

void setupLocator() {
  // Core
  getIt.registerLazySingleton(() => Dio());
  getIt.registerLazySingleton(() => ApiClient(getIt()));

  // Services
  getIt.registerLazySingleton(() => GitcodeRemoteService(getIt()));
  
  // ViewModels / Bloc
  getIt.registerFactory(() => HomeViewModel(getIt()));
}

5. 基础依赖管理

在 pubspec.yaml 中引入支持鸿蒙的库。注意：部分包含原生代码的库（如 sqflite, webview_flutter）需要确认是否有鸿蒙版本适配。本项目主要使用纯 Dart 库或已适配的库。

dependencies:
  flutter:
    sdk: flutter
  
  # 网络
  dio: ^5.3.0
   
  # UI 工具
  google_fonts: ^5.1.0
  flutter_svg: ^2.0.7

6. 总结

本章我们完成了 Flutter 鸿蒙开发环境的“硬核”配置，并深入剖析了 ohos 目录的内部机理。不同于普通的 Flutter 项目，鸿蒙化项目要求开发者对 ArkTS 和 DevEco Studio 有一定的认知。

下一章，我们将构建基于 Dio 的高性能网络层，并解决鸿蒙系统特有的网络权限与抓包调试问题。