Skip to content

Rust 侧:写业务逻辑 ​

所有业务路由都在生成项目的 rust/src/lib.rs(或它引用的模块)里写。三端壳和 dev-server 都会调 build_router(),改一处三端生效。


两种路由写法(可以混用) ​

方式一:#[route("/path")] 宏路由(推荐) ​

rust
use aura::{route, Context, Response};
use serde_json::json;

#[route("/hello")]
async fn hello(ctx: Context) -> Response {
    let name = ctx.params().get("name").cloned()
        .unwrap_or_else(|| "stranger".to_string());
    Response::ok(json!({ "greeting": format!("hi, {name}") }))
}

// ⚠️ 必须显式引用,否则 iOS staticlib 链接时 object 可能被裁掉
// Android / 鸿蒙是 cdylib / 动态库,不受影响,但写上没坏处
aura::link_routes!(init: hello);
  • 入参是 Context(含 path / params / platform / state / i18n)
  • 返回 Response(Response::ok(value) 或 Response::err(code, msg))
  • link_routes!(init: handler1, handler2, ...) 生成一个 init() 函数,必须在 Aura::new() 之前调用

方式二:aura.register() 同步路由 ​

rust
aura.register("/sync", |params| {
    // 参数是 serde_json::Value,返回 Result<Value, BridgeError>
    let count = params.get("count").and_then(|v| v.as_u64()).unwrap_or(0);
    Ok(serde_json::json!({ "doubled": count * 2 }))
});

aura.register("/oops", |_| {
    Err(aura::BridgeError::Failed {
        code: 409,
        message: "冲突了".into(),
    })
});
  • 适合简单逻辑,不用写 async fn
  • 三端都支持

在 build_router 里挂进去 ​

rust
pub fn build_router() -> Aura {
    init();                          // 宏路由兜底(必须在 Aura::new() 之前)
    let mut aura = Aura::new();

    aura.register("/sync", |params| Ok(params));  // 也可以混写

    // 给 aura 挂 i18n(见下)、设置、中间件...

    aura
}

处理参数 ​

Context.params() 返回 &serde_json::Value,是前端传进来的 params 字段。

rust
#[route("/calc")]
async fn calc(ctx: Context) -> Response {
    let a: f64 = ctx.params().get("a")?.as_f64()?;
    let b: f64 = ctx.params().get("b")?.as_f64()?;
    Response::ok(serde_json::json!({ "sum": a + b }))
}

参数缺失或类型不对时,? 会自然走到 500 错误(框架自动转换)。也可以显式返回:

rust
Response::err(400, "missing a or b")

i18n ​

内嵌语言包 ​

模板已经帮你配好了:rust/locales/zh-CN.json 和 en-US.json,用 include_str! 编进二进制。

json
// locales/zh-CN.json
{ "app": { "name": "我的应用" }, "hello": "你好" }
rust
let i18n = 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
#[route("/hello")]
async fn hello(ctx: Context) -> Response {
    let name = ctx.params().get("name").and_then(|v| v.as_str())
        .unwrap_or("stranger");
    let greeting = ctx.tr("hello");              // 取当前语言
    let greeting = ctx.tr_in("hello", "en-US");  // 取指定语言
    let lang = ctx.lang();                       // "zh-CN" 或 "en-US"

    Response::ok(serde_json::json!({
        "greeting": format!("{greeting}, {name}"),
        "lang": lang,
    }))
}

动态切语言:

rust
// 在任何 handler 里
ctx.set_lang("en-US");   // 后续 ctx.tr() 就用英文了

全局 State ​

Aura 实例有个 State,可以跨 handler 共享数据(进程内单例,不走持久化)。

rust
#[route("/counter/inc")]
async fn inc(ctx: Context) -> Response {
    let current: u64 = ctx.state().get("counter").unwrap_or(0);
    let next = current + 1;
    ctx.state().insert("counter", next);
    Response::ok(serde_json::json!({ "value": next }))
}

State 内部用 Mutex,多 handler 并发安全。


中间件(洋葱模型) ​

全局中间件对所有路由生效,在 Aura::new() 之后挂:

