Skip to content

Latest commit

 

History

History
369 lines (279 loc) · 31.2 KB

03-codegen-chain.md

File metadata and controls

369 lines (279 loc) · 31.2 KB

03 · 契约与生成链路

前置:02 从零跑起来。读完你会知道:proto 如何变成 admin 面的 291 条路由、491 条错误映射和 286 个服务方法(fork 面另有 5 条路由、6 条错误映射、5 个方法,同链路生成);哪些代码永远不该手改。

1. 契约树的维护方式:同步 + 校验门

backend/apps/admin/api/protos/(admin 契约树)与 backend/apps/admin/api/fork/protos/(fork 模块契约树)共享同一个 buf 工作区——一次编译、一个池、一套分页类型。admin 树是唯一 API 契约,由脚本从上游契约源同步进本仓,并配 MANIFEST 校验门防止手改:

bash backend/apps/admin/api/sync-protos.sh          # 同步并重建 MANIFEST.sha256
bash backend/apps/admin/api/sync-protos.sh --check  # 校验门(与 CI 一致)
  • 同步源的默认路径与覆盖方式见脚本头部说明(backend/apps/admin/api/sync-protos.sh);
  • 上游契约发生变更时:重新同步 → buf breaking 对主基线做破坏性检查 → 确认行为面(见 §8 差分台架)→ 提交;
  • 不要手改 api/protos/;
  • 契约树引用的注解模块(google.api 等)不再进仓:api/buf.yaml 把它们声明为 buf 依赖、api/buf.lock 按 commit 钉定(与上游 lock 同源,重新同步时会比对两把锁)。注解里携带两类关键信息——google.api.http 路由绑定与错误码注解(reason → HTTP 状态映射)——它们是整条生成链的输入。

1.1 同步脚本实际做什么

sync-protos.sh 的语义比"复制 + 哈希"多一点,四个值得知道的细节:

  • 字节归一化:同步时统一剥 UTF-8 BOM(源仓有 2 个文件带 BOM——protoc 容忍、Rust 侧曾经的 protox 拒绝),复制与哈希两侧走同一归一化,漂移检测语义不受影响;
  • 清单稳定序:MANIFEST.sha256 的行序由 sort 决定,且脚本强制 export LC_ALL=C——UTF-8 locale 的 collation 会忽略标点,i_api.proto 与 i_api_audit_log.proto 的先后会随环境翻转,CI 的 C locale 因此必红(脚本注释原话:前端 sync 脚本早有此钉,此处补齐);
  • 三种退出码:0 = 通过;1 = api/protos 与 MANIFEST 不一致(篡改或未同步的手改,CI 门拦截的就是这个);2 = 本仓快照与上游契约源存在漂移(上游动了契约,等你重新同步——这是提醒不是失败);
  • 门只看字节:MANIFEST 是逐文件 sha256 清单,任何一字节的手改都会让 --check 退 1——没有"我只想改个注释"的例外。

同步源本身可覆盖:默认指向脚本内的上游契约源路径,用 GOWIND_ADMIN_API_DIR 环境变量换成任意 checkout(本地联调上游未发布分支时用)。

1.2 buf 工作区实物(api/buf.yaml)

version: v2
modules:
  - path: protos        # admin 契约树:149 个 proto,字节同步快照(MANIFEST 门),上行同步唯一落点
    lint:
      use: [STANDARD]
      except:           # 上游 *_error.proto 的 reason 枚举走裸 HTTP 状态拼写,改名即破坏线上客户端——样式债记在上游
        - ENUM_VALUE_UPPER_SNAKE_CASE
        - ENUM_ZERO_VALUE_SUFFIX
  - path: fork/protos   # fork 自有契约树:自由编辑,不做字节清单门
