主题
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 分发入口的固定符号。