Cap'n Proto Schema语言从零开始:如何编写第一个.capnp文件(附8个核心语法要点)
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 与传统 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 个要点速查清单
- 文件头:
@0x...;唯一 ID,用capnp id生成,别照抄别人的。 - 注释:
#开头,习惯写在声明之后。 - 内置类型:
Bool/Int/UInt/Float/Text/Data/List(T)。 struct:字段从 0 连续编号@N,新增字段排在末尾。enum:有限符号值,成员也从 0 连续编号。union:表达"只有一个会被填值"的互斥字段。- 默认值 &
const:字段可带默认值,常量可用capnp eval求值。 - 编译:
capnp compile -o<语言> xxx.capnp生成源码。
把上面 8 条串起来,你就能读懂并写出 c++/samples/addressbook.capnp 这类真实示例,进而构建属于自己的 Cap'n Proto 序列化与 RPC 系统。建议以官方 Schema 语言参考 doc/language.md 为纲,结合 samples 目录下的示例边看边练,上手会非常快。
