RushWind CMS — 三服务拓扑:core 领域层、双 BFF 薄代理与一份契约的双面输出

RushWind CMS --- 三服务拓扑:core 领域层、双 BFF 薄代理与一份契约的双面输出

本文回答一个问题:一个内容平台为什么要拆成 core-service + 双 BFF 三个进程?BFF 里为什么连一句 SQL 都找不到?同一份 proto 契约又怎么同时长出 REST 和 gRPC 两张脸、喂饱五个前端?

RushWind CMS 是一套 Rust 全栈 Headless 内容平台。它的后端是三个进程:core-service 是唯一的领域层,独占 PostgreSQL 与 Redis,只对内暴露 gRPC;admin-api 与 app-api 是两道 BFF,对浏览器与小程序提供 REST + SSE。分工写成一条铁律(仓库根 AGENTS.md):

BFF 不碰数据库:admin-api / app-api 只做协议转换与转发(生成代理 + 手写面);数据访问只发生在 core-service。

这句话的含金量在于"只发生在"------不是规范建议,是结构事实:BFF 的代码里不存在数据库连接。本文从启动序列讲到生成器,把这套拓扑的每个接缝拆开。


一、三服务分工:数据只有一个主人

三个进程、四个端口,各管一段:

进程 端口 职责
core-service gRPC :6602 领域层:认证内核 + 全部领域服务,独占 PG/Redis,不对外暴露
admin-api REST :6600 / SSE :6601 管理 BFF:后台全部路由
app-api REST :6700 / SSE :6701 前台 BFF:门户、注册登录、游客评论、公开读

core-service 的 main.rs 只有三件事------读配置、连库并引导、起 gRPC:

rust 复制代码
// backend/services/core-service/src/main.rs
//! The core domain service entry: loads the embedded config defaults
//! (env overrides win), connects Postgres + Redis exclusively (the
//! BFFs never touch the database), runs the fresh-database bootstrap
//! (golden DDL + system seed + demo seed), and serves the domain gRPC
//! face (:6602 by default).

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cfg = Config::load()?;
    let state = Arc::new(AppState::connect(cfg.clone()).await?);
    store::bootstrap::run(&state.db).await?;
    let addr: std::net::SocketAddr = cfg.grpc_addr.parse()...;
    let listener = tokio::net::TcpListener::bind(addr).await?;
    tonic::transport::Server::builder()
        .add_routes(server::registry(state))
        .serve_with_incoming(tokio_stream::wrappers::TcpListenerStream::new(listener))
        .await?;
    Ok(())
}

空库引导值得一格:数据库全新时自动跑四段 SQL------schema、系统种子、菜单种子、演示数据。已有的库一行不动,演进交给黄金 DDL 管线:

rust 复制代码
// backend/crates/store/src/bootstrap.rs
/// Applies schema + system seed + demo seed when the database is fresh.
/// Existing databases (already carrying the schema) are left untouched ---
/// the golden-DDL pipeline owns evolution.
pub async fn run(db: &DatabaseConnection) -> Result<(), sea_orm::DbErr> {
    if crate::tables_present(db).await? {
        return Ok(());
    }
    exec_statements(db, crate::SCHEMA_SQL).await?;
    exec_statements(db, crate::SEED_SQL).await?;
    exec_statements(db, crate::MENUS_SEED_SQL).await?;
    exec_statements(db, crate::DEMO_DATA_SQL).await?;
    Ok(())
}

cargo run -p core-service 连上空库,等它跑完,一个带演示数据的完整内容平台就在 :6602 后面了------"从克隆到能点"的距离被压到一个启动序列。

界面上它长这样:管理后台的帖子管理、标签管理,与 Next.js 内容门户,全部消费同一个后端栈:

管理后台 · 帖子管理 管理后台 · 标签管理

前台 · 内容门户(Next.js)------四套前台(React / Vue / Taro / Flutter)共用 app-api 这一道 BFF:

二、一份契约,两张脸

三个进程对外的全部接口,来自同一棵 proto 树。契约 crate 的 build.rs 是一个纯配置值------它声明两件事:gRPC 面要生成(tonic: true) ,以及 REST 面按 root prefix 切成两张:

