前言

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

做移动端开发，绑定第三方登录几乎是标配——Google、GitHub、微信、微博，用户不想注册新账号，开发者也不想自己维护一套密码体系。flutter_web_auth 就是干这个的：打开一个浏览器页面让用户登录，登录完了把结果通过 深度链接 回传给 App。

听起来简单，但跨平台实现起来每个平台都不一样。Android 用 Chrome Custom Tabs，iOS 用 ASWebAuthenticationSession，Web 用 window.open。现在要加上 OpenHarmony——用 openLink API 打开系统浏览器，用 Want 深度链接 接收回调。

这个系列 20 篇文章，把整个适配过程从头到尾讲清楚。

一、flutter_web_auth 是什么

1.1 一句话定义

flutter_web_auth 是一个 Flutter 插件，用于通过 Web 服务 对用户进行身份验证。最常见的场景是 OAuth2 登录。

1.2 核心 API

import 'package:flutter_web_auth/flutter_web_auth.dart';

final result = await FlutterWebAuth.authenticate(
  url: "https://my-auth-server.com/authorize",
  callbackUrlScheme: "myapp",
);

// result 是类似 "myapp://callback?code=abc123" 的字符串
final code = Uri.parse(result).queryParameters['code'];

就这么一个方法。传入认证 URL 和回调 Scheme，返回包含认证结果的回调 URL。

1.3 插件不做什么

插件做的事	插件不做的事
打开浏览器加载认证页面	构造 OAuth2 授权 URL
监听深度链接回调	用 code 换取 access_token
把回调 URL 返回给 Dart	管理 token 的存储和刷新
处理用户取消的情况	实现具体的登录 UI

💡 flutter_web_auth 只负责"打开浏览器"和"接收回调"这两步。OAuth2 流程中的其他步骤（构造 URL、换 token、刷新 token）需要开发者自己实现。

二、OAuth2 授权码流程中的角色

2.1 完整流程

用户 → App → 浏览器 → 授权服务器 → 浏览器 → App → 后端服务器

2.2 flutter_web_auth 的职责范围

                    flutter_web_auth 的职责
                    ┌──────────────────┐
用户点击登录 → App │→ 打开浏览器      │
                   │                  │
用户在浏览器登录   │  （等待回调）     │
                   │                  │
授权服务器重定向   │→ 接收回调 URL    │→ 返回给 Dart
                    └──────────────────┘
                    
App 用 code 换 token → 后端服务器 → 返回 access_token

2.3 参数对应关系

OAuth2 概念	flutter_web_auth 参数	示例
Authorization Endpoint	url	https://accounts.google.com/o/oauth2/v2/auth?...
Redirect URI 的 Scheme	callbackUrlScheme	com.googleusercontent.apps.xxx
Authorization Code	从 result 中解析	Uri.parse(result).queryParameters['code']

三、各平台实现策略总览

3.1 平台实现对比

3.2 OpenHarmony 的独特之处

OpenHarmony 的实现有几个和其他平台不一样的地方：

1. 需要 AbilityAware：获取 UIAbility 引用才能调用 openLink
2. 双重浏览器启动：openLink 失败时降级到 startAbility
3. 宿主应用必须手动集成：EntryAbility 中要手动调用 FlutterWebAuthPlugin.onNewWant(want)
4. 静态回调 Map：用 static callbacks 跨实例传递认证结果

// OpenHarmony 核心代码概览
export default class FlutterWebAuthPlugin implements FlutterPlugin, MethodCallHandler, AbilityAware {
  private static callbacks: Map<string, MethodResult> = new Map();
  
  // 打开浏览器
  context.openLink(url);
  
  // 接收回调（由 EntryAbility 调用）
  static onNewWant(want: Want): void {
    const uri = want.uri;
    // 从 callbacks Map 中找到对应的 MethodResult 并返回
  }
}

📌 与 secure_application 的对比：secure_application 不需要 AbilityAware，因为它只用 ApplicationContext 就够了。flutter_web_auth 需要 UIAbilityContext 来调用 openLink，所以必须实现 AbilityAware。

四、OpenHarmony 适配的意义

4.1 鸿蒙生态的第三方登录现状

