Cap'n Proto Schema语言从零开始:如何编写第一个.capnp文件(附8个核心语法要点)

原创2026-09-21 16:39:021,932 阅读
文章标签:后端通信

Cap'n Proto Schema语言从零开始:如何编写第一个.capnp文件(附8个核心语法要点)

Cap'n Proto 是一款高性能的序列化与 RPC 系统,它用一套强类型的 Schema 语言来描述消息结构。只要写一个 .capnp 文件并用 capnp compile 编译,就能生成 C++ 等语言的源码。本文面向新手和普通用户,从零讲解如何编写第一个 .capnp 文件,并整理出 8 个最核心的语法要点,帮你快速上手 Cap'n Proto 序列化与 RPC 开发。

先搞懂:.capnp 文件到底扮演什么角色?

和 JSON、MessagePack 这类"自描述"格式不同,Cap'n Proto 的消息是强类型的——它不会在数据里自带结构信息,而是要求你先用专门的 Schema 语言把"长什么样"写清楚。编译时,工具 capnp 会读取 .capnp 文件,为每种语言生成对应的操纵代码。

换句话说,一个 .capnp 文件就是整个系统的"契约":它定义了字段、类型、接口方法,也决定了线上数据如何编码、如何向后兼容。官方对这套语法的完整说明见 doc/language.md。

Cap'n Proto 序列化与 RPC 相比传统方案的优势

上图直观展示了 Cap'n Proto RPC 与传统 RPC 的差异:它支持"承诺链式调用(promise pipelining)",能把多次网络往返压缩成一次,这也是 Schema 里 interface 设计的底层价值。

要点 1:用唯一文件 ID 开头(@0x...;)

每个 .capnp 文件的第一行必须是一个 64 位唯一文件 ID,用来在系统里无歧义地标识这个文件。它由 capnp id 命令随机生成:

capnp id
# 输出类似:@0x9eb32e19f86ee174

把结果复制成文件头即可。新手常踩的坑是"直接照抄示例文件的 ID"——不同文件必须使用各自独立的 ID,否则可能冲突。

@0x9eb32e19f86ee174;   # 文件唯一 ID,由 capnp id 生成

要点 2:注释用 #,且写在声明之后

Cap'n Proto 的注释符号是 #,从出现处一直延伸到行尾。一个反直觉但重要的约定:文档式注释应该放在声明的"后面",而不是前面(同一行或下一行)。因为读代码时你几乎总是先看声明、再看注释。

year @0 :Int16;
# 年份,必须包含世纪;负值表示公元前。

month @1 :UInt8;   # 月份,1-12。

要点 3:认识内置基础类型

Cap'n Proto 自动提供一批内置类型,无需 import。掌握这张表,能覆盖 90% 的日常需求:

类型 说明
Void 空类型,只有一个值(常用作 union 成员)
Bool 布尔
Int8 / Int16 / Int32 / Int64 有符号整数
UInt8 / UInt16 / UInt32 / UInt64 无符号整数
Float32 / Float64 浮点数
Text 字符串,恒为 UTF-8 且以 NUL 结尾
Data 任意二进制字节串
List(T) 列表,T 是元素类型,如 List(Int32)
name @0 :Text;            # 字符串
age  @1 :UInt8;           # 无符号整数
tags @2 :List(Text);     # 字符串列表

要点 4:定义 struct 结构体与字段编号 @N

struct 是一组"带名字、带类型"的字段,字段从 0 开始连续编号。这个编号不是装饰——它记录着协议的演进顺序,编译器靠它保证新旧版本兼容。

规则(新手务必记住):

  • 编号必须从 0 起、连续递增,不能跳号(这点和 Protobuf 不同)。
  • 新增字段时,把它的编号排到现有字段之后,这样老数据依然能读。
struct Person {
  name    @0 :Text;
  email   @1 :Text;
  phones  @2 :List(PhoneNumber);
  birthdate @3 :Date;   # 较晚加入的字段,编号更大
}

