技能介绍

解决什么问题

当你手里只有线上 JSON 样本，却要补 .proto 定义时，手写 schema 很慢，而且字段、嵌套、枚举和 gRPC 方法很容易和实际流量脱节。这个技能面向的是这类“从样例反推契约”的场景：它不是简单地生成一份看起来像 protobuf 的文本，而是把 JSON 样本当作输入，推断出 proto3 的结构，进而输出包含嵌套 message、enum 以及 gRPC service stubs 的定义。对于正在迁移、补文档或做接口兼容的工程师，价值在于先得到一版可评审的骨架，再围绕业务约束做收敛。

它如何工作

核心链路依赖 protobuf-compiler 与 grpcio-tools。前者提供协议编译器能力，后者提供 Python 侧的 protobuf/gRPC 工具链；结合样本推断，技能会把 JSON 对象映射为 message 字段，数组映射为 repeated 字段，稳定的有限取值集映射为 enum，并按推断到的服务方法补出 service stub。实际使用时，建议先准备能覆盖正常、边界与错误响应的代表性 JSON，再对生成结果做三轮校验：字段名是否符合项目约定、嵌套 message 是否过度或过浅、enum 是否遗漏合法值。生成后不要直接上线，应先编译并和真实调用链跑通一次。

适用边界与注意点

它适合快速得到 proto3 草案，不适合替代架构评审。JSON 样本无法表达业务语义，因此命名风格、字段是否必须、reserved 字段、custom options、oneof 冲突、时间格式和跨服务鉴权等都需要人工判断。若样本太少，推断结果可能过于具体；若样本太杂，又可能产生噪声字段。上游资料还列出了前置条件：需要可用的 Python 环境，并在工程中处理 protobuf-compiler / py_repositories 这类依赖加载。最终 .proto 仍是契约，需要纳入版本控制与代码评审。