rust 复制代码
// backend/crates/proto/build.rs
rushwind_proto_build::run(rushwind_proto_build::Build {
    dep_data_files: &[
        "pagination/v1/pagination.proto",
        "google/api/httpbody.proto",
    ],
    auth_free: AUTH_FREE,
    redact_plan_expr: Some("crate::redact_plan()"),
    tonic: true,
    faces: &[
        rushwind_proto_build::Face {
            label: "admin",
            module_file: "admin_gen.rs",
            root_prefix: Some("admin/service/v1/"),
            module_path: Some("crate::gen_admin::"),
        },
        rushwind_proto_build::Face {
            label: "app",
            module_file: "app_gen.rs",
            root_prefix: Some("app/service/v1/"),
            module_path: Some("crate::gen_app::"),
        },
    ],
    ..
})

为什么要切两张?模块文档给了唯一理由:admin 与 app 的 BFF 存在同名服务 (两边各有一个 CategoryService、CommentService,语义不同),两张面按 root prefix 切片、各指各的模块,不能共享。切片是字节级保真的可达性遍历------每张面只含自己前缀下的契约,挂到 crate::gen_admin / crate::gen_app。

同一棵契约树于是长出三样东西:

  • prost/pbjson 类型(两个 BFF 与 core 共用同一套消息类型,"BFF 与领域方法共享消息类型,代理层零映射");
  • tonic gRPC 面------core-service 的全部领域服务实现的是它;
  • gen-http REST 面------两张,分别是两个 BFF 的路由/绑定/trait/挂载产物。

类型一树,三处消费。契约改一处,gRPC 与两张 REST 面同时重算------没有"REST 改了 gRPC 忘了"这种事,因为它们不是两份代码,是同一份契约的两次投影。

三、薄代理:BFF 是一张生成的宏表

BFF 里的领域路由不是手写的转发函数,是一张生成的宏表。每个 proxy impl 长这样:

rust 复制代码
// backend/services/admin-api/src/services/proxies.rs(生成物)
//! Generated thin-BFF proxies --- a table of passthrough_proxy! invocations
//! ... DO NOT EDIT; regenerate via scripts/gen-proxies.py

passthrough_proxy!(
    services::admin_face for AccessKeyProxy {
        client: access_v1::AccessKeyServiceClient<Channel>,
        behaviors: behaviors,
        methods: [
            pass list_access_keys(ListAccessKeysRequest) -> ListAccessKeysResponse,
            pass create_access_key(CreateAccessKeyRequest) -> CreateAccessKeyResponse,
            ...
        ]
    }
);

宏的方法有四种形态(proxy_kit.rs 的自述):

  • pass------普通透传:带上操作者戳转发,原样返回领域的响应;
  • drop ------转发但丢弃响应体(BFF 脸返回 Empty,领域返回实体);
  • stub------契约有这个方法、领域还没落地:恒答 NOT_IMPLEMENTED;
  • hand------委托给 BFF 手写行为模块(裸转发带不动的 BFF 专属语义)。

pass 分支的全部实现,就是这一段:

rust 复制代码
// backend/services/admin-api/src/services/proxy_kit.rs
// pass --- the operator-stamped forward, the inner response back.
(@body pass $method:ident($req:ty) -> $resp:ty,
    client: $client:ty, behaviors: $behaviors:ident,
    state: $state:expr, ctx: $ctx:expr, msg: $msg:expr) => {
    {
        let mut core = <$client>::new($state.core_channel.clone());
        Ok(core
            .$method($crate::services::with_operator($ctx, $msg))
            .await
            .map_err($crate::services::map_status)?
            .into_inner())
    }
};

这张表是脚本(gen-proxies.py)从契约生成的------admin 侧 71 个 proxy impl、app 侧 12 个,文件头一行 DO NOT EDIT。BFF 的"薄"是生成的,不是自觉的:没有人为每个新接口手写一遍转发样板,也就没有人在转发层夹带私货的机会。

hand 形态最有代表性的是 app 侧的写方法------C 端 BFF 对内容写操作直接拒绝:

rust 复制代码
// backend/services/app-api/src/services/proxies.rs
hand create(content_v1::CreatePageRequest) -> content_v1::Page => forbidden_mutation,
hand update(content_v1::UpdatePageRequest) -> content_v1::Page => forbidden_mutation,
hand delete(content_v1::DeletePageRequest) -> pbjson_types::Empty => forbidden_mutation,

同一个领域服务,admin 脸 pass 全放行,app 脸写方法逐个钉成 403------BFF 的差异化语义(谁能写、谁只能读)收敛在代理表的一列动词上。

stub 形态则是诚实的进度表态:契约先行于实现时,未落地的领域方法在 BFF 脸上明确回答 NOT_IMPLEMENTED,而不是静默 404 或 500。

四、认证链在 core:刷新轮换是一次 Lua 原子操作

认证内核住在 core-service。登录链的自述(authentication_service.rs 文件头):

rust 复制代码
//! * Login (password grant): tenant resolve → credential verify (AES
//!   unwrap + bcrypt + dummy equalizer) → user status → permission gate
//!   (sys:access_backend / sys:access_app per client type) → HS256
//!   access JWT + opaque refresh, registered in the `gwc:` key family;
//!   refresh grant: verify-and-revoke rotation then re-mint.
//! * Logout: revokes every token of the user (SCAN prefix family).
//! * ValidateToken: the BFF session check (whitelist + blacklist).

口令侧三件套照旧:应用层 AES 加密传输、bcrypt 哈希存储、恒时假校验 (对不存在的用户跑一遍 dummy 哈希比对,让"探测哪些用户名存在"在时间侧信道上失效)。会话侧的键族按客户端类型与令牌种类分开:gwc:at:{client}:{uid}:{jti}、gwc:rt:{client}:{uid}:{jti}、黑名单 gwc:bl:{jti}。

最能代表"这种事该住在哪一层"的是刷新轮换。access token 与 refresh token 成对登记,刷新时验旧、吊旧、发新必须是原子的------两个请求同时拿同一个 refresh token 刷新,只能成功一个。这靠一段 Redis Lua 脚本保证:

rust 复制代码
// backend/services/core-service/src/token.rs
const VERIFY_AND_REVOKE: &str = r#"
local rtKey = KEYS[1]
local atKey = KEYS[2]
local refreshToken = ARGV[1]
local stored = redis.call('GET', rtKey)
if not stored or stored ~= refreshToken then
    return 0
end
redis.call('DEL', rtKey)
redis.call('DEL', atKey)
return 1
"#;

GET 比对与两把 DEL 在脚本里一次执行,Redis 单线程模型天然串行化------没有竞态窗口。轮换后旧 access token 一起作废,"刷新令牌泄露"的损害窗口被压到一次使用。

BFF 这边不碰会话存储,它的鉴权门是两段式 :本地先做 HS256 验签(格式对不对、签名过不过期,纯 CPU),会话校验阶段经适配器远程调 core 的 ValidateToken(白名单 + 黑名单的 verdict 只有一个来源):

rust 复制代码
// backend/crates/auth/src/lib.rs
let claims = match rushwind_authn_gate::authenticate_and_check_session(
    auth.as_ref(), checker.as_ref(), &headers, bearer.as_deref(),
).await {
    Ok(claims) => claims,
    Err(err) => {
        return rushwind_http_binding::envelope::error_response(unauthorized(package, err));
    }
};
req.extensions_mut().insert(claims);
next.run(req).await

免鉴权白名单同样在契约 crate 里编译期成形(auth_free.rs:admin 10 条、app 27 条,(service 全名, 方法名) 二元组),build.rs 消费它生成公开/门内双路由树------白名单是产物,不是配置文件,改它就是改代码,review 看得见。

五、横切件:分页管线与 SSE 扇出

分页。领域服务里没有一处手写的 count+offset。repo 侧只有一个 9 行的桥接文件,管线本体在框架:

rust 复制代码
// backend/crates/store/src/paging.rs(全文)
//! The deployment bridge to the framework paging pipeline
//! (`rushwind-storage-seaorm-support`): ...

pub use rushwind_storage_seaorm_support::paging::fetch_paged;

