- 编程语言
- 编译器
- 开发工具
【免费下载链接】grammars-v4
Grammars written for ANTLR v4; expectation that the grammars are free of actions.
本指南以 grammars-v4 仓库中的 thrift/Thrift.g4 文法为核心，系统讲解 Apache Thrift 接口定义语言（IDL）的完整语法结构：从document顶层规则到 header、definition、字段、函数、容器类型、注解与常量，再到词法层的注释与字面量处理。读者将掌握 Thrift IDL 文法的组成脉络、每个语法要素的书写规则，以及如何借助仓库内置的 示例文件 与 Maven 测试配置 验证文法并驱动代码生成。
背景：为 Thrift IDL 编写 ANTLR v4 文法
Apache Thrift 是一套跨语言的 RPC 与序列化框架，服务接口与数据结构使用专门的接口描述语言（IDL）书写，通常保存在扩展名为.thrift的源文件中。Thrift 官方编译器（compiler/cpp）内部使用 Bison 文法（thrifty.yy）解析这类文件；而 grammars-v4 仓库则提供了这套 IDL 的 ANTLR v4 实现，即 thrift/Thrift.g4。
该文法是仓库中"无内嵌动作（free of actions）"风格文法的典型代表：文法文件只描述语言的语法结构，不包含任何目标语言（Java、Go、Python 等）的语义动作，生成代码后由用户自行通过 Listener 或 Visitor 遍历语法树。从 thrift/desc.xml 可以看到，仓库针对该文法验证了Go;Java;JavaScript;PHP;Python3五类目标，而 thrift/pom.xml 则声明其模块名为thrift，描述为 "Apache Thrift IDL grammar"。
顶层结构：document = header* + definition* + EOF
文法的入口规则非常简洁（见 Thrift.g4）：
document : header* definition* EOF ;即一个合法的.thrift文件由零个或多个header（文件头声明）和零个或多个definition（类型与服务定义）组成，必须以文件结尾EOF结束。header与definition之间没有强制顺序，完全符合 Thrift IDL"先声明、后定义"的书写习惯，同时也允许空文件存在（例如EmptyStruct {}所在的测试文件仍以空 header 通过解析）。
header仅包含三种声明（见 Thrift.g4）：
header : include_ | namespace_ | cpp_include ;Header 声明：include、namespace 与 cpp_include
include：引用其他 thrift 文件
include_ : 'include' LITERAL ;include后跟一个字符串字面量（LITERAL），即被引用文件的路径。仓库示例 thrift/examples/thrift_project/Include.thrift 展示了其用法：
include "ThriftTest.thrift" struct IncludeTest { 1: required ThriftTest.Bools bools }被引用文件中的类型通过文件名.类型名的方式引用（ThriftTest.Bools）。
namespace：目标语言命名空间
namespace_ : 'namespace' '*' (IDENTIFIER | LITERAL) | 'namespace' IDENTIFIER (IDENTIFIER | LITERAL) type_annotations? | 'cpp_namespace' IDENTIFIER | 'php_namespace' IDENTIFIER ;namespace是 Thrift IDL 中控制代码生成的关键指令，文法支持三种形态：
- 通配命名空间：
namespace * thrift.test表示对所有语言生效； - 指定语言命名空间：
namespace java thrift.test、namespace go thrifttest等，其中第二个 token 可以是普通标识符，也可以是字符串字面量，并允许跟随可选注解type_annotations?； - 兼容旧写法：
cpp_namespace与php_namespace作为单独的 token 序列保留。
官方 ThriftTest.thrift 文件一口气声明了c_glib、cpp、delphi、go、java、js、lua、netstd、perl、php、py、py.twisted、rb、st、xsd十余种命名空间，并测试了namespace noexist ThriftTest（对应不存在生成器的语言仅产生告警）以及带注解的写法namespace xsd test (uri = 'http://thrift.apache.org/ns/ThriftTest')，覆盖了文法中type_annotations?分支。
cpp_include：向 C++ 生成代码插入头文件
cpp_include : 'cpp_include' LITERAL ;cpp_include用于在生成的 C++ 代码中额外包含指定头文件，后跟字符串字面量。
定义类型：const、typedef、enum、senum、struct、union、exception、service
definition是文法的核心（见 Thrift.g4），共八种：
definition : const_rule | typedef_ | enum_rule | senum | struct_ | union_ | exception | service ;const：常量定义
const_rule : 'const' field_type IDENTIFIER ('=' const_value)? list_separator? ;const声明一个具名常量，语法为const 类型 名称 = 常量值，其中= 常量值可选（即允许仅声明），且末尾允许一个可选的list_separator（逗号或分号，见下文）。典型示例：
const i32 INT32CONSTANT = 9853 const map<string,string> MAPCONSTANT = {'hello':'world', 'goodnight':'moon'} const string VERSION = "19.33.0" const Numberz myNumberz = Numberz.ONE前两例取自 DocTest.thrift，VERSION取自 cassandra.thrift，myNumberz取自 ThriftTest.thrift，可见常量值既可以是基本类型、map 字面量，也可以引用已定义的枚举值（Numberz.ONE）。
typedef：类型别名
typedef_ : 'typedef' field_type IDENTIFIER type_annotations? ;typedef将已有类型重命名为新标识符，并允许附加注解。仓库示例覆盖了多种形态：
typedef i64 UserId typedef map<string,Bonk> MapType typedef map<string, map<string, i16>> T1 typedef list<i32> ( cpp.template = "std::list" ) int_linked_list typedef string ( unicode.encoding = "UTF-16" ) non_latin_string (foo="bar") typedef list< double ( cpp.fixed_point = "16" ) > tiny_float_list前两个来自 ThriftTest.thrift，T1来自 eleme_test.thrift，后三个来自 AnnotationTest.thrift。注意文法允许typedef时同时给容器元素类型加注解（list< double (cpp.fixed_point = "16") >），并且type_annotations?既出现在typedef规则尾部的类型名之后，也允许在field_type/container_type中内嵌。
enum 与 senum：枚举
enum_rule : 'enum' IDENTIFIER '{' enum_field* '}' type_annotations? ; enum_field : IDENTIFIER ('=' integer)? type_annotations? list_separator? ;enum定义枚举，成员是标识符，可带= 整数显式赋值、可选注解与可选列表分隔符。经典示例（ThriftTest.thrift）：
enum Numberz { ONE = 1, TWO, THREE, FIVE = 5, SIX, EIGHT = 8 }未赋值的成员（TWO、THREE）由编译器按顺序自动编号，这符合 Thrift IDL 语义。enum整体还允许尾部注解，如 AnnotationTest.thrift 中的enum weekdays {...} (foo.bar="baz")与成员级注解SUNDAY ( weekend = "yes" )。
senum是 Thrift 的字符串枚举（已废弃但文法仍支持）：
senum : 'senum' IDENTIFIER '{' (LITERAL list_separator?)* '}' type_annotations? ;即枚举成员是字符串字面量而非标识符，AnnotationTest.thrift 给出了senum seasons { "Spring", "Summer", "Fall", "Winter" } ( foo = "bar" )的完整示例，并在注释中特别说明 senum 成员不支持注解。
struct、union、exception：复合数据结构
三者语法结构完全相同（见 Thrift.g4），只是关键字不同：
struct_ : 'struct' IDENTIFIER '{' field* '}' type_annotations? ; union_ : 'union' IDENTIFIER '{' field* '}' type_annotations? ; exception : 'exception' IDENTIFIER '{' field* '}' type_annotations? ;- struct：普通结构体，字段可有
required/optional约束； - union：联合体，同一时刻只允许一个字段被赋值，如 ThriftTest.thrift 中的
SomeUnion； - exception：异常类型，用于 service 方法抛出，如：
exception Xception { 1: i32 errorCode, 2: string message }三者都允许在}之后附加type_annotations?，例如 ThriftTest.thrift 的struct Insanity {...} (python.immutable= "")。
service：服务接口
service : 'service' IDENTIFIER ('extends' IDENTIFIER)? '{' function_* '}' type_annotations? ;service定义 RPC 服务，可继承另一个 service（extends），函数列表放在花括号内，整体支持注解。文法中('extends' IDENTIFIER)?是可选的继承分支，配合function_*表示服务可以没有方法。
字段与函数：field、function_、oneway、throws
字段（field）
field : field_id? field_req? field_type IDENTIFIER ('=' const_value)? type_annotations? list_separator? ; field_id : integer ':' ; field_req : 'required' | 'optional' ;字段由五个可选/必选部分组成：
- 字段编号
field_id?：形如1:的整数加冒号，这是 Thrift 二进制协议的传输标识，必须全局唯一； - 约束
field_req?：required（必填）或optional（可选），也可缺省（默认default语义）； - 类型
field_type（必选）； - 名称
IDENTIFIER（必选）； - 默认值
('=' const_value)?、注解type_annotations?、列表分隔符list_separator?均可选。
综合示例（eleme_test.thrift 与 ThriftTest.thrift）：
exception E1 { 1: required string name, 2: required string message } struct CrazyNesting { 1: string string_field, 2: optional set<Insanity> set_field, 3: required list<map<set<i32> (python.immutable = ""), map<i32,set<list<map<Insanity,string>(python.immutable = "")> (python.immutable = "")>>>> list_field, 4: binary binary_field }CrazyNesting展示了注解内嵌在容器类型参数中的深层嵌套写法，是文法对field_type递归能力的重要验证用例。
函数（function_）与 oneway、throws
function_ : oneway? function_type IDENTIFIER '(' field* ')' throws_list? type_annotations? list_separator? ; oneway : ('oneway' | 'async') ; function_type : field_type | 'void' ; throws_list : 'throws' '(' field* ')' ;service 中的每个方法包含：
- 可选的
oneway修饰（同时接受oneway与async两种关键字），表示异步单向调用，不等待响应； - 返回类型
function_type：普通field_type或void； - 方法名
IDENTIFIER； - 参数列表
'(' field* ')'（参数同样是完整 field 语法）； - 可选的
throws_list异常列表； - 可选的注解与列表分隔符。
例如 eleme_test.thrift 中的 service：
service Test { Args test(1: list<S1> list1, 2: T1 map1, 3: T2 map2) throws (1: E1 exception1); void void_call(); oneway void oneway_set_hehe(1: double hehe); binary bin(1: binary data); map<i32,string> def_req_arg(1: i32 i = 233, 2: string s = "hehe"); }其中oneway void oneway_set_hehe(...)直接对应文法oneway?+function_type分支，参数默认值1: i32 i = 233对应field规则中的('=' const_value)?。
类型系统：base_type、container_type 与 cpp_type
field_type归纳为三种（见 Thrift.g4）：
field_type : base_type // 基础类型 | IDENTIFIER // 引用已定义类型（struct/typedef/enum 名称） | container_type // 容器类型 ;基础类型（base_type）
base_type : real_base_type type_annotations? ; real_base_type : TYPE_BOOL | TYPE_BYTE | TYPE_I16 | TYPE_I32 | TYPE_I64 | TYPE_DOUBLE | TYPE_STRING | TYPE_BINARY ;词法上对应 8 个关键字 token（Thrift.g4）：bool、byte、i16、i32、i64、double、string、binary。其中binary用于原始字节串。基础类型之后允许直接附加type_annotations?（如string ( unicode.encoding = "UTF-16" )）。
容器类型（container_type）
container_type : (map_type | set_type | list_type) type_annotations? ; map_type : 'map' cpp_type? '<' field_type COMMA field_type '>' ; set_type : 'set' cpp_type? '<' field_type '>' ; list_type : 'list' '<' field_type '>' cpp_type? ; cpp_type : 'cpp_type' LITERAL ;三种容器在文法细节上略有差异：
map<key, value>：cpp_type?出现在'<'之前，键值类型之间用COMMA分隔；set<elem>：cpp_type?同样出现在尖括号前；list<elem>：cpp_type?反而出现在尖括号之后（'list' '<' field_type '>' cpp_type?）。
cpp_type用于覆盖 C++ 生成代码中的容器实现，例如map加cpp_type时可指定std::unordered_map等，其值是字符串字面量。容器类型整体还可以再带注解，例如 AnnotationTest.thrift 中的typedef list<i32> ( cpp.template = "std::list" ) int_linked_list。
常量与字面量：const_value、integer、DOUBLE、LITERAL
const_value
const_value : integer | DOUBLE | LITERAL | IDENTIFIER | const_list | const_map ;常量值可以是整数、浮点数、字符串字面量、标识符引用（如Numberz.ONE）、列表或 map。列表与 map 的定义如下：
const_list : '[' (const_value list_separator?)* ']' ; const_map_entry : const_value ':' const_value list_separator? ; const_map : '{' const_map_entry* '}' ;列表使用方括号[...]，map 使用花括号{key:value, ...}，元素之间允许可选的逗号或分号。DocTest.thrift中的MAPCONSTANT = {'hello':'world', 'goodnight':'moon'}即对应const_map规则。
数值与字符串词法
整数分十进制与十六进制两种（Thrift.g4）：
integer : INTEGER | HEX_INTEGER ; INTEGER : ('+' | '-')? DIGIT+ ; HEX_INTEGER : '-'? '0x' HEX_DIGIT+ ; DOUBLE : ('+' | '-')? (DIGIT+ ('.' DIGIT+)? | '.' DIGIT+) (('E' | 'e') INTEGER)? ;INTEGER允许正负号，HEX_INTEGER允许负数十六进制（-0x...），DOUBLE支持小数、1.与.5这类写法以及科学计数法（E/e）。
字符串字面量（Thrift.g4）支持单引号与双引号两种定界符，内部可包含转义序列：
LITERAL : '"' (ESC_SEQ | ~[\\"])* '"' | '\'' ( ESC_SEQ | ~[\\'])* '\'' ; fragment ESC_SEQ : '\\' [rnt"'\\] ;转义字符集合为\r \n \t \" \' \\五种。仓库专门准备了 thrift/examples/literal.thrift 验证转义嵌套场景：
const string default_user = "\'default_user\'" ; const string default_name = '"abc\'s"' ;第一行是双引号字符串内转义单引号，第二行是双引号字符串内直接包含单引号，均属于合法输入。
注解：type_annotations 与 type_annotation
注解是 Thrift IDL 扩展元数据的主要机制，文法中几乎每个定义末尾都预留了type_annotations?：
type_annotations : '(' type_annotation* ')' ; type_annotation : IDENTIFIER ('=' annotation_value)? list_separator? ; annotation_value : integer | LITERAL ;注解是圆括号包裹的名称或名称=值列表，值只能是整数或字符串字面量，条目之间可用逗号或分号。仓库中最全面的注解示例是 AnnotationTest.thrift，它验证了：
- 结构体级注解
( cpp.type = "DenseFoo", python.type = "DenseFoo", java.final = "", annotation.without.value, )——注意最后一个注解annotation.without.value没有值，对应文法IDENTIFIER ('=' annotation_value)?的可选分支； - 字段级注解
1: i32 bar ( presence = "required" )； - 枚举级与枚举成员级注解；
- 容器元素级注解（
list< double ( cpp.fixed_point = "16" ) >）。
词法层：标识符、空白与三种注释
标识符
IDENTIFIER : (LETTER | '_') (LETTER | DIGIT | '.' | '_')* ; fragment LETTER : 'A' ..'Z' | 'a' ..'z' ; fragment DIGIT : '0' ..'9' ;标识符以字母或下划线开头，后续可包含字母、数字、.与_。因此像ThriftTest.Bools、cpp.template（作为注解名）这样的带点写法在词法上就是一个完整的IDENTIFIER，由文法层按语境解释。
空白与注释
WS : (' ' | '\t' | '\r' '\n' | '\n')+ -> channel(HIDDEN) ; SL_COMMENT : ('//' | '#') (~'\n')* ('\r')? '\n' -> channel(HIDDEN) ; ML_COMMENT : '/*' .*? '*/' -> channel(HIDDEN) ;空白与注释全部进入HIDDEN通道，语法规则无需关心它们的分布。注释风格非常贴近 Thrift 实际文件：
- 行注释：
// ...与# ...两种前缀（#是 Unix 风格注释，常见于 thrift 文件头部的#!/usr/local/bin/thriftshebang 行，见 cassandra.thrift）； - 块注释：
/* ... */非贪婪匹配； - 文档注释
/** ... */在词法上属于块注释，例如 DocTest.thrift 中大量/** ... */形式，都被ML_COMMENT吸收而不会干扰解析。
仓库内的实战验证资源
要验证文法行为，无需额外搭建环境，仓库已提供完整的示例与自动化测试配置。
示例文件
thrift/examples 目录下有两类素材：
- 散落的独立文件：ThriftTest.thrift（418 行，来自 Thrift 官方测试套件）、cassandra.thrift（764 行，来自 Cassandra 的真实接口定义）、eleme_test.thrift、eleme_test2.thrift 以及 literal.thrift；
- thrift_project 子目录：21 个针对特定语法点的测试文件，包括
AnnotationTest.thrift（注解全集）、DocTest.thrift（文档注释）、Include.thrift（include 引用）、EnumContainersTest.thrift、ManyTypedefs.thrift、OptionalRequiredTest.thrift、DenseLinkingTest.thrift、DebugProtoTest.thrift等，几乎覆盖文法每一条规则。
Maven 测试链路
thrift/pom.xml 展示了从文法生成到回归测试的完整配置：
antlr4-maven-plugin将Thrift.g4作为唯一文法源（<include>Thrift.g4</include>），并开启visitor与listener两种代码生成模式；antlr4test-maven-plugin（来自 com.khubla.antlr）以document为入口规则、Thrift为文法名，把examples/目录下所有.thrift文件作为测试输入逐一解析，任何一条规则匹配失败都会导致测试失败。
<configuration> <entryPoint>document</entryPoint> <grammarName>Thrift</grammarName> <exampleFiles>examples/</exampleFiles> </configuration>这实际上把整套示例变成了文法的"回归测试套件"：ThriftTest.thrift与cassandra.thrift这类大型真实文件能通过解析，本身就是对文法覆盖度的强有力证明。此外 thrift/desc.xml 声明了Go;Java;JavaScript;PHP;Python3五个验证目标，说明该文法在这几种生成目标下均通过了仓库的静态检查与构建验证。
本地快速试用
在已安装 ANTLR 工具链（仓库根目录的 _scripts/antlr4-tools 提供了相应脚本）的前提下，可按如下流程本地体验：
# 1. 生成解析器（Java 目标） antlr4 Thrift.g4 # 2. 编译生成的 Java 代码 javac Thrift*.java # 3. 用 grun 以 document 为入口解析某个 thrift 文件并打印语法树 grun Thrift document -tree examples/ThriftTest.thrift若使用仓库的 Maven 结构，则直接执行mvn test（根 pom.xml 的grammarsv4父工程已集成上述插件），即可看到 antlr4test 插件逐文件解析examples/下全部样例的结果。注意：本仓库只读，以上命令仅用于本地查看与运行验证。
词法注意点与文法局限
从源码结构可以推断出该文法在覆盖范围上的一些特点，使用时值得留意：
- 关键字采用词法 token 而非解析器字符串：
bool、i16、map、struct等都以词法规则（TYPE_BOOL、TYPE_I16、map_type内的字面量等）形式出现，因此在 Thrift IDL 中它们不能作为普通标识符使用； - 不支持
i8关键字：Thrift 新版本将byte与i8视为同义词并鼓励使用i8（见 ThriftTest.thrift 的注释），但本文法real_base_type只收录了TYPE_BYTE（byte），未包含i8token。相应地，示例中的1: i8 byte_thing字段会被词法层解析为普通IDENTIFIER而非基础类型，这一点与 Thrift 官方编译器存在差异，从文法当前实现看应视为一个覆盖缺口； - 列表分隔符双轨制：
list_separator同时接受,与;，这兼容了 Thrift 历史文件中的两种写法，但也意味着解析时不会强制逗号； const_rule允许省略默认值：('=' const_value)?为可选，这与 Thrift 官方语法要求常量必须初始化的语义略有出入，属于文法相对宽松的体现。
上述推断均以 Thrift.g4 现有规则为准，若实际使用中遇到i8、async等扩展语法，需在文法层自行确认。
总结
grammars-v4 的 thrift/Thrift.g4 是一份无内嵌动作的 ANTLR v4 文法，完整覆盖了 Apache Thrift IDL 的 header（include/namespace/cpp_include）、八类定义（const、typedef、enum、senum、struct、union、exception、service）、字段与函数（含oneway、throws）、基础与容器类型、注解、常量字面量以及三种注释风格。它与 Thrift 官方 Bison 文法（thrifty.yy）功能对位，可用于构建独立的 IDL 解析、校验、代码生成或文档化工具链。仓库附带的 examples 目录（含官方 ThriftTest 与 Cassandra 真实接口文件）配合 pom.xml 的 antlr4test 配置，为文法的正确性与回归稳定性提供了可复现的验证路径。
许可
本仓库中的该模块遵循 Apache License 2.0（见 thrift/README.md 的 License 声明与各示例文件头部的 Apache 版权头），使用时请遵守相应许可条款。
- 编程语言
- 编译器
- 开发工具
【免费下载链接】grammars-v4
Grammars written for ANTLR v4; expectation that the grammars are free of actions.
相关推荐
Apache Thrift教程：从IDL文件到跨语言服务开发
Apache Thrift教程：从IDL文件到跨语言服务开发 前言 Apache Thrift作为一种高效的跨语言服务开发框架，其核心在于使用简单的接口定义语言
后端RPC框架序列化代码生成Apache Thrift IDL 语法完全指南：.thrift 接口描述语言规范与源码级解析
Apache Thrift IDL 语法完全指南：.thrift 接口描述语言规范与源码级解析 本指南以 Apache Thrift 官方 IDL 规范文档（
后端RPC框架序列化代码生成OpenWorker Coworker Google Docs & Sheets 连接器设计规格解析：按 URL 读取、分级授权的 Sheets 写入
OpenWorker Coworker Google Docs & Sheets 连接器设计规格解析：按 URL 读取、分级授权的 Sheets 写入 本篇技术
编程语言编译器开发工具
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
