Skip to content

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 或抛 BridgeError

2. 目录与依赖方向 ​

Rust crates ​

Crate职责业务何时使用
aura路由、Context、中间件、State、Response、i18n几乎每个 Rust 业务模块
aura-macros#[route] proc-macro 与 inventory 收集通过 aura::route 间接使用
aura-platformAppPaths 与 Platform 宿主能力抽象文件目录、日志、事件、平台能力
aura-bridgeJSON 请求/响应与内核分发适配通常由原生入口和 dev-server 使用
aura-settings内存/JSON 文件键值设置应用配置持久化
aura-storageSQLite 连接、路径与迁移入口数据库存储
aura-native固定 JNI / C ABI 导出宏业务 lib.rs 末尾保留导出宏
aura-dev-server桌面 HTTP 开发服务rust/src/main.rs 使用
aura-wifi-bridge可选局域网文件传输仅启用 wifi-bridge 时

前端 packages ​

包职责
@aura/bridge-clientnative / http 自动检测、路由调用、错误与事件订阅
@aura/theme亮暗主题与语义设计 token
@aura/i18n业务语言包、插值、语言切换订阅
@aura/uiTabBar、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 实现和对应壳。

排查三端差异时遵循:

  1. 先用 dev-server + curl 验证路由。
  2. 再检查前端 native 调用参数。
  3. iOS 单独 404 时优先检查 link_routes!。
  4. 平台能力异常时检查原生实现是否已注入,而不是改业务路由。

10. wifi-bridge 可选能力 ​

启用 feature 后,业务构建中会出现 /wifi/start、/wifi/stop、/wifi/status 三个路由,并引入 aura-wifi-bridge。

启动后,电脑浏览器访问:

text
http://<设备IP>:30000

HTTP 传输接口:

方法路径作用
GET/管理页面(BridgeOptions.web_assets 提供的 Vite 产物,未提供时用内置兜底页);/bridge/ 仍兼容
GET/bridge/status服务状态与任务
POST/bridge/uploadmultipart 流式上传
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 符号和响应信封。

推荐流程 ​

  1. 在框架仓库实现通用能力并补测试。
  2. 发布框架版本或 tag。
  3. 项目中运行 node scripts/update-core.mjs --ref <tag>。
  4. 重新安装前端依赖并执行三端回归。

项目侧基础验证:

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. 源码阅读顺序 ​

建议按请求链路阅读,而不是逐个文件跳着看:

  1. packages/bridge-client/src/client.ts:前端如何选择通道并拆响应。
  2. crates/aura-dev-server/src/lib.rs:桌面 HTTP 入口。
  3. crates/aura-bridge/src/lib.rs:JSON 与 DispatchRequest / Response 的转换。
  4. crates/aura/src/aura.rs:路由查找、Context 构造和中间件执行。
  5. crates/aura/src/router.rs:同步与异步 handler 抽象。
  6. crates/aura/src/context.rs:参数、State、i18n 与平台入口。
  7. crates/aura-native/src/lib.rs:三端固定原生导出。
  8. crates/aura-platform/src/lib.rs:需要新增平台能力时的扩展点。

项目开发教程见仓库根目录的 README.md(不在本文档站内)。

lynx-aura · 跨平台本地应用开发框架