主题
Aura 框架架构
一句话:一份 Rust 代码 = 三端的业务内核,一份 ReactLynx 代码 = 三端的界面,原生壳只负责起引擎和转发消息。
细节用法不在这里重复,按主题跳:quickstart(上手)、rust-side(路由/Context)、 frontend-side(bridge-client/主题/i18n)、core-guide(内核教程)、 wifi-bridge(可选传输能力)、extraction-map(抽取来源)。
1. 核心思想(先看这四句)
- 业务用 Rust 写一次,三端共用:Android / iOS / 鸿蒙加载的是同一份 Rust 代码编出来的库, 路由、存储、网络、文件、解析全在里面。
- 界面用 Lynx 写一次,三端共用:ReactLynx 渲染,一套页面三端跑。
- 原生只做壳:壳不写业务,只做四件事——起引擎、装页面、转发调用、提供系统能力。
- 双向通信:JS ⇄ Rust(调用 / 事件)、Rust ⇄ 系统(能力 / 回调);壳是中间人,但不做判断。
1.1 「一套 Rust 做三端」具体怎么落地
业务 crate(生成项目的 rust/)同时产出三种 crate-type:
toml
[lib]
crate-type = ["cdylib", "staticlib", "rlib"]| crate-type | 产物 | 谁用 |
|---|---|---|
cdylib | lib<name>.so | Android / 鸿蒙(运行期加载) |
staticlib | lib<name>.a | iOS(系统不允许随便加载自带动态库,只能静态链接) |
rlib | 普通 Rust 库 | 本机 cargo test、桌面 dev server |
三端加载的是同一个业务 crate,所以「同一个接口在三端行为一致」是结构保证的,不是靠人肉对齐。
入口符号是固定的,不随应用包名变化:
| 平台 | 固定入口 |
|---|---|
| Android | Java_com_aura_runtime_NativeBridge_nativeInit / nativeDispatch / nativeIsReady |
| iOS / 鸿蒙 | aura_core_init / aura_core_dispatch / aura_core_free_string / aura_core_is_ready |
业务 lib.rs 只需在末尾放导出宏(export_jni!() / export_c_abi!()), router 注册、初始化、JSON 分发都由框架包装好。
1.2 「原生只做壳」的边界
| 壳该做 | 壳不该做 |
|---|---|
引擎初始化(LynxEnv.init)、加载 bundle | 业务路由判断、业务文案、业务存储 |
把 JS 的 path + json 转给 Rust | 在 Kotlin/Swift/ArkTS 里拼业务参数 |
| 把 Rust 的请求转成系统调用 | 在壳里做页面跳转决策 |
| 生命周期、权限、安全区、前台服务 | 直接读写业务数据库 / 文件 |
判断标准很直接:BridgeModule.dispatch(path, params) 里看不到任何业务路径字符串, 它只做「转发 + 错误兜底」。
1.3 双向通信有四条边
text
┌────────────────── App 进程(三端一致)──────────────────┐
JS 线程 │ │
ReactLynx 页面 ───┼──① dispatch(path, json)──▶ 原生桥 ──②──▶ Rust 业务内核 │
▲ │ (JNI/C ABI/NAPI) │ │
└────────────┼──③ emit(event, payload) ◀───────┘ │ │
│ │ │
│ ④ 系统能力(外链/通知/日志/长时任务)◀─────────┘ │
└────────────────────────────────────────────────────────┘
▲ ⑤ 生命周期(init / 通知栏停止按钮)
└──────────── 系统| 边 | 方向 | 用途 | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|
| ① 同步调用 | JS → Rust | 绝大多数业务请求 | NativeModules.Bridge.dispatch() → JNI | C ABI aura_core_dispatch | NAPI dispatch |
| ② 异步调用 | JS → Rust | 耗时操作不卡 UI | dispatchAsync(Kotlin 线程池) | C ABI + 业务自起线程 | NAPI(同左) |
| ③ 事件推送 | Rust → JS | 进度 / 状态广播 | JNI NativeBridge.onNativeEvent → Lynx sendGlobalEvent | AuraHost.emit | napi_threadsafe_function |
| ④ 系统能力 | Rust → 系统 | 外链、通知、日志、震动、长时任务 | JNI 静态方法 | AuraHost 函数指针 | NAPI threadsafe |
| ⑤ 生命周期 | 系统 → Rust | 传 dataDir、通知栏「停止传输」 | nativeInit / dispatch("/wifi/stop") | aura_core_init | NAPI init |
要点:
- 只有 ① 是同步返回的,其余都是单向或异步。所以 handler 里不能做秒级阻塞(用 ②,或先返回再 ③ 推送结果)。
- ③④ 的共同难点是线程:Rust 可能在任何线程回调,JS/系统调用必须在「对的线程」上执行(见 §2)。
- 业务代码只感知两件事:
bridge.call(path, params)(①②)和ctx.emit(event, payload)(③); 它不知道也不需要知道当前是 JNI 还是 C ABI。
1.4 为什么不是「三端各写一套原生」
| 维度 | 三端各写一套 | Aura |
|---|---|---|
| 业务逻辑 | 3 份,行为容易漂移 | 1 份,三端共用 |
| 业务单测 | 依赖真机 / 模拟器 | cargo test 直接跑 |
| 新增一个接口 | 改 3 处 + 3 次联调 | 加一个 #[route] |
| 系统差异 | 散落在各处 | 收敛到 Platform trait |
| 换 Lynx 版本 / 适配新系统 | 3 套壳各改 | 只改壳,不碰业务 |
2. 线程与进程模型
打包后(App):Rust 和 Lynx 在同一个进程里,但不在同一线程。
| 执行体 | 说明 |
|---|---|
| JS / UI 线程 | 调 dispatch 时会同步等待 Rust 返回;重活必须走 dispatchAsync |
| Rust 调用线程 | 同步分发就在调用方线程上跑;异步分发用线程池 |
| Rust 后台线程 | 例如 wifi-bridge 的 HTTP 服务(自带 tokio runtime),或业务起的线程 |
| 系统主线程 | 前台服务启停、通知、requestPermissions 等必须在主线程做的事 |
跨线程的两条铁律:
- Rust → JS:必须投递回 JS 线程。Android 由 Kotlin 侧(
sendGlobalEvent)保证; 鸿蒙必须走napi_threadsafe_function,不能直接 call JS 函数。 - Rust → 系统:Android 用
attach_current_thread后调静态方法;需要 UI 线程的(如申请权限) 由 Kotlin 侧自己runOnUiThread,Rust 不关心。
dev 模式(桌面):Rust 是独立进程(aura-dev-server,默认 3456),前端通过 HTTP 调; 此时业务代码完全一样,只是桥从 JNI 换成了 HTTP。这就是为什么 dispatch_json 被抽成独立 crate (aura-bridge):同一套 JSON 契约,三种传输载体。
3. 分层与仓库地图
text
业务层(生成的项目) frontend/src/pages·components rust/src/lib.rs(build_router)
│ │
前端内核 packages/ @aura/bridge-client ─────────┐ │
@aura/theme / i18n / ui │ │
│ │ │
传输载体 Lynx NativeModule / HTTP ◀────┘ │
│ │
Rust 内核 crates/ aura(路由·Context·中间件·State)◀──────┘
aura-bridge(JSON ↔ 分发,三条载体共用)
aura-platform(Platform trait)
aura-settings / aura-storage
aura-native(JNI / C ABI 固定导出)
aura-dev-server / aura-wifi-bridge
│
原生壳 platforms/ Android(JNI) / iOS(C ABI) / 鸿蒙(NAPI)| 目录 | 内容 |
|---|---|
crates/ | Rust 内核(9 个 crate,见上) |
packages/ | 前端内核(bridge-client / theme / i18n / ui) |
platforms/ | 三端原生壳模板,生成时整体拷进项目 |
build/ | 三端构建脚本与手册,生成时整体装配进项目的 framework/build/ |
templates/config/ | 项目配置模板(env / version / store / signing),生成时复制到项目根 config/ |
templates/app/ | 项目骨架:frontend/ + rust/ + docs/ + 根配置文件 |
features/<name>/ | 可选能力:feature.json 清单 + 注入片段 + 资源(如 wifi-bridge 的 wifi-web 工程) |
scripts/create.mjs | 生成器:占位符替换、core / link 模式、按 feature 注入 |
examples/demo-app | 内核自检样例 |
单向依赖:业务 → core;内核永不反向引用业务。
4. 一次调用到底发生了什么
text
前端 bridge.call('/library/list', { limit: 20 })
│
├─(App) NativeModules.Bridge.dispatch(path, json)
│ ├─ Android: JNI → Java_com_aura_runtime_NativeBridge_nativeDispatch
│ ├─ iOS: C ABI → aura_core_dispatch
│ └─ 鸿蒙: NAPI 包装层 → aura_core_dispatch
│
└─(dev) POST http://<host>:3456/dispatch { path, params }
Rust aura_bridge::dispatch_json(aura, path, payload)
① 解析 params(空串 / {} = 无参;非法 JSON → 400 响应)
② 路由匹配(宏路由与显式注册共用一张路由表)
③ 构造 Context(params / platform / state / lang)
④ 依次穿过中间件
⑤ handler(ctx) → Response
返回 {"ok":true,"code":200,"data":...,"message":"success"}响应信封统一为 { ok, code, data, message };bridge-client 在 ok=false 时抛 BridgeError。
路由两种注册方式:
| 方式 | 场景 |
|---|---|
#[route("/path")] + link_routes! | 异步、需要 Context;编译期用 inventory 收集 |
aura.route("/path", handler) | 显式注册,适合简单 JSON 转换或控制顺序 |
iOS 是 staticlib,
inventory的链接期收集可能被裁掉。模板用link_routes!显式引用; 仍 404 时加-force_load或改用显式注册。
5. 平台抽象:差异只允许出现在一个 trait
aura-platform 定义宿主能力,内核只调 trait,不出现任何平台 API:
| 能力 | 默认 | Android | iOS | 鸿蒙 |
|---|---|---|---|---|
app_paths() | 当前目录 | JNI 传 dataDir | C ABI | NAPI |
log() | stderr | logcat | os_log | hilog |
emit() | 丢弃 | JNI 静态方法 | AuraHost.emit | NAPI threadsafe |
open_url() | 不支持 | Intent | UIApplication.open | startAbility |
set_transfer_server_active() | 空实现 | 前台服务 + 通知 | 未实现 | 长时任务 |
vibrate() / set_keep_screen_on() | 空实现 | — | — | — |
新增一项能力的四步:
Platformtrait 加带默认空实现的方法(三端不实现也能编译);- Android:
aura-native里加 JNI 调用 → 固定类com.aura.runtime.NativeBridge上的@JvmStatic方法; - iOS / 鸿蒙:
AuraHost(crates/aura-native/include/aura_core.h)末尾追加函数指针字段; - 各端壳接实现。
ABI 只能追加,不能重排——字段顺序错一位就是三端随机崩。
6. 为什么入口符号要「固定」
应用包名是参数化的(com.acme.xxx),但 JNI 符号不能跟着变,否则框架没法预置导出。 所以约定:
- Kotlin 侧永远有一个
com.aura.runtime.NativeBridge,不随业务包名重命名; - 业务代码通过
BridgeModule间接使用它,业务包名可以随便改; - iOS / 鸿蒙走 C ABI,天然与包名无关;
- 鸿蒙再多一层
aura_napi.cpp:Rust 的 cdylib 没有napi_module_register,不能直接被 ArkTS import, 必须包一层真正的 NAPI 模块。
这三条合起来,才让「壳可以模板化、生成器只改包名/应用名」成立。
7. 前端内核包与三条硬约束
| 包 | 职责 |
|---|---|
@aura/bridge-client | 通道探测(native / http)、调用、超时、错误、事件订阅 |
@aura/theme | 亮暗语义 token |
@aura/i18n | 语言包、插值、切换订阅(框架不内置业务文案) |
@aura/ui | TabBar / SubPage / ConfirmDialog,类名统一 aura- 前缀 |
@aura/ui发 TS 源码,由项目 Rspeedy 编译。预编译成 JS 会丢style/className/bindtap。node_modules里的 CSS 会被 Rspeedy 抽成独立文件,Lynx 运行时不加载。 生成项目会把 UI 样式复制到frontend/src/styles/aura-ui.css并在App.tsximport。- Lynx 样式的
px是逻辑像素(dp)。原生 inset 是物理像素,传给前端前必须除以density。
另外:Lynx 运行时没有页面 origin,相对路径 fetch 会直接抛异常 —— 真机调试要把电脑 IP 编进 bundle。
8. 项目生成与形态
bash
# 交互式向导:逐项确认,回车取 app.config.json 里的默认值
node scripts/create.mjs
# 非交互(CI / 脚本):全部取默认值
node scripts/create.mjs ../my-app --yes
# 按需覆盖这一次的取值
node scripts/create.mjs ../my-app --name "我的应用" --bundle-id com.acme.myapp \
--lib my_core --features wifi-bridge --web vue- 按
app.config.json+ 命令行参数替换__XXX__占位符(包名、库名、品牌色、功能开关…); --features按需注入(wifi-bridge 会加 Rust 依赖、/wifi/*路由、wifi-web/、前台服务与 manifest 权限);core(默认):把crates/+packages/复制进项目framework/core/,自包含、可离线、可搬目录;link:path 依赖指回本机框架(此时项目只有framework/build/),仅框架开发者联调。
text
my-app/
├── frontend/ ReactLynx(Rspeedy)
├── rust/ 业务 crate:build_router + link_routes + 导出宏
├── framework/ 框架源码:core/(内核副本)+ build/(构建脚本)+ README.md
├── config/ 项目配置:env / version / store / signing
├── platforms/ 三端原生壳(已替换包名)
├── wifi-web/ 可选:局域网传输 Web
└── dist/ 构建产物与中间文件(不入库)结构对应 §10.1 的目标布局,已由生成器落地。
9. 三端壳职责
| 职责 | Android | iOS | 鸿蒙 |
|---|---|---|---|
| 引擎初始化 | LynxEnv.inst().init()(必须,否则白屏) | Lynx 初始化 | Lynx 初始化 |
| 页面容器 | MainActivity 全屏 LynxView | MainViewController | LynxPage |
| bundle 加载 | assets + AppTemplateProvider + renderTemplateUrl | 同左 | 同左 |
| 桥接 | JNI(固定 com.aura.runtime.NativeBridge) | C ABI(AuraHost) | NAPI 包装 + threadsafe function |
| 系统栏 | edge-to-edge,inset → globalProps(dp) | 系统自动 | 系统自动 |
| 调试 | 原生调试浮层(默认隐藏,i 按钮) | Xcode 日志 | hilog |
Android
targetSdk 35强制 edge-to-edge:壳不再给内容让位,安全区由SubPage.safeAreaTop/TabBar.safeAreaBottom消化;position: fixed的弹窗铺满整屏。
10. 构建与发布
text
config/env/{dev,prod}.json 应用名后缀 / 包名后缀 / buildType / 混淆 / Rust profile
config/version.json 三端版本唯一来源
config/store/ 商店目标 / 文案 / 图标素材
config/signing/ 签名与导出材料(*.example 模板,本地副本 gitignore)
framework/build/scripts/ build-* / preflight / package-stores / gen-icons / sync-version / archive
dist/<platform>/<env>/<version>/ 安装包 + SHA256SUMS + BUILD_INFO.txtdev与prod可同机共存(包名后缀.dev);prod缺正式签名直接失败(本地验证可显式ALLOW_DEBUG_SIGNING=1);- 产物按商店区分:Play → AAB,国内商店 → 分 ABI / universal APK,App Store → IPA + dSYM。
10.1 配置归属与升级边界(已实施)
原 build/ 里混了三类东西:执行层(scripts/)、默认值与环境(env/、version.json、stores.json、metadata/)、 项目数据(config/ 签名材料)。其中大量值本来就该由项目决定,和「build/ 是框架资产、可整体替换」的定位冲突; 一旦执行层收成不可见形态(CLI / npm 包),项目配置就没有合法落点。
四条原则:
- 代码与配置分离:框架源码目录(
core/、build/)里不放项目数据。 - 升级语义按目录定死,不靠 README 口头约定。
- 机密只引用不内联:密码 / 证书不进受版本管理的配置文件。
- 校验逻辑单份实现:
config.mjs的 normalize / validate 只留一份,生成器与项目共用。
目标结构:
text
项目根
├── app.config.json # 身份与构建目标:app / build / generator / runtime
├── config/ # 项目资产(永不覆盖)
│ ├── env/{dev,prod}.json
│ ├── version.json
│ ├── store/{stores.json,listing.json,icon.json,assets/}
│ └── signing/{android,ios,harmony}/ # 实体 gitignore,仓库只留 *.example 与 README
├── framework/ # 只读框架源码(整体替换,core 与 build 同版本)
│ ├── core/ # crates + packages(内核副本)
│ ├── build/ # 构建脚本(原 build/scripts)
│ └── README.md # 内核教程(原 core/README.md)
├── platforms/ # 三端壳(项目可改)
├── frontend/ rust/ # 业务
└── dist/ # 产物(不入库)core/ 与 build/ 合并进 framework/ 的理由:两者升级节奏本就该一致, 分开会导致「core 整体替换、build 手动吸收」的版本漂移;合并后升级只做一件事——整体替换 framework/。 platforms/ 不进 framework/:它是项目可改的壳,收进去会破坏「framework 只读」的语义。
app.config.json 留在根目录(已定):它是声明式入口(决定生成什么、构建什么), 定位接近 package.json,与 config/ 里的数据型配置不同类;留在根目录既符合 package.json / tsconfig.json / Expo app.config.js 的惯例,也让生成器、未来 CLI、IDE 无需额外参数定位。 config/ 只放 env、version、store、signing 这类项目数据。
- 已实施:
app.config.json增加$schema,指向framework/config.schema.json(core 模式), 编辑器即可补全字段、标红未知字段;link 模式不写(避免指向不存在的路径)。
归属与升级矩阵:
| 路径 | 归属 | 升级行为 | 项目可编辑 |
|---|---|---|---|
app.config.json | 项目 | 永不覆盖 | ✅ |
config/** | 项目 | 永不覆盖 | ✅ |
framework/** | 框架源码(内核 + 构建脚本) | update-core.mjs 整体替换 | ❌ |
platforms/** | 项目壳 | 手动吸收框架改动 | ✅ |
frontend/**、rust/** | 业务 | 不受影响 | ✅ |
dist/** | 产物 | 不参与升级 | 生成物 |
合并后必须同步改的路径:
| 位置 | 现在 | 合并后 |
|---|---|---|
| Rust 依赖 | ../core/crates/* | ../framework/core/crates/* |
前端 @aura/* | file:../core/packages/* | file:../framework/core/packages/* |
| 脚本定位根 | dirname/../.. | 再上一层 |
package.json | bash build/scripts/* | bash framework/build/scripts/* |
| 生成器 | 复制 core/ | 组装 framework/{core,build} |
| 升级脚本 | 替换 core/ | 替换整个 framework/(不碰 config/、platforms/) |
读取约定:
- 所有脚本只通过
framework/build/scripts/config.mjs暴露的路径 / 值接口取配置,禁止硬编码config/env/...这类字符串。 - 覆盖优先级:命令行参数 > 环境变量 >
config/>app.config.json> 框架默认值。
机密约定:
- 受版本管理的配置只写路径或环境变量名,例如
"keystore": "config/signing/android/release.jks"、"storePasswordEnv": "ANDROID_KEYSTORE_PASSWORD"。 - 证书、描述文件、API Key 实体一律 gitignore。
版本策略:
schemaVersion为 3;低于 3 的旧结构(项目数据在build/)直接报错,不做静默回退 ——旧布局的项目已不存在,留着兼容分支只会让「读出错值」比「报错」更难排查;- 高于 3 时报错并提示先升级框架;
create.mjs只按当前结构生成。
与「不弹出」的关系:
- 执行层不弹出时,
framework/由 npm 包(如@aura/build+ 预构建内核)提供,项目只保留app.config.json+config/+frontend/+rust/+platforms/; - 配置位置与是否弹出无关:能隐藏的只有
framework/,配置永远在项目根。
实施记录(已完成):
core/+build/合并为framework/,同步 Rust / 前端依赖路径与脚本定位;config.mjs抽出路径解析(resolveProjectPaths);doctor/generate-check覆盖新结构;- 文件迁移,同步
create.mjs与templates/app,跑通生成器金丝雀; - 更新 README、quickstart、
build/README.md中的路径说明; - 确认没有旧布局项目后,删除
build/旧路径回退与旧 config 结构兼容分支(schemaVersion < 3 直接报错)。
10.2 后续优化清单(P0 / P1 / P2 均已实施或已评估)
按收益排序,P0 影响迭代速度,P1 补工程化能力,P2 清质量与文档债务。 逐条执行清单见 layout-migration-checklist.md。
P0 · 迭代速度
- 生成器拆分(已实施):
scripts/create.mjs由 772 行降到约 250 行, 逻辑拆到scripts/lib/{args,ui,fs-utils,features,replacements,assemble}.mjs; 旧/新生成结果逐文件 diff 一致(仅时间戳不同)。 - feature 目录化(已实施):
features/wifi-bridge/{feature.json, snippets/, web/}声明 crate 依赖、 占位符片段、资源目录与钩子,生成器按清单装配(scripts/lib/features.mjs+assemble.mjs)。 新增 feature 只需加目录与feature.json,不改生成主流程。 后续可把 privacy-consent / splash-ad 也迁入同一清单。
P1 · 工程化补齐
- CLI 入口(已实施):根
package.json注册bin: { aura }并提供pnpm aura脚本, 支持aura create <目录>/aura check,参数与既有脚本一致(scripts/cli.mjs只做转发)。 - 配置强校验(已实施):
config.mjs新增validateConfig(),config:check(sync-config --check)按严格模式校验类型、范围与枚举,失败退出码 1; 普通读取仍只告警。JSON Schema 源文件在仓库根schema/app.config.schema.json, core 模式生成时装配到项目的framework/config.schema.json,并在app.config.json写"$schema": "./framework/config.schema.json";link 模式两者都不带。 - 发布入口统一(已实施):
scripts/release.mjs统一package.json/app.config.json/Cargo.toml(含aura*依赖)的版本号,提交后打vX.Y.Ztag;--check校验四处版本与最新 tag 是否一致,--push才推送。push.sh --tag保留为临时标记,正式发布走pnpm aura release;core/Cargo.toml的版本改为从框架Cargo.toml读取,不再写死0.1.0。 - 构建脚本上移(已实施):
templates/app/build/的源文件移到仓库根build/(与crates/、packages/并列), 生成时由installBuildScripts()装配进项目的framework/build/(脚本ROOT按dirname/../../..推算);templates/app/只保留frontend/、rust/、docs/与骨架文件。scripts/lib/replacements.mjs与create.mjs改为从根build/scripts/config.mjs导入。 §10.1 合并framework/时,装配目标再从build/改成framework/build/(已实施)。
P2 · 质量与债务
- 金丝雀矩阵(已实施):
generate-check.mjs按「默认 / 全关 / 仅 wifi-bridge / 仅 privacy-consent / link 模式」五种组合各生成一个项目,分别断言 feature 开关落点(前端常量、Rust 常量、wifi-web 工程、 Android 清单权限与服务)、三端默认值、$schema写入策略、依赖引用完整性与占位符残留; 默认组合还会跑一次update-core升级再校验,纯静态生成,秒级完成。 splash-ad 需要素材地址才会真正启用,默认配置没有imageUrl,目前断言「无素材不启用」。 金丝雀不编译:全量cargo check在 Intel Mac 上代价很高,且使用者生成项目后本来就会pnpm dev编译一次。折中是静态校验rust/Cargo.toml的path依赖、frontend/package.json的file:依赖、framework/core的 workspace members 都真实存在——生成器改路径失效时, 这是最先炸的地方,而查目录成本几乎为零。 - 自检职责收敛(已评估:保留):
examples/demo-app与金丝雀不重叠。demo-app 走cargo run,实际执行宏路由、register、中间件、State、i18n、settings 落盘、storage 打开与 bridge 分发的正常 / 错误 / 404 三种结果,是内核运行时行为的唯一自检;金丝雀只做静态生成检查, 不cargo、不加载内核。删除 demo-app 会让「内核 API 还能跑」失去回归入口。 - 文档债务(已实施):
docs/extraction-map.md已标记为历史文档,现行结构以本文为准; 根目录git.md是本地草稿,已被.gitignore忽略,不入库。
以上条目不影响 §10.1 的规范结论;P0 / P1 / P2 均已实施或已评估。
11. 可选能力:wifi-bridge
它不参与主桥,而是一个独立的 axum 服务(默认 30000),与 App 通过 Platform 耦合:
text
App 前端 ──/wifi/start──▶ aura 路由 ──▶ WifiBridge::start(port)
├─ 起 axum(页面 `/`,接口 `/bridge/*`)
├─ Platform::set_transfer_server_active(true, url)
└─ Android 前台服务 / 鸿蒙长时任务(后台保活 + 通知)
电脑浏览器 ──http://<手机IP>:30000──▶ 传输页面(wifi-web 产物,编译期嵌入 Rust)详见 wifi-bridge.md。
12. 常见扩展怎么做
| 想加什么 | 改哪里 |
|---|---|
| 新接口 | 业务 rust/src/*.rs 加 #[route](或 aura.route),前端 bridge.call |
| 新平台能力 | Platform trait 加默认方法 → 三端实现(§5) |
| 新 UI 组件 | packages/ui/src/<name>/ 并导出;业务项目同步 src/styles/aura-ui.css |
| 新前端包 | packages/<name>/ + workspace;发 TS 源码时 main/types 指向 src/index.ts |
| 新生成开关 | app.config.json + create.mjs 的 replacements |
13. 验证与门禁
bash
cargo test # 内核单测
cargo run -p demo-app # 最小业务自检
pnpm -r build # 前端内核包
pnpm --dir frontend typecheck # 业务前端类型(生成项目内)
pnpm preflight # 版本 / 签名 / 架构 / 商店元数据改 crates/ 或 packages/ 后,要重新生成项目(或同步 core/)跑一遍 pnpm dev + pnpm build:android,才算端到端验证。
14. 已知边界
| 边界 | 说明 |
|---|---|
| iOS 后台 | 系统不允许本地 HTTP 服务长期后台运行,beginBackgroundTask 仅约 30 秒 |
| Lynx CSS | 全局无作用域,组件类名必须带前缀(aura-) |
position: fixed | 提升到根节点,坐标基准是屏幕而非父容器 |
| 宏路由 + iOS staticlib | 依赖 inventory,需 link_routes! 或 -force_load |
| dev 模式 bridge | 真机必须注入电脑局域网 IP,不能用相对路径 |