deps:
  - 'buf.build/googleapis/googleapis'            # google.api.http / field_behavior / HttpBody
  - 'buf.build/kratos/apis'                      # (errors.code) reason→HTTP 状态注解
  - 'buf.build/tx7do/pagination'                 # PagingRequest(请求信封)
  - 'buf.build/envoyproxy/protoc-gen-validate'   # PGV 校验注解声明
  - 'buf.build/gnostic/gnostic'                  # OpenAPI 扩展注解
  - 'buf.build/go-wind/redact'                   # 静态脱敏注解声明
breaking:
  use: [FILE]
  • 六个 BSR 依赖由 buf.lock 逐个钉 commit(文件头 "Generated by buf. DO NOT EDIT.");首次 buf build 会把六个模块拉进 buf 模块缓存,之后离线可用。buf.lock 与上游镜像仓的同一把锁同源——再同步时比对两边 commit 即知注解依赖是否也该跟着升。
  • 两棵树并列在 modules 下:新 fork 模块的契约树在 fork/protos/ 并排落地,与 admin 树共享一次编译、一个池、一套分页类型(fork 的 PagingRequest 就是 admin 的那个)。
  • breaking.use: [FILE]:FILE 规则下仅删除/改型算破坏,纯新增不算——buf breaking --against "../../.git#branch=main,subdir=backend/apps/admin/api" 对 main 基线跑(buf.yaml 头部注释给的正是在接受新 vintage 前先跑这条)。
  • 不做 buf format:会砸字节清单门(格式化改字节,MANIFEST 必红)。

2. 构建期双面编译

apps/admin/build.rs 把契约工作区编译成两个面(admin 树与 fork 模块树同区编译,每个源树再各出一个 gen face),这是理解本仓的关键一刀:

backend/apps/admin/api/protos(admin 树)+ api/fork/protos(fork 模块树,+ buf 依赖的注解模块)
        │
        ├─ buf build → 全量闭包注解镜像(含 google.api.http / 错误码等自定义选项字节)
        │     └─ rushwind-gen-http(框架仓的生成器)解析描述符,确定性生成:
        │          · ROUTES 路由表(291 条,含 additional_bindings)
        │          · 错误状态表(491 条 reason → HTTP 状态)
        │          · 服务 trait(286 个方法,XxxServiceHandlers)
        │          · mounts 挂载胶水(每服务一个,pub/gate 双路由线程)
        │          · 逐路由绑定计划(body/query/path 变量怎么解)
        │
        └─ buf build(带 source info)→ 过滤后的描述符集 → prost + pbjson
              └─ proto 类型与 protojson serde(64 位整数字符串化、presence 语义)

两条闭包都是 buf build 的产物:注解闭包编译时不带 source info(描述符镜像按序产出、平台无关);类型闭包带 source info——proto 注释经 prost 变成生成类型的 rustdoc,再过滤掉注解声明文件后交给 prost_build/pbjson_build。admin 树与 fork 模块树各出一个 gen face(同一闭包按树前缀切片),类型面则共用一个池。

为什么必须装 buf:构建引擎直接消费 buf build 的描述符产物——Rust 侧序列化器(如曾经的 protox 管线)会丢弃自定义选项字节,而选项字节正是路由与错误码的载体;生成链已不再依赖 protox,两条闭包统一走 buf build。这是环境要求里 buf"必须"的原因。

2.1 两条闭包的精确形态