rust
use aura::{Context, Next, Response};

async fn log_middleware(ctx: Context, next: Next) -> Response {
    let path = ctx.path().to_string();
    let response = next.run(ctx).await;
    println!("{path} → {}", response.code);
    response
}

pub fn build_router() -> Aura {
    let mut aura = Aura::new();
    aura.use_middleware(log_middleware);   // 后挂的包在内层
    aura
}

满足 Fn(Context, Next) -> Future<Output = Response> 的闭包/函数都行,不需要 async_trait。

路由级中间件 ​

只作用于某一条路由,适合登录、权限、限流:

rust
async fn require_login(ctx: Context, next: Next) -> Response {
    if ctx.param("token").and_then(|value| value.as_str()) != Some("secret") {
        return Response::error(401, "unauthorized");
    }
    next.run(ctx).await
}

#[route("/admin/users", middleware = require_login)]
async fn users(_ctx: Context) -> Response {
    Response::ok(serde_json::json!([]))
}

非宏写法:aura.route_with("/admin/users", users, require_login);。 全局中间件仍会先执行,路由级中间件只包住这一条 handler。

路由分组 ​

一组路由共享前缀和中间件时用 group,不用逐条写 middleware =:

rust
pub fn build_router() -> Aura {
    let mut aura = Aura::new();

    let mut admin = aura.group("/admin", require_login);
    admin.register("/users", |_| Ok(serde_json::json!({ "users": [] }))); // /admin/users
    admin.route("/stats", stats_handler);                                  // /admin/stats

    // 子分组:前缀叠加,中间件按「外层先执行」的顺序追加
    let mut ops = admin.group("/ops", require_ops);
    ops.register("/jobs", list_jobs);                                      // /admin/ops/jobs

    aura
}
  • 前缀会自动补前导 /、去掉多余斜杠,"/admin" 与 "/admin/" 等价;
  • 组只影响手动注册的路由(register / route)。宏路由是编译期收集的,用 #[route(..., middleware = ...)];
  • 分组中间件在内核全局中间件之后执行,和 route_with 的语义一致;
  • 同一个 Aura 里可以开任意多个组,互不影响。

前端路由常量 ​

手写 bridge.call('/app/xxx') 容易和 Rust 路由漂移。模板提供了从路由表生成常量的脚本:

bash
pnpm bridge:gen      # 生成 frontend/src/bridge-routes.ts
pnpm bridge:check    # 只检查,不一致退出 1(CI / 提交前用)

生成内容是全部已注册路径(宏路由、register、group 都会包含):

ts
import { ROUTE_PATHS, type RoutePath } from './bridge-routes';

const path: RoutePath = ROUTE_PATHS[0];
await bridge.call(path, { /* ... */ });

frontend/src/bridge-routes.ts 是生成物,不要手改;新增 / 删除路由后重新运行 pnpm bridge:gen。 目前只生成路径,请求与响应类型仍在调用处用泛型声明。 采用后 pnpm build:all 会在构建前自动校验(文件不存在时跳过,SKIP_BRIDGE_CHECK=1 可关闭)。


发事件给前端 ​

Context 有 emit() 方法:真机走 NativeModule 的全局事件,dev 模式写入 dev-server 的 /events 队列(前端默认 1s 轮询一次)。

rust
#[route("/longjob/start")]
async fn start(ctx: Context) -> Response {
    // 用 tokio::spawn 起后台任务,期间 ctx.platform().emit("progress", json!({...}))
    ctx.platform().emit("progress", serde_json::json!({ "percent": 10 }));
    ctx.platform().emit("progress", serde_json::json!({ "percent": 50 }));
    ctx.platform().emit("progress", serde_json::json!({ "percent": 100 }));
    Response::ok(serde_json::json!({ "started": true }))
}

部署 ​

build_router() 是唯一生效入口,所有三端都调它。加了宏路由记得加 link_routes!(init: ...)。lib.rs 末尾的 export_jni!() 和 export_c_abi!() 不要删——它们是三端壳找到 Rust 分发入口的固定符号。

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