登录方式	鸿蒙原生支持	Flutter-OHOS 支持
华为账号登录	✅ Account Kit	⚠️ 需要适配
微信登录	❌ 需要微信适配	❌
Google 登录	❌	⚠️ 通过 flutter_web_auth
GitHub 登录	❌	✅ 通过 flutter_web_auth
自建 OAuth	❌	✅ 通过 flutter_web_auth

4.2 flutter_web_auth 填补的空白

flutter_web_auth 是一个通用的 Web 认证桥梁。只要认证服务支持浏览器跳转 + URL Scheme 回调，就能通过这个插件接入。这意味着：

• 任何支持 OAuth2 的服务都能在 OpenHarmony 上使用
• 不需要等各个服务商单独适配鸿蒙
• 开发者可以用同一套代码支持所有平台

4.3 适配工作量评估

工作项	预估时间	难度
插件工程搭建	0.5天	低
FlutterPlugin + AbilityAware	0.5天	中
openLink 浏览器启动	0.5天	中
深度链接回调处理	1天	高
宿主应用集成文档	0.5天	低
测试与调试	1天	中
总计	4天	中

五、插件架构概览

5.1 整体架构

┌─────────────────────────────────────┐
│            Dart 层                   │
│  FlutterWebAuth.authenticate()      │
│  _OnAppLifecycleResumeObserver      │
│  MethodChannel("flutter_web_auth")  │
├─────────────────────────────────────┤
│          MethodChannel 通信          │
├─────────────────────────────────────┤
│          原生层（各平台）             │
│  ┌─────────┬──────────┬──────────┐  │
│  │ Android │ iOS/macOS│ OHOS     │  │
│  │ Chrome  │ ASWeb    │ openLink │  │
│  │ Custom  │ Auth     │ + Want   │  │
│  │ Tabs    │ Session  │ deeplink │  │
│  └─────────┴──────────┴──────────┘  │
└─────────────────────────────────────┘

5.2 数据流

1. Dart: FlutterWebAuth.authenticate(url, scheme)
       ↓ MethodChannel
2. Native: 存储 callbacks[scheme] = result
       ↓
3. Native: openLink(url) → 打开系统浏览器
       ↓
4. 用户在浏览器中完成认证
       ↓
5. 授权服务器重定向到 scheme://callback?code=xxx
       ↓
6. 系统通过深度链接唤起 App
       ↓
7. EntryAbility.onNewWant(want) → FlutterWebAuthPlugin.onNewWant(want)
       ↓
8. Native: callbacks[scheme].success(uri)
       ↓ MethodChannel
9. Dart: authenticate() 返回 uri 字符串

5.3 关键源码文件

文件	作用	行数
lib/flutter_web_auth.dart	Dart 层 API	55行
ohos/.../FlutterWebAuthPlugin.ets	OpenHarmony 原生实现	161行
ohos/index.ets	入口导出	5行
ohos/oh-package.json5	包配置	10行
ohos/src/main/module.json5	模块声明	11行

六、系列文章阅读路线

6.1 按主题分组

主题	篇目	适合读者
基础概念	第1-2篇	所有人
源码分析	第3-5篇	想深入理解的开发者
OpenHarmony 适配	第6-14篇	适配开发者（核心）
实战与对比	第15-17篇	应用开发者
进阶与展望	第18-20篇	架构师

6.2 推荐阅读顺序

1. 快速上手：第1篇 → 第16篇 → 第18篇
2. 深入理解：第1-5篇顺序阅读
3. 适配开发：第6-14篇顺序阅读
4. 全面掌握：第1-20篇顺序阅读

总结

本文介绍了 flutter_web_auth 插件的功能定位和 OpenHarmony 适配价值：

1. 核心功能：打开浏览器 + 接收深度链接回调，服务于 OAuth2 登录
2. OpenHarmony 实现：openLink 打开浏览器 + Want 深度链接回调
3. 独特挑战：AbilityAware 接口、宿主应用手动集成、静态回调 Map
4. 生态价值：填补鸿蒙第三方 OAuth 登录的空白

下一篇我们讲 OAuth2 协议基础——理解协议才能理解插件为什么这样设计。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

---

相关资源：

• flutter_web_auth GitHub
• flutter_web_auth Gitcode
• OAuth 2.0 规范 RFC 6749
• Chrome Custom Tabs
• ASWebAuthenticationSession
• OpenHarmony openLink API
• Flutter Plugin 开发指南
• 开源鸿蒙跨平台社区