feat(grpcgen): 分层控制 —— 每一层是下一层的默认值,不是另一条路

[Sunrisepeak]

实现 .agents/docs/2026-08-06-grpcgen-layered-control-design.md。

问题不是「不够方便」,是断崖

generate_all() 之外只有两个旋钮(proto_dir / grpc)。需求一超出,用户只能像 examples/helloworld 那样手写六十行 build.mcpp 绕开整个规则 —— 而那六十行要重新实现规则已经解决过的东西:well-known types 目录怎么定位、嵌套 .proto 的输出子目录怎么建、输入集合怎么算。它们会与规则悄悄漂移,且没有任何机制会报出漂移。

断崖本身就是设计缺陷:它把「优雅」和「可控」变成了二选一。

四层,不是四条路

L0  generate_all()
L1  generate_all({.extra_dirs=…, .imports=…, .mock=…, .protoc_args=…})
L2  generate_all({.plugins={cpp(), my_plugin}})
L3  auto e = plan_all(); /* 改 */ ; submit(e);

generate_all(opt) 就是 submit(plan_all(opt)),.grpc = true 就是 .plugins = {cpp()}。L0 逐字节不变。

extra_dirs 与 imports 是两件事 —— 写示例时撞出来的

不是设计时想到的。protoc 会把 #include "common/types.pb.h" 写进任何 import 了它的文件,所以只靠 -I 够到的共享树会产出一个没人生成的头:

fatal error: 'common/types.pb.h' file not found

而且报错离原因很远。于是分成两个概念:extra_dirs 既生成又搜索,imports 只搜索。这是 L1 里唯一一个不在原设计里的字段。

可观测性的分工由引擎定死,不由规则发明

核实过(不是推断):mcpp:action= 的边其完整 argv 原样落在 build.ninja 里,ninja -t commands <output> 即可取。所以规则不实现命令行 dump —— 第二个真相来源只会漂移。规则负责的是「哪些旋钮产生了它」,写进每次构建都打印的 description:

GENERATE protoc:orders (+grpc +mock, -Iproto -I../shared-proto)

mock:能生成,但本生态编不了,示例如实反映

--grpc_out=generate_mock_code=true:<dir> 是插件参数而非 protoc 顶层参数 —— 正是消费者不该被要求知道的拼写,所以做成具名选项。

生成的 mock 头 #include <gmock/gmock.h>,而 compat.gtest 只带 googletest、不带 gmock。因此示例声明并产出它、但不 include;plan 阶段断言它进了输出集,CI 再断言文件真的存在。

命名:codegen 不改

• protoc 只命名三者之一,且是 protobuf 那一半;buf 存在,换生成器就成谎话。
• 与 tonic 的歧义单向:tonic 的 codegen 指生成代码的运行时导出,C++ 里不存在对应物(生成的桩直接 #include <grpcpp/...> 并链同一个库)。
• L2 之后 codegen 更站得住:它表达「这个包知道 .proto 怎么变成 C++,包括你后来加的插件」。

真正欠的是文档,已补:codegen 是两步(--cpp_out 是 protobuf 的事,--grpc_out 才是 gRPC 的),以及默认关闭的真实理由 —— 官方 Generic API(GenericStub + ByteBuffer)是真实存在的无 codegen 路径,代理/LB 类服务的推荐做法。

本机验证

examples/advanced	service = orders.Orders / advanced: OK (messages + stubs, cross-root generation);产出含 common/types.pb.* 与两个 *_mock.grpc.pb.h
examples/greeter(L0)	从零重建,helloworld: OK —— 加法没有改变默认行为
examples/helloworld	从零重建,helloworld: OK