fetch_paged 收一个 Select 基座和生成的 PagingRequest,内部完成过滤绑定(按列类型匹配算子:exact / in / gt / contains / icontains / range......)、count、切片。core-service 服务层 35 处调用,全是同一形状------分页参数的拼写(page / pageSize / noPaging / orderBy / query)全仓只有一个定义处。

SSE。core 领域服务产生"推给哪些人"的事件后,经 gRPC 响应的 metadata 回传给 BFF 扇出------base64 包着的 JSON 事件列表:

rust 复制代码
// backend/services/admin-api/src/services/internal_message.rs
// The SSE fan-out: the payload metadata carries the base64 of a
// JSON event list [{uid, payload}, ...] --- decoded here, each event
// pushed to its user's stream.
if let Some(wire) = resp.metadata().get("x-sse-payload").and_then(|v| v.to_str().ok()) {
    let decoded = base64::engine::general::STANDARD
        .decode(wire).ok()
        .and_then(|b| serde_json::from_slice::<serde_json::Value>(&b).ok());
    if let Some(serde_json::Value::Array(events)) = decoded {
        for ev in events {
            let uid = ev.get("uid").and_then(|v| v.as_u64()).unwrap_or(0) as u32;
            let payload = ev.get("payload").cloned().unwrap_or_default();
            if uid > 0 && payload.is_object() {
                let body = serde_json::to_string(&payload).unwrap_or_else(|_| "{}".to_string());
                self.state.hub.publish(uid, body);
            }
        }
    }
}

领域层不需要知道 SSE 的存在------它只是在 gRPC 响应上多带了一份收件人列表;BFF 的 Hub 按 uid 分发;连接侧再过一道归属校验:?stream= 参数必须等于令牌的 userId,否则 FORBIDDEN: stream user mismatch,循环里还要再滤一次 user_id != uid 的事件。"谁的事件推给谁"有两层检查,中间层的广播对订阅者不可见。

六、五个前端与两份清单

五个前端(管理后台 admin-react、门户 Next.js、门户 Nuxt、Taro 小程序、Flutter 应用)以快照形式随仓同步。快照的治理是双清单:

  • MANIFEST.sha256 ------快照终态的门:树上每个文件的哈希。手改任何一个文件,--check 立刻红;
  • UPSTREAM.sha256 ------上游基线:同步时(品牌覆写之前)的上游哈希,用于检测"上游源仓是否又动了"。
bash 复制代码
# frontend/admin/sync-frontend.sh --check 的两道判
if d="$(diff -u "$MANIFEST" <(hash_tree "$DST") 2>&1)"; then
  echo "OK: frontend/admin/$FRONTEND/ matches $FRONTEND.MANIFEST.sha256"
else
  echo "ERROR: ... (hand-edit? run sync-frontend.sh $FRONTEND to rebuild)" >&2
  status=1        # 手改 → 退出码 1
fi
# 漂移检测:源仓在时对比上游基线(CI 无源仓时自跳过)。
if ! diff -u "$UPSTREAM_MANIFEST" <(upstream_hash) >/dev/null; then
  ... status=2    # 上游漂移 → 退出码 2
fi

退出码分开了两种病因:手改快照 (退出 1,必须重建)与上游有新版(退出 2,该同步了)。CI 里它们都是门,本地则是有用的信号。

快照唯一被允许的对源偏离是品牌覆写 :同步后打一层 RushWind 品牌(logo / favicon / 文案 / meta),能改什么在一个登记表里逐条列明------logo 与二进制资产、公司名与链接、系统标题与版权行、index.html meta、env 应用标题。替换表是逐条显式声明,不做全局盲替换;设计 token、代码注释、树内冻结文档明确列为禁区,保持上游原样。双清单钉的是覆写之后的终态------diff 与登记表严格对账,多一行少一行都过不了门。

于是"五个前端接同一个后端"这件事的工程形态是:同步是唯一入口,覆写是唯一偏离,清单是唯一裁判。前端升级 = 跑一次同步脚本 + 复核登记表,而不是五次手工合并。

七、E2E:三服务栈上的 125 个断言

这套拓扑对不对,最后由一个脚本裁决。backend/scripts/e2e-test.sh 在三服务栈全起后跑 125 个断言点、11 个覆盖节:

bash 复制代码
check() { if [[ "$3" == *"$2"* ]]; then ok; else fail; fi; }
# ......收尾打印 结果: PASS=$PASS FAIL=$FAIL

11 节覆盖:验证码与登录链(含错误密码反枚举)、门控路由(无 token / 假 token 的 401 信封形状)、13 个模块的种子数据读、CRUD 写路径、刷新轮换与登出全吊销、app 面(注册 / 游客评论 / 公开读)、权限与审计、聚合面、multipart 文件上传下载(MinIO)、SSE 与 CORS、以及边界面(Range 206/416、草稿不可见、待审评论不可见、注册链跨租户回退)。

值得注意的不只是数量,是断言的层级:认证链的断言(fresh jti、轮换后旧 token 401、登出全吊销)打的是 core 的会话语义;门控路由的断言打的是 BFF 的门;草稿不可见打的是领域规则。三服务的每一道接缝,都有一节断言对着它。

八、机制 × 关键决策 × 失败模式

机制 关键决策 失败模式(若无此决策)
core 独占数据 BFF 无数据库连接,数据访问单点 两个 BFF 各自直连库,事务与缓存口径分裂
契约双面 一棵契约树产出 tonic + 两张 gen-http 面 REST 与 gRPC 两套接口定义漂移
face 切片 按 root prefix 切 admin/app,同名服务各指各的模块 同名 CategoryService 在一张面里冲突
生成代理表 passthrough_proxy! 四形态,gen-proxies.py 产物 转发层手写膨胀,BFF 私货与样板并存
stub 形态 契约先行,未落地方法明确 NOT_IMPLEMENTED 前端对半成品接口得到静默 404
Lua 原子轮换 验旧/吊旧/发新一次脚本执行 并发刷新竞态,refresh token 重放
两段式门 本地验签 + core 远程 ValidateToken 会话黑名单两处维护,吊销不及时
白名单进构建 AUTH_FREE 是代码,消费于 build.rs 公开路由靠配置文件,加路由忘配白名单
SSE metadata 扇出 领域只带收件人列表,BFF 分发+双重过滤 领域层耦合推送细节;事件串台
双清单快照 MANIFEST 终态门 + UPSTREAM 漂移基线,退出码分病因 前端快照被顺手修补,与上游渐行渐远

三服务拓扑的成本是真实的:多两个进程、多一层 gRPC 边界、部署从一变三。买到的也是真实的:领域逻辑只有一个主人,BFF 薄到可以整体生成,契约的每次变更对 REST、gRPC、五个前端同时生效。什么时候值得付这个成本?当消费端的形态开始分化------管理后台与小程序要的不仅是不同界面,而是不同的权限面与错误面------BFF 就不再是架构品味,而是必需品。


项目地址:Gitee | GitHub

相关项目:

  • rushwind ------ RushWind 框架 monorepo(http-binding / gen-http / authn-gate / transport-sse / proto-build / storage-seaorm-support 等),本项目的底座:Gitee | GitHub
  • rushwind-admin ------ 姊妹项目(Rust 中后台平台,同一框架底座):Gitee | GitHub

系列文章:

相关推荐
喵个咪11 分钟前
RushWind Admin — 多租户行级隔离与租户回收站:Viewer 三态、repo_shell! 与全域级联清除
后端·rust
天多高_风不晓得1 小时前
Comparable 与 Comparator
后端
程序员鱼皮1 小时前
这 3 年 AI Agent 到底进化了啥?万字大白话,一次讲透!
前端·后端·aigc
一条Go1 小时前
SSH 命令审核流:为什么「能执行」必须先「被批准」
后端·架构·github
__underline__1 小时前
冷门Python知识点007篇:list[int]不是类,为什么能当基类?
后端·python
用户615218329961 小时前
为什么 String 是不可变的?看懂字符串常量池和底层实现
后端
brilliance1 小时前
HashMap 底层原理详解,从数组、链表到红黑树
后端
未秃头的程序猿2 小时前
RedisTemplate 序列化用错,线上多了 3 个 G 的隐形 key
redis·后端
掘金者阿豪2 小时前
MySQL兼容性实践:从SQL语法适配到业务系统平滑迁移
后端