百积木文档
开发指南后端应用开发

架构与资源边界

区分后端项目、Release Operation、Artifact、环境、部署、运行治理和数据库迁移。

后端应用的构建面与运行面相互独立:

资源Owner职责是否可变
ProjectProject Service后端应用的唯一产品身份,保存源码和 Git 历史可持续修改
Release OperationRust Build Service从主线 HEAD 发布一个 Cargo 语义版本完成后保留状态和日志
ArtifactArtifact Service保存构建成功后登记的统一可部署制品元数据不可变
EnvironmentHosted Service某个 Project 的开发、测试、生产等运行配置可产生配置修订
DeploymentHosted Service把一个 Artifact 部署到一个环境每次部署形成记录
EndpointHosted Service对调用方提供稳定访问地址由部署和路由状态支撑

“Hosted Service”是平台提供的托管构建与运行能力,不是需要另行创建的产品资源。项目、环境、部署、 端点以及它们的历史都以真实 projectId 关联;不存在与 Project 并列的 hostedServiceId

核心不变量是:

同一主线 commit 的 Cargo package.version 发布一次
  -> 得到一个不可变 projectVersion
  -> 同一个 projectVersion 逐级部署到开发、测试和生产

Hosted Service 部署只接收 projectId + projectVersion,不会把 releaseOperationIdbuildJobIdartifactId 当成部署版本,也不会在部署阶段隐式重新构建。发布成功时,构建服务把 hosted_service_release 登记到独立 Artifact Service;Hosted Service 在自己的边界内按项目版本解析该 不可变制品。Artifact 查询不改变后端所有权,也不是正常部署入口。

配置边界

  • 源码和 Artifact 保存与环境无关的程序逻辑。
  • 数据库、密钥、第三方 token 和环境差异配置在 Environment 或 Config Provider 中管理。
  • db-service 负责数据库 Instance、Logical Database、Profile 和 Allocation;Hosted Service 能力只在 Project Environment 中保存绑定,并在部署时解析连接配置。
  • 数据库迁移是与运行 Artifact 同源提交构建出的不可变 Artifact,由 Hosted Service 能力在目标 Environment 的数据库上、运行部署和流量切换之前执行。
  • Endpoint 鉴权由环境级 consumer/token 或应用自身鉴权负责。
  • 业务用户权限由后端应用自身或上游受信任身份上下文负责。

不要把生产配置打进 Artifact,也不要让构建脚本根据目标环境生成内容不同但版本相同的制品。

业务进程与运行治理边界

Hosted Service 后端必须按可以水平扩展为多个副本设计。Rust 业务进程不拥有实例数量、流量入口或跨副本 治理状态;增加、替换或回收副本不能改变业务合同,也不能要求业务代码增加部署环境分支。

层次负责不负责
Rust 业务进程业务规则、业务授权、数据一致性、事务、幂等、业务配额,以及健康检查、优雅退出、请求取消和有界资源使用等单进程正确性实例数量、扩缩容、入口负载均衡、通用请求限流、跨副本运行配额和发布调度
Hosted Service 控制面Environment 的类型化运行治理配置、配置修订、Slot 绑定、Deployment 编排和治理策略下发在业务进程内复制一套运行治理状态
Slot当前可用的 CPU、内存和副本容量权益,以及运行载体约束业务规则或某个请求的业务授权
OpenResty 与运行载体Endpoint 路由与鉴权、通用速率和并发保护、负载均衡、进程放置、就绪摘挂流、重启和发布切换依赖业务数据判断的配额、计费权益或领域不变量

实例数量、扩缩容策略、资源限制和通用流量策略应由目标 Environment 下的类型化、版本化治理配置统一管理, 并由 Hosted Service 根据 Slot 当前容量和产品目录校验后投影到运行载体。它们不是注入 Rust 进程的普通环境 变量,也不能通过约定任意配置键让业务代码自行解释。当前是否开放某项治理能力、可选值和限制,以工作区 当前 Runtime 方法定义与 Slot 目录为准;能力尚未开放时,普通 Environment 配置不能代替平台治理合同。

凡是需要在多个副本之间保持统一语义的通用运维能力,都必须由外部运行层或权威集中式服务执行。例如单个 OpenResty 实例可以完成本地过载保护,但跨副本的全局精确限流必须使用共享的权威计数能力,不能把每个 Rust 进程的本地计数相加后假装成全局配额。

这条边界不把业务责任移出 Rust 服务。像“某用户每天最多创建多少个业务对象”、积分余额、套餐权益、事务 冲突和上游调用幂等仍依赖业务身份与持久化状态,必须由对应业务 Owner 执行;它们不能被降格为 OpenResty 中的通用请求限流。

代码设计边界

运行资源边界清晰并不代表服务内部可以继续传递无类型数据。Rust 后端必须把 HTTP、消息、数据库 JSON 列和 Artifact 限制在适配器边界;JSON 进入服务后立即反序列化为有明确 Owner、版本和不变量的 Rust 类型,领域和应用逻辑只处理类型化对象。

Contract DTO、领域对象、应用 Command/Query、数据库 Record 和第三方 Payload 必须分开建模,业务转换 使用显式 TryFromFrom、编译器或应用服务完成。完整的目录、依赖方向、Serde、契约演进和测试门禁见 Rust 服务设计约束

本页内容