上面的例子其实来自官方示例 c++/samples/addressbook.capnp,非常适合作为第一份 .capnp 的参考。

要点 5:声明 enum 枚举,表达有限符号值

enum 用于"一小撮固定的、有名字的值"。枚举成员同样从 0 开始连续编号。在支持数值枚举的语言里这些编号会被使用,但在 Cap'n Proto 里更应把它们当作"符号"而非数字。

enum Type {
  mobile @0;
  home   @1;
  work   @2;
}

枚举可以嵌套在 struct 内部,就近描述某个字段允许的取值,例如 addressbook.capnp 里的 PhoneNumber.Type 就是嵌套枚举的典型写法。

要点 6:用 union 表达"可选 / 互斥"字段

当一个结构体里有且只有一个字段会被填值(例如一个人的就业状态只能是"无业 / 雇主 / 学校 / 自由职业"之一),就使用 union。union 会自动维护一个"标签"来记录当前设置的是哪个成员,其余成员不占实际数据空间。

struct Person {
  # ...
  employment :union {
    unemployed   @4 :Void;
    employer     @5 :Text;
    school       @6 :Text;
    selfEmployed @7 :Void;
  }
}

两个细节:

  • union 成员和所属 struct 的普通字段共用同一套编号空间,继续往下编号即可。
  • 默认情况下,union 里编号最小的那个成员被视为"已设置"。若希望默认全空,就加一个编号最小的 unset 字段。

要点 7:设置默认值与定义 const 常量

字段可以带默认值,这样读取老数据时会自动填充。const 则定义编译期常量——它不影响线上编码,但会被写入生成的代码,还能被 capnp eval 求值,非常适合用来组织"带导入的配置"。

# 字段默认值
foo @0 :Int32 = 123;
bar @1 :Text = "default";

# 顶层常量(注意跨作用域引用时要用 `.` 前缀限定作用域)
const pi :Float64 = 3.14159;

官方示例 c++/samples/calculator.capnp 进一步展示了 enum、interface 与 union 的组合用法,想深入 RPC 时可以参考。

要点 8:用 capnp compile 编译你的第一个 .capnp 文件

写好 .capnp 后,用 capnp 工具把 Schema 编译成目标语言的源码。-o 后跟语言名(如 c++),工具会去找名为 capnpc-c++ 的插件来干活:

capnp compile -oc++ myschema.capnp
# 生成 myschema.capnp.h 与 myschema.capnp.c++

几个实用小命令(完整参考见 doc/capnp-tool.md):

命令 作用
capnp id 生成新的唯一文件 ID
capnp compile -ocapnp x.capnp 回显 Schema 并补全自动生成的 ID,排查 ID 问题很有用
capnp decode x.capnp MyType < m.bin 把二进制消息转成可读文本
capnp eval x.capnp myConst 求值 Schema 里的常量

小结:8 个要点速查清单

  1. 文件头:@0x...; 唯一 ID,用 capnp id 生成,别照抄别人的。
  2. 注释:# 开头,习惯写在声明之后。
  3. 内置类型:Bool / Int / UInt / Float / Text / Data / List(T)。
  4. struct:字段从 0 连续编号 @N,新增字段排在末尾。
  5. enum:有限符号值,成员也从 0 连续编号。
  6. union:表达"只有一个会被填值"的互斥字段。
  7. 默认值 & const:字段可带默认值,常量可用 capnp eval 求值。
  8. 编译:capnp compile -o<语言> xxx.capnp 生成源码。

把上面 8 条串起来,你就能读懂并写出 c++/samples/addressbook.capnp 这类真实示例,进而构建属于自己的 Cap'n Proto 序列化与 RPC 系统。建议以官方 Schema 语言参考 doc/language.md 为纲,结合 samples 目录下的示例边看边练,上手会非常快。

登录后查看全文
capnproto