crates/biz-proto-build/src/lib.rs 的 run() 是整条链的实现,五步值得照着读(OUT_DIR = cargo 给 build script 的输出目录,§7):

  1. 注解闭包(全工作区,无 source info)——buf build --exclude-source-info --output <OUT_DIR>/annotated_descriptor.bin,在 api/ 目录下执行;选项字节保真,输出顺序由 buf 决定(有序),生成器的 ROUTES 因此平台无关。产物随即读入内存并留下 size(调试日志用)。
  2. 类型闭包(全工作区,带 source info)——同一次 buf 工作区的第二次 build 写临时文件,prost 解码成 FileDescriptorSet 后删掉临时文件;随后校验 dep_data_files(build.rs 声明的 pagination/v1/pagination.proto)确实在闭包里——依赖被从工作区拿掉会让构建直接失败而不是静默丢类型。
  3. 类型过滤——见 §2.2。
  4. prost + pbjson——prost_build::Config:compile_well_known_types() + extern_path(".google.protobuf", "::pbjson_types") + include_file("proto_include.rs"),直接 compile_fds(过滤后集合)——不碰 protoc、不碰文件系统,类型面没有任何输入路径;pbjson_build 在同一过滤集合的字节上出 protojson serde impl(包清单从过滤集合自身推导,well-known 外部化排除)。
  5. 逐 face 出 gen 面——对 build.rs 的 faces 列表逐项取闭包(取法两种:face 声明了 source_dir 就对这一个 buf 模块目录单独 buf build;声明了 root_prefix 就在全量闭包上按前缀切片——当前两个 face 各占一种,机制见 §4)、调 rushwind_gen_http::generate_from_bytes、把生成源里的 crate::gen:: 重写为该 face 的模块路径、写 OUT_DIR/<module_file>。生成器报错即 panic(gen-rust code generation failed ({label} face))——契约错误宁可红构建也不静默降级。

构建脚本最后注册五条 cargo:rerun-if-changed:src/auth_free.rs(白名单单源,改分类就要再生)、api/buf.yaml、api/buf.lock、api/protos/(整树)、每个 extra_type_root(api/fork/protos/)——契约树任何文件增删改、依赖升版、白名单改动都会触发完整再生。

2.2 类型闭包的过滤规则

类型面不想要注解声明文件(google.api 声明、errors 注解、redact 声明……它们只是选项载体,生成 Rust 类型没有意义)。过滤判据 is_types_kept,一个文件保留当且仅当:

  • 顶层目录在 contract_tops——protos/* 的顶层目录 + 每个 extra_type_root(fork/protos/*)的顶层目录,从树本身派生(目录列表 read_dir 后排序去重)——新模块目录不需要改任何白名单,这是 fork 树并排落地能零配置的原因;
  • 或是显式声明的依赖数据文件(dep_data_files:pagination/v1/pagination.proto——分页信封是真实运行时类型);
  • 或是 well-known(google/protobuf/ 前缀——保留使字段引用可解析,但 prost 侧已外部化到 pbjson_types,pbjson 侧排除)。

保留的文件还要修剪依赖边:dependency 列表里指向被丢弃文件的边删掉,prost 拿到的集合自洽。出参即两条:proto_include.rs(prost 类型树)与 pbjson serde——这就是 src/proto/mod.rs 里 include!(OUT_DIR/proto_include.rs) 的来源。

3. 以 LanguageService 为例:一个 rpc 的全程

把一条 rpc 从 .proto 到 handler 的每站都摆出来——这是读懂生成链最短的一条路。选 LanguageService.List(语言管理列表),它包含所有典型要素:BFF 注解面、类型复用面、分页信封。

第 1 站:契约树里的注解声明——api/protos/admin/service/v1/i_language.proto(i_ 前缀 = 面向 HTTP 的 BFF 服务文件):

package admin.service.v1;

import "dict/service/v1/language.proto";   // 类型从数据面文件复用

service LanguageService {
  // 分页查询语言列表
  rpc List (pagination.PagingRequest) returns (dict.service.v1.ListLanguageResponse) {
    option (google.api.http) = {
      get: "/admin/v1/dict/langs"
    };
  }
  // Get / Create / Update / Delete / BatchCreate 同文件,各带 google.api.http
}

注:dict/service/v1/language.proto(同树的数据面文件)携带 Language 等消息类型,不带 google.api.http 注解;类型面一个池一个类型,注解面一树一 face——两份文件在同一 buf 工作区里分工(详见 §4)。请求类型是框架的 pagination.PagingRequest(BSR 依赖模块,经 dep_data_files 参与类型生成)。

第 2 站:ROUTES 路由表条目——构建后 OUT_DIR/admin_gen.rs 的 routes::ROUTES[122](索引 = 表内注册序):

RouteSpec {
    method: "GET",
    path: "/admin/v1/dict/langs",
    operation_id: "/admin.service.v1.LanguageService/List",
    service_name: "LanguageService",
    service_fq: "admin.service.v1.LanguageService",
    method_name: "List",
    input_fq: "pagination.PagingRequest",
    output_fq: "dict.service.v1.ListLanguageResponse",
    path_vars: &[],
    body_star: false,          // GET 无 body 绑定
    shadowed: false,
    query_leaves: &[ /* 14 个 BindLeaf:page/pageSize/offset/limit/token/noPaging/
                        query|filter(oneof filtering_type)/filterExpr.*/orderBy/
                        sorting/fieldMask —— path_json 与 path_proto 双拼写 +
                        LeafKind + oneof 归属 */ ],
},

