主题
Aura Core 内核教程
framework/core/ 是 lynx-aura 框架内核在项目中的自包含副本,包含 Rust crates、前端 packages、workspace 配置; 本文档位于 framework/README.md。
项目业务代码放在
frontend/与rust/,不要放进framework/。scripts/update-core.mjs会整体替换framework/(含本文档);通用修复应回流框架仓库。
1. 内核解决什么问题
Aura 将同一个 Rust 业务内核接到三种运行环境:
- 桌面开发:ReactLynx → HTTP →
aura-dev-server→Aura - Android:ReactLynx → NativeModule → JNI →
Aura - iOS / HarmonyOS:ReactLynx → NativeModule → C ABI / NAPI →
Aura
业务只实现路由和平台无关逻辑。传输协议、统一响应、平台入口、设置存储基座、主题与 UI 组件由内核提供。
一次请求的路径如下:
text
bridge.call('/app/ping', params)
│
▼
HTTP / JNI / C ABI
│
▼
aura-bridge:JSON 字符串 ↔ DispatchRequest
│
▼
Aura::dispatch
├─ 按 path 找路由
├─ 构造 Context
├─ 执行中间件
└─ 调用业务 handler
│
▼
Response { ok, code, data, message }
│
▼
bridge.call() 拆信封,返回 data 或抛 BridgeError2. 目录与依赖方向
Rust crates
| Crate | 职责 | 业务何时使用 |
|---|---|---|
aura | 路由、Context、中间件、State、Response、i18n | 几乎每个 Rust 业务模块 |
aura-macros | #[route] proc-macro 与 inventory 收集 | 通过 aura::route 间接使用 |
aura-platform | AppPaths 与 Platform 宿主能力抽象 | 文件目录、日志、事件、平台能力 |
aura-bridge | JSON 请求/响应与内核分发适配 | 通常由原生入口和 dev-server 使用 |
aura-settings | 内存/JSON 文件键值设置 | 应用配置持久化 |
aura-storage | SQLite 连接、路径与迁移入口 | 数据库存储 |
aura-native | 固定 JNI / C ABI 导出宏 | 业务 lib.rs 末尾保留导出宏 |
aura-dev-server | 桌面 HTTP 开发服务 | rust/src/main.rs 使用 |
aura-wifi-bridge | 可选局域网文件传输 | 仅启用 wifi-bridge 时 |
前端 packages
| 包 | 职责 |
|---|---|
@aura/bridge-client | native / http 自动检测、路由调用、错误与事件订阅 |
@aura/theme | 亮暗主题与语义设计 token |
@aura/i18n | 业务语言包、插值、语言切换订阅 |
@aura/ui | TabBar、SubPage、ConfirmDialog 等基础组件 |
依赖方向必须保持单向:
text
业务 frontend ──> framework/core/packages ──> Lynx
业务 rust ──> framework/core/crates ──> 三端原生壳内核不得 import 或引用业务 crate、业务语言包和业务页面。
3. Rust 路由
宏路由:异步、需要 Context 时使用
rust
use aura::{Context, Response, route};
use serde_json::json;
#[route("/user/profile")]
async fn profile(ctx: Context) -> Response {
let user_id = ctx
.param("userId")
.and_then(|value| value.as_i64())
.unwrap_or(0);
if user_id <= 0 {
return Response::err(400, "userId 必须是正整数");
}
Response::ok(json!({
"id": user_id,
"path": ctx.path(),
}))
}在业务 crate 中显式链接所有宏路由:
rust
aura::link_routes!(init: ping, profile);
pub fn build_router() -> Aura {
init(); // 必须在 Aura::new() 之前
let aura = Aura::new(); // 自动收集 inventory 中的 #[route]
aura
}link_routes! 用于防止 iOS staticlib 链接器裁掉未被显式引用的 object。Android 和鸿蒙通常不受影响,但三端应共用同一份声明。
显式同步路由:简单 JSON 转换时使用
rust
use aura::{Aura, BridgeError};
use serde_json::{json, Value};
pub fn build_router() -> Aura {
let mut aura = Aura::new();
aura.register("/math/double", |params: Value| {
let value = params.get("value").and_then(|v| v.as_i64()).unwrap_or(0);
Ok(json!({ "result": value * 2 }))
});
aura.register("/math/conflict", |_| {
Err(BridgeError::Failed {
code: 409,
message: "冲突".into(),
})
});
aura
}选择建议:
- 需要
await、平台能力、i18n、类型化 State:用#[route]+Context。 - 纯同步 JSON 输入输出:用
aura.register()。 - 动态选择异步 handler:也可用
aura.route("/path", handler)。
4. Context 与类型化 State
参数
Context 的参数来自 bridge.call(path, params) 的第二个参数:
rust
let raw: Option<serde_json::Value> = ctx.param("name");
let name: Option<String> = ctx.param_as("name");
#[derive(serde::Deserialize)]
struct CreateInput {
name: String,
enabled: Option<bool>,
}
let input: CreateInput = match ctx.param_many() {
Ok(value) => value,
Err(message) => return Response::err(400, message),
};常用方法:
| 方法 | 返回 | 用途 |
|---|---|---|
ctx.path() | &str | 当前路由 |
ctx.param(key) | Option<Value> | 取原始 JSON 参数 |
ctx.param_as<T>(key) | Option<T> | 反序列化单个参数 |
ctx.param_many<T>() | Result<T, String> | 反序列化整个参数对象 |
ctx.body() | Option<Arc<Vec<u8>>> | 二进制请求体 |
ctx.platform() | &dyn Platform | 宿主能力 |
参数缺失或类型错误时,优先返回明确的 400 响应,不要让错误默默变成默认值。
共享状态
State 按 Rust 类型存取,不是字符串 key-value:
rust
#[derive(Default)]
struct Counter {
value: std::sync::atomic::AtomicU64,
}
pub fn build_router() -> Aura {
let mut aura = Aura::new();
aura.manage(Counter::default());
aura
}
#[aura::route("/counter/next")]
async fn next(ctx: aura::Context) -> aura::Response {
let Some(counter) = ctx.state::<Counter>() else {
return aura::Response::err(500, "Counter 未注入");
};
let value = counter.value.fetch_add(1, std::sync::atomic::Ordering::SeqCst) + 1;
aura::Response::ok(serde_json::json!({ "value": value }))
}State 适合进程内共享服务与状态。进程重启后仍需保留的数据应使用设置或数据库。
5. 响应与中间件
统一响应
rust
Response::ok(json!({ "id": 1 }));
Response::err(400, "参数错误");线上结构:
json
{
"ok": true,
"code": 200,
"data": { "id": 1 },
"message": "success"
}约定:
- 成功固定
ok: true、code: 200、message: "success"。 - 业务失败使用非 200 code,并给出可诊断的 message。
- 路由不存在返回 404;传输或内核失败由对应层转换为错误信封。
bridge.call<T>()成功时只返回data,失败时抛BridgeError(code, message)。
中间件
中间件按洋葱模型包裹 handler,可用于日志、鉴权、耗时统计和统一错误处理:
rust
use aura::{BridgeError, Context, Middleware, Next, Response};
struct RequestLog;
#[async_trait::async_trait]
impl Middleware for RequestLog {
async fn handle(&self, ctx: Context, next: Next<'_>) -> Result<Response, BridgeError> {
let path = ctx.path().to_string();
let started = std::time::Instant::now();
let result = next.run(ctx).await;
eprintln!("{path} cost {:?}", started.elapsed());
result
}
}
// 在 build_router() 中:
// aura.use_middleware(RequestLog);自定义中间件使用 async_trait 时,业务 crate 需要自行添加 async-trait 依赖。内置的 logger / timeout 中间件也可直接查看 crates/aura/src/middleware.rs 后使用。
6. i18n 与平台事件
Rust 语言包
I18nBundle 适合将业务 JSON 编进二进制:
rust
let i18n = aura::I18nBundle::new("zh-CN");
i18n.load_json("zh-CN", include_str!("../locales/zh-CN.json"))?;
i18n.load_json("en-US", include_str!("../locales/en-US.json"))?;
aura.i18n(i18n);handler 中:
rust
let current = ctx.lang();
let text = ctx.tr("app.name");
let greeting = ctx.tr_with("app.greeting", &[("name", "Lynx")]);
ctx.set_lang("en-US");框架不内置业务文案,语言包及 key 由项目维护。
给前端发原生事件
rust
ctx.emit("download.progress", Some(serde_json::json!({
"id": "task-1",
"percent": 50,
})))?;前端:
tsx
bridge.on('download.progress', (_event, payload) => {
const data = JSON.parse(payload);
console.log(data.percent);
});
// 不再需要时
bridge.off('download.progress');事件目前只在 native 模式有效;HTTP dev 模式下不要依赖事件完成关键流程。
7. 设置、存储与平台能力
JSON 文件设置
rust
use aura_settings::{FileSettings, SettingsStore};
let path = ctx.platform().app_paths().data_dir.join("settings.json");
let mut settings = FileSettings::load(path)
.map_err(|error| error.to_string())?;
settings.set_and_save("theme", "dark")
.map_err(|error| error.to_string())?;
let theme = settings.get("theme"); // Option<String>MemorySettings:测试和临时状态。FileSettings::set():只改内存,之后需调用save()。set_and_save():修改并立即原子落盘。- 值统一是字符串;结构体可由业务侧序列化为 JSON 字符串。
SQLite
rust
use aura_storage::{open, migrate, StorageConfig};
let config = StorageConfig::from_paths(ctx.platform().app_paths(), "app.db");
let db = open(&config).await.map_err(|error| error.to_string())?;
// Migrator 是业务项目实现的 sea_orm_migration::MigratorTrait 类型:
// migrate::<Migrator>(&db).await.map_err(|error| error.to_string())?;内核只负责数据库位置、连接和迁移执行。连接默认启用 WAL、busy_timeout=5s、 foreign_keys=ON 与 4 条连接池,适合 JNI 线程 + 后台任务并发访问。 aura_storage::ping(&db) 可用于健康检查。业务项目负责 SeaORM entity、表结构、DAO 与连接生命周期。不要把数据库文件写到任意绝对路径,应使用 AppPaths。
Platform
rust
let paths = ctx.platform().app_paths();
ctx.platform().log("info", "sync", "started");
ctx.platform().vibrate(30);
ctx.platform().set_keep_screen_on(true);
ctx.platform().open_url("https://example.com")?;Platform 的默认可选能力可能返回 Unsupported 或静默忽略,调用方应根据产品需要处理。桌面 NullPlatform 的目录在系统临时目录,不应把它当作正式持久化位置。
8. 前端 bridge-client
初始化与调用
tsx
import { BridgeError, createBridgeClient } from '@aura/bridge-client';
const bridge = createBridgeClient({ bridgePort: 3456 });
const mode = await bridge.init(); // native | http | disconnected
try {
const profile = await bridge.call<{ id: number }>('/user/profile', {
userId: 1,
});
console.log(profile.id);
} catch (error) {
if (error instanceof BridgeError) {
console.error(error.code, error.message);
}
}- 真机自动使用
NativeModules.Bridge。 - 浏览器开发使用 HTTP dev-server。
- 每次调用可重新检测 native 环境,避免模块加载过早造成误判。
- 手机通过 HTTP 联调电脑时:
await bridge.setBridgeHost('192.168.1.100')。
诊断通道问题时可读取:
tsx
console.log(bridge.getMode());
console.log(bridge.diagnostics());theme / i18n / ui
tsx
import { createTheme, lightTheme } from '@aura/theme';
import { createI18n } from '@aura/i18n';
import { SubPage, TabBar } from '@aura/ui';
const theme = createTheme(lightTheme, { brand: '#2F7DF6' });
const i18n = createI18n({
defaultLang: 'zh-CN',
packs: { 'zh-CN': { 'home.title': '首页' } },
});主题优先使用 background / surface / text / textSecondary / brand 以及 spacing、radius、fontSize token。i18n 语言包由业务传入;subscribe() 返回取消订阅函数。
9. 三端原生入口
业务 rust/src/lib.rs 末尾的两个导出宏不能删除:
rust
aura_native::export_jni!();
aura_native::export_c_abi!();它们分别提供:
- Android:
Java_com_aura_runtime_NativeBridge_* - iOS / HarmonyOS:
aura_core_*
业务包名可以变化,固定桥接符号不变。新增路由不需要修改 JNI 或 Swift / ArkTS;只有新增原生平台能力时才需要同时修改 Platform 实现和对应壳。
排查三端差异时遵循:
- 先用 dev-server + curl 验证路由。
- 再检查前端 native 调用参数。
- iOS 单独 404 时优先检查
link_routes!。 - 平台能力异常时检查原生实现是否已注入,而不是改业务路由。
10. wifi-bridge 可选能力
启用 feature 后,业务构建中会出现 /wifi/start、/wifi/stop、/wifi/status 三个路由,并引入 aura-wifi-bridge。
启动后,电脑浏览器访问:
text
http://<设备IP>:30000HTTP 传输接口:
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | / | 管理页面(BridgeOptions.web_assets 提供的 Vite 产物,未提供时用内置兜底页);/bridge/ 仍兼容 |
| GET | /bridge/status | 服务状态与任务 |
| POST | /bridge/upload | multipart 流式上传 |
| GET | /bridge/tasks | 任务列表 |
| POST | /bridge/tasks/clear | 清空任务记录,不删除文件 |
| POST | /bridge/start?port=30000 | 传输服务内部启动接口 |
| POST | /bridge/stop | 停止传输服务 |
默认请求体上限 512MB,同名文件自动添加序号,任务状态为 uploading / done / error。done 只表示落盘完成,不表示业务已导入。 写操作会校验 Origin 与 Host 同源,跨站请求直接 403;文件名只取 basename,不能写出上传目录。
当前限制:
- 局域网服务没有鉴权,只能在可信网络使用(已做同源与路径校验,但不是账号体系)。
- 上传完成不自动推送事件,业务需轮询或自行扩展钩子。
- 任务列表只在内存中,进程重启后清空;文件仍保留。
- Android 已生成
WifiTransferService.kt,但 JNI 启停仍需按项目原生层接线。 WifiBridge::install必须取得真实的 NativePlatform;若在aura_native::install()之前安装,拿到的仍可能是 NullPlatform。
11. 修改内核与验证
不要做的事
- 不在
framework/core/中添加业务路由、业务实体或业务文案。 - 不让内核 crate 反向依赖项目
rust/。 - 不直接长期维护项目内的内核分叉。
- 不随意修改固定 JNI / C ABI 符号和响应信封。
推荐流程
- 在框架仓库实现通用能力并补测试。
- 发布框架版本或 tag。
- 项目中运行
node scripts/update-core.mjs --ref <tag>。 - 重新安装前端依赖并执行三端回归。
项目侧基础验证:
bash
# 业务 Rust 与 core 依赖
cargo check --manifest-path rust/Cargo.toml
# core 自身测试
cargo test --manifest-path framework/core/Cargo.toml
# 前端依赖与类型
pnpm install
pnpm --dir frontend typecheck
pnpm --dir frontend build如果修改了 Platform、原生导出或 wifi-bridge,还必须在对应真机验证;桌面测试无法覆盖 JNI、C ABI、后台服务和生命周期。
12. 源码阅读顺序
建议按请求链路阅读,而不是逐个文件跳着看:
packages/bridge-client/src/client.ts:前端如何选择通道并拆响应。crates/aura-dev-server/src/lib.rs:桌面 HTTP 入口。crates/aura-bridge/src/lib.rs:JSON 与 DispatchRequest / Response 的转换。crates/aura/src/aura.rs:路由查找、Context 构造和中间件执行。crates/aura/src/router.rs:同步与异步 handler 抽象。crates/aura/src/context.rs:参数、State、i18n 与平台入口。crates/aura-native/src/lib.rs:三端固定原生导出。crates/aura-platform/src/lib.rs:需要新增平台能力时的扩展点。
项目开发教程见仓库根目录的 README.md(不在本文档站内)。