query_leaves 就是绑定计划:绑定层照它把 query 串逐叶解进 PagingRequest(page → proto 字段 page,驼峰蛇形双拼写都可;query/filter 同落 oneof filtering_type 的两臂……)。GET 路由 body_star: false,body 绑定层不参与。

第 3 站:服务 trait 方法——同文件 services::LanguageServiceHandlers(286 个方法之一;生成源里类型是全路径拼写,此处缩写):

pub trait LanguageServiceHandlers: Send + Sync {
    /// Operation `/admin.service.v1.LanguageService/List`.
    async fn list(&self, ctx: RequestContext, req: PagingRequest)
        -> Result<ListLanguageResponse, StatusError>;
    // get / create / update / delete / batch_create 同 trait
}

第 4 站:挂载函数——mounts::mount_language_service 按白名单分类逐条注册(LanguageService 不在免鉴权表,全部进门控桶):

pub fn mount_language_service(router_pub: Router, router_gate: Router,
    svc: Arc<dyn crate::proto::gen::services::LanguageServiceHandlers>,
    wrap: &dyn Fn(MethodRouter, &RouteWire, bool) -> MethodRouter) -> (Router, Router) {
    let r_pub = router_pub;
    let mut r_gate = router_gate;
    r_gate = mount_route_122(r_gate, Arc::clone(&svc), wrap);   // List
    r_gate = mount_route_123(r_gate, Arc::clone(&svc), wrap);   // Get
    // …124–127:Create / Update / Delete / BatchCreate,全部 r_gate
    (r_pub, r_gate)
}

mount_route_122 是单条绑定的装配体(节选自生成源,关键行):

let spec = &super::routes::ROUTES[122];
// method 字符串 → axum MethodFilter(match 五动词,其余 panic——契约层不认识就不该出现)
let h = move |req: axum::extract::Request| { …
    rushwind_http_binding::glue::handle(
        crate::pool(),                       // 描述符池(crate 根单例,见 01 章 §2.5)
        Some(crate::redact_plan()),          // 静态脱敏计划
        &wire,                               // RouteWire(operation/输入输出类型/body/path_vars)
        move |ctx, req| { let svc = Arc::clone(&svc);
            async move { svc.list(ctx, req).await } },   // ← trait 方法调用点
        req, std::collections::HashMap::new(),
    ).await };
let mr = wrap(axum::routing::on(m, h), &bind_wire, true);    // true = 门控
if super::routes::is_verb_on_resource(spec.path) { return r; }  // AIP-136 守卫(§6 例外)
r.route(spec.path, mr)

第 5 站:手写挂载表行——rest.rs 的 mount_items()(01 章 §2.3):

mount_service!(state, mount_language_service, LanguageService),

宏展开把 LanguageService { state } 实例化并 Arc 化,交给生成的 mount_language_service——手写侧只说"这个服务用这个实现",路由形状零手写。

第 6 站:路由边组层——edge.rs 的 make_wrap(01 章 §2.1)对 mount_route_122 交出的 MethodRouter 先挂 auth_gate(gated=true)再挂 bind_run(最外层)——绑定计划就在 bind_run(pool, wire.input_fq, wire.body_star, subtypes, req, next) 里逐叶执行。

第 7 站:handler 调用——请求进来:绑定层按 query_leaves 解出 PagingRequest → 门三阶段放行、claims 进扩展 → glue::handle 构造 RequestContext → 调 svc.list(ctx, req) → service 层(apps/admin/src/admin/services/)拿到的是 proto DTO,转模型交仓储 → 响应沿原路返回(脱敏计划裁剪 → protojson 序列化)。

七站里只有第 5 站(那一行宏)与 service 实现是手写的;其余五站全部构建期确定。

4. 双 face 切片机制

build.rs 声明两个 face,各自用不同的闭包取法——这组对比是理解"面"的关键:

faces: &[
    biz_proto_build::Face {
        label: "admin",
        module_file: "admin_gen.rs",
        root_prefix: None,
        source_dir: Some("protos"),                  // ① 整目录专属闭包
        module_path: Some("crate::proto::gen::"),
    },
    biz_proto_build::Face {
        label: "template",
        module_file: "template_gen.rs",
        root_prefix: Some("notice/"),                // ② 全量闭包按前缀切片
        source_dir: None,
        module_path: Some("crate::proto::gen::template::"),
    },
]
  • admin face 用 source_dir: "protos":生成器对这一个 buf 模块目录单独跑一次 buf build protos --exclude-source-info(transitive import 经工作区 BSR 依赖解析,选项字节保真),得到 admin 树自己的闭包。为什么整目录:admin face 的路由表必须恰好是同步进仓的 admin 注册集——差分台架按这张表逐条 sweep,fork 路由混进去一个字就破坏台账(build.rs/引擎注释原话:"the admin face must NOT see fork routes… and a fork face must not re-generate the admin surface")。
  • template face 用 root_prefix: "notice/":在全工作区注解闭包上做字节保真的可达性游走(slice::sub_closure),把 notice/ 子闭包切出来再生成。为什么不用整目录:fork/protos 是一个模块目录,未来第二个 fork 模块(copy-rename 模板而来)的契约树会并排落进同一目录——buf build fork/protos 会把两个模块的树都编进这份闭包,第二个模块的路由就泄漏进 template face 的路由表。root_prefix 把 face 钉死在 notice/ 前缀,新模块来了它不沾(build.rs 注释:copy-rename 演练编译过第二模块,守卫保持全绿)。
  • module_path 重写:框架生成器的产物里自引用写死 crate::gen::;每个 face 按自己的模块路径重写(admin face → crate::proto::gen::,template face → crate::proto::gen::template::)。同一份生成逻辑因此能以两个兄弟模块并存(proto/mod.rs:pub mod gen { include!(admin_gen.rs) … pub mod template { include!(template_gen.rs) } }——fork 的第二个模块在这里再加一个兄弟块 + build.rs 的 face 条目)。

两把刀各管一边:source_dir 保证"admin 表 = admin 树",root_prefix 保证"模板表 = 模板树";类型面则不需要切片——一个池一个类型,PagingRequest 全仓唯一。

5. 新增一个 proto 文件时,链路各站发生什么

按"文件落在哪棵树"分两条路径。逐站清单(每站都给了可验证的落点):

  1. 树的选择:admin 面的契约改动源头在上游契约源——本仓不手写 api/protos/,走重新同步(§1);fork 树(api/fork/protos/<模块>/…)自由编辑。
  2. import 写法:按模块根相对路径(import "dict/service/v1/language.proto"),与契约树的写法天然同构;BSR 依赖模块里的类型(pagination 等)同样按根解析。
  3. MANIFEST 门:admin 树的变更必须经 sync-protos.sh(重新生成 MANIFEST),否则 --check 退 1、CI 红;fork 树无此门。
  4. 构建触发:cargo:rerun-if-changed 覆盖 api/protos/ 与 api/fork/protos/ 整树——文件增删改都触发 build script 完整重跑。
  5. 全量闭包再生:buf build 全工作区,注解闭包与类型闭包先后再生;新增文件进了两个闭包(前提:import 闭合,buf 报错即红构建)。
  6. face 闭包分派:新增在 admin 树 → 只进 admin face 的专属闭包(buf build protos)与类型闭包;新增在 fork 树 → 只进 template face 的 root_prefix 切片(前提:顶层前缀是 notice/,第二模块则有自己的前缀)与类型闭包——admin face 的路由表不会长出 fork 路由(§4)。
  7. 类型面派生:新文件的顶层目录自动加入 contract_tops(§2.2),prost/pbjson 出类型——不需要改任何白名单;若文件只带注解(如 error 声明),类型面正确地不出类型。
  8. 生成面生长:新 rpc → ROUTES 新条目 + trait 新方法 + mount 新函数;新 (errors.code) 枚举值 → ERROR_STATUS 新行;文件头 Corpus 行的数字与 [biz-proto-build] 调试日志的 bytes/files 同步变化(§7)。
  9. 编译闸门:trait 新方法必须被手写 service 实现——rest.rs 的 Arc::new($service{..}) 要向上转型为 Arc<dyn XxxServiceHandlers>,漏实现直接编译失败(生成面把"忘写业务"提前到编译期);fork 树新 rpc 还要显式更新 tests/template_gen_surface.rs 的路由计数钉("a new rpc updates this count")。
  10. 运行时闸门:admin 面端点随同步面更新 assets/openapi.yaml(protoc-gen-openapi 产物,编译进二进制),启动期 sync_apis 按 (path, method) MERGE 进 sys_apis——authorizer 对未登记端点 fail-closed,部署新契约若不同步,租户侧全端点 403;fork 模块没有 OpenAPI 资产(business-surface 不挂文档面),模块种子改从自己的 ROUTES 表逐条 upsert sys_apis(modules/template/seed.rs 注释:"routes fail-closed, so this sync is what makes the module's routes authorizable")。
  11. 迁移与种子不自动:新实体要自己进实体目录与迁移链(新表),菜单/权限点要进种子——生成链只管契约面,业务落地面见 04 章与 09 章。
  12. 前端客户端:TypeScript 客户端从同一契约再生、随快照进仓(三份字节相同)——走前端同步脚本,不手写。

6. 生成面落位(crate proto)

符号 内容 谁消费
crate::proto::<module>::<service>::v1::* 请求/响应/实体类型(prost + pbjson) service 层、绑定层
crate::proto::gen::services::XxxServiceHandlers 服务 trait(async-trait,dyn 兼容) service 层实现
crate::proto::gen::mounts::mount_xxx_service 挂载胶水:接收 (router_pub, router_gate, service, wrap) 双路由线程 admin/server/rest.rs 的 mount_service!
crate::proto::tables ROUTES 路由表 + reason→状态表 绑定层、错误编码
crate::AUTH_FREE(面内 crate::proto::AUTH_FREE 再导出) 免鉴权端点白名单(8 端点,单源 apps/admin/src/auth_free.rs) 鉴权门、守卫测试

admin/server/rest.rs 的 mount_service! 表是服务与挂载的唯一对接点——每个服务一行 ($mount, $Service),绑定计划决定 wrap 怎么组合层级。

tables 模块是生成表之上的手写薄访问层,只有一个函数:error_status(package, reason) -> Option<i32> 对 ERROR_STATUS 线性查表;调用方(state::status_error、门信封)把 None 折叠成 Unknown 形态(500 + 空 reason)——语义钉在函数文档里,never 静默替换成别的兜底。门的双锚等价也守在这层:tests/admin_error_statuses.rs 断言错误表里 UNAUTHORIZED → 401、FORBIDDEN → 403 与 crates/auth 钉的字面量一致(01 章 §2.2)——契约改锚在这里红,而不是线上漂移。

已知例外(291 条中的 1 条):POST /admin/v1/bi-dashboards/{id}:copy 是 AIP-136 "资源上的自定义动作"形态——路径段里参数后跟 :verb 字面量。 Go 参照的 mux 按字符前缀匹配支持它,而 axum 0.8 的 matchit 路由树拒绝 这种混合段("Only one parameter is allowed per path segment")。生成的 mount 对该类绑定跳过 axum 树注册(is_verb_on_resource 守卫):RouteSpec、 服务 trait 与实现完整保留,仅该 RPC 暂答 404,待 wire 层原生支持后恢复。 其余 :verb 路由(如 monitor-alert-rules:evaluate)是纯字面量段, 不受影响。

前端同源:React 版的 TypeScript 客户端(frontend/admin/react/src/api/generated/)同样从这套契约生成、随快照进仓——三份产物(Rust 类型、路由面、TS 客户端)共享同一契约源,不存在手写 API 层。

序列化形态的钉子:tests/golden.rs 把响应编解码的字节形状钉死(绑定规格 §3 的 EmitUnpopulated 形态)——presence 字段未设置恒省略、裸标量发默认值、64 位整数发字符串、未设置的 repeated 发 [];文件头自述"the authoritative cross-backend pin is the differential harness; these lock the Rust side against drift"。文件里最短的两个断言值得一看:零值 Language 序列化为 {},零值 ListLanguageResponse 序列化为 {"items":[],"total":"0"}——两行就记住了 protojson 的 presence 语义。

7. build script 调试方法

生成链出错时,按下面的顺序定位(全部是本仓实际可复现的形态):

产物在哪:build script 的 OUT_DIR 落在 backend/target/debug/build/admin/<hash>/out/(不同 cargo 版本可能是 admin-<hash> 形态,dir target\debug\build\admin* 一眼可见)。产物清单:

文件 来源 内容
annotated_descriptor.bin 步骤 ① 全工作区注解闭包 唯一留下的 buf 产物(DESCRIPTOR_BYTES include 的就是它)
proto_include.rs prost include_file 类型树(src/proto/mod.rs include)
admin_gen.rs / template_gen.rs 步骤 ⑤ 逐 face 两个 gen face

(每次构建前会清扫 OUT_DIR 里的陈旧 .rs——早期运行产出、后被过滤掉的包不残留。)

看构建在说什么:cargo build -p admin -vv 把 build script 的 stderr 透出来,三行固定格式的诊断全来自 biz-proto-build:

[biz-proto-build] annotated closure: <N> bytes (buf build); types set: <M> files (annotation declarations dropped)
[biz-proto-build] admin face closure: <N1> bytes (dir: protos; full: <N>)       # source_dir 型 face
[biz-proto-build] template face sub-closure: <N2> bytes (full: <N>)             # root_prefix 型 face

N1 ≪ N 是常态(admin 专属闭包远小于全工作区闭包)——数字异常通常是契约树混入了预期外的依赖。

错误信息即语义(全部逐字来自 biz-proto-build/src/lib.rs):

  • buf build failed: <buf 的 stderr>——契约树编译不过,第一现场永远是 buf 的报错(行号在 proto 文件上);先 cd backend/apps/admin/api && buf build 手跑一遍,比 cargo 包装的输出直观;
  • buf: <io error>——buf 不在 PATH(02 章 §1.1);
  • dependency data file missing from the compiled closure: <rel> (declared in the module workspace's deps and pinned by its buf.lock?)——dep_data_files 声明的文件没编进闭包,查 buf.yaml deps 与 buf.lock;
  • no contract protos found under <path>——契约树目录空了(同步事故);
  • the buf image does not decode as a FileDescriptorSet: <e>——buf 版本产物形态异常;
  • panic gen-rust code generation failed ({label} face): <e>——描述符合法但生成器不认识(通常是注解形状超出支持面)。

读生成物:直接打开 out/admin_gen.rs,头部四行(@generated … DO NOT EDIT + Corpus 行)就是体检表(01 章 §5.1);改契约后重构建,diff 这份文件是理解"我的改动变成了什么"最快的方式——ROUTES 条目、trait 方法、mount 函数与 ERROR_STATUS 行一一对应第 3 节的各站。

8. 差分回归台架:契约面的验收

backend/testbed 通过 compose 拉起中间件与 Go / Rust 双栈后端,admin-diff 对 291 条路由 + 121 条 HEAD 探针(GET 路由逐条自动 sweep)并逐字节比对响应,豁免显式登记于 exemptions.json(当前 3 类:路由遮蔽、鉴权后路径绑定、HEAD-on-GET)。

使用方式与"探针方法学陷阱"(代理污染、Content-Type 注入等,复跑前必读)见 backend/testbed/README.md。

compose 实物(testbed/docker-compose.yml)三个要点,避免第一次就踩空:

  • 拓扑:bitnami 的 pg/redis/minio + Go 参照后端(rushwind-diff/go-admin,发布 127.0.0.1:27788/27789);基础设施三件不发布宿主端口——只有两个后端可达,回放器经 127.0.0.1 访问各自端口;
  • 凭据与库:PG 库名 gwa(Go 侧 data.yaml 烤死),凭据与本地开发栈一致(*Abcd123456)——但这份栈不能当本地开发中间件用(02 章 §2.2);
  • Rust 侧不在 compose 里:注释原话——其构建上下文需要仓外 rushwind 路径依赖,且差分期间由 cargo 直跑以获得快速迭代。

日常工作流:

  • 动了绑定/序列化/错误信封相关代码 → 必须跑台架,以逐字节一致为通过标准;
  • 只动了业务逻辑(service/repo 内部)→ 单元与行为测试即可,台架不覆盖业务数据面;
  • 上游契约漂移 → 重新同步 + 台架回归 + 更新 binding-spec.md(wire 语义对齐基准)。

9. 生成面 vs 手写面边界清单

把"哪些文件永远不要手改"钉成一张清单(第 1 章的边界表的执行版):

永远不要手改(构建/同步再生,改了必被覆盖或必被门拦截):

文件 为什么
OUT_DIR 全部产物(annotated_descriptor.bin / proto_include.rs / admin_gen.rs / template_gen.rs) 每次构建确定性再生;手改既无效又误导
api/protos/** MANIFEST.sha256 门;--check 退 1,CI 红(§1.1)
api/buf.lock 文件头 "Generated by buf. DO NOT EDIT.";与上游镜像仓 lock 同源,随同步演进
apps/admin/assets/openapi.yaml 头部 "Generated with protoc-gen-openapi";随上游同步面更新,是 /q/openapi.yaml 与启动期 sync_apis 的数据源(assets.rs 编进二进制)
前端 src/api/generated/** 与后端同一契约源生成,三份快照字节相同

结构上会动,但按既有形状动(模板位,不是自由发挥区):

位置 动法
apps/admin/build.rs 的 faces 列表 fork 的第二个模块加自己的 face 条目(module_file + 前缀/目录 + module_path)
apps/admin/src/proto/mod.rs 新 face 加兄弟 include 块(注释原话:"one include per module face");PagingRequest impl 等手写段可改
src/auth_free.rs 部署白名单的唯一编辑点——改它要连带审视 tests/whitelist.rs 的双向钉

手写自由区:services/**(模式化样板)、data/**(实体/仓储/租户规则)、server/** 与 audit/**(装配/审计)、crates/auth(门)、proto/tables.rs(手写访问器)。判断口诀:带 Corpus 头、带 @generated、带 MANIFEST 锚、带 "DO NOT EDIT" 的,都不是你写的地方。

10. 本章小结

  • 契约同步进仓 + MANIFEST 门:proto 面不可手改,漂移必须显式接受;
  • 构建期一次编译产出两个面:注解描述符(路由/错误/绑定/trait)与 prost 类型(protojson);
  • 挂载对接只有一张表(mount_service! 逐行宏,mount_items() 收集),服务与路由的连接零手写;
  • 双 face 两把刀:admin face 整目录专属闭包(表 = 同步注册集),fork face root_prefix 切片(新模块不泄漏);
  • 新增 proto 的十二站里,只有 service 实现、模块种子与守卫计数是你要动手的,其余构建期自动;
  • 台架逐字节比对是契约改动的验收面。

下一步:04 · 第一个服务模块。