欢迎来到 protocol buffers 的开发者指南。protocol buffers 是一个语言中立，平台中立针对通讯协议，数据存储和其他领域中对结构化数据进行序列化的扩展方法。 本文档主要针对的是 Java，C++ 或 Python 的开发人员希望在开发的应用程序中使用 Protocol Buffers。这个有关 Protocol Buffers 摘要性的介绍将会告诉你如何开始使用 Protocol Buffers。如果你希望更加深入的了解有关 Protocol Buffers 的内容，你可以进入 tutorials 或者 protocol buffer encoding 页面来详细了解。 有关 API 的参考文档，请参考页面：reference documentation 这里提供了所有这 3 种语言的参考，同时也针对 .proto language 和 style 提供相关的指南。 什么是 Protocol Buffers？ Protocol buffers 是对结构化数据序列化的一个灵活，高效，自动化工具 —— 你可以将 Protocol buffers 想象成 XML，但是体积更小，更快也更加简单。 你可以自己定义你的结构化数据，然后你可以使用特定的代码生成工具来非常容易对你的结构化数据进行读取和写入。这些数据的读取和写入可以是一系列的数据流和使用不同的计算机程序语言。你甚至可以在不对已经部署的程序进行破坏的情况下更新你的数据结构。 Protocol Buffers 是如何进行工作的 你需要制定你希望如何将你的数据进行序列化。你是通过 proto 文件来定义你的消息结构化数据的。 每一 protocol buffer message 是一个小的信息记录逻辑，这个消息中包含有一系列的名字，变量对照序列。下面是一些基本的.proto 文件，这些文件中定义了一个消息，这个消息包含有一个 person 信息： message Person {   required string name = 1;   required int32 id = 2;   optional string email = 3;   enum PhoneType {     MOBILE = 0;     HOME = 1;     WORK = 2;   }   message PhoneNumber {     required string number = 1;     optional PhoneType type = 2 [default = HOME];   }   repeated PhoneNumber phone = 4; } 通过上面你可以看到这个消息的格式非常简单—— 每一个消息类型都有一个或者多个唯一进行编号的字段，每一个字段包含有一个名字和变量类型。 变量可以为数字（整形或者浮点型）（numbers），布尔类型（booleans），字符串（strings），原生二进制（raw bytes）甚至其他的 protocol buffer 消息类型，能够允许你分级的结构化你的数据。 你可以将字段指定为可选字段（optional fields），必须字段（required fields）和重复字段（repeated fields）。你可以从下面的 Protocol Buffer Language Guide 页面中找到更多有关 .proto 的定义。 一旦你成功定义了你的消息，你可以针对你使用的语言使用你定义的 .proto 来运行 protocol buffer 编译器（protocol buffer compiler）来生成数据访问类。 针对每一个字段，在数据访问类中提供了简单的访问方法（例如 name() 和 set_name()）和序列化到原生 2 进制数据和从原生 2 进制数据反序列化的方法。 针对上面的定义，如果你现在使用的是  C++ 语言的话，当你把消息定义进行编译后，你将会得到一个称为 Person 的类。 你可以使用这个类在你的应用程序中进行填充数据，对数据进行序列化和从序列化的数据中（protocol buffer 消息）重新获得 Person 数据。 然后你可以写一些类似 Person person; 的代码。 Person person; person.set_name("John Doe"); person.set_id(1234); person.set_email("jdoe@example.com"); fstream output("myfile", ios::out | ios::binary); person.SerializeToOstream(&output); 随后，你可以对消息进行读取： fstream input("myfile", ios::in | ios::binary); Person person; person.ParseFromIstream(&input); cout << "Name: " << person.name() << endl; cout << "E-mail: " << person.email() << endl; 你可以向你的消息中添加新的字段而不会损坏老的消息。这是因为在老的消息处理中，针对新的字段是完全忽略掉的。因此，如果你在你的通讯协议中使用 protocol buffers 为数据结构的话，你可以对你的协议和消息进行扩展而不需要担心老的代码没有办法编译通过，或者损坏老的代码。 你可以访问 API Reference section 页面中的内容来了解完整 protocol buffer 代码的生成和使用。 你也可以在 Protocol Buffer Encoding 页面中了解更多protocol buffer 消息是如何进行编码的。 为什么不使用 XML 针对 XML 来说 Protocol Buffers 具有更多的优势来对序列化结构数据。 更加简单 小于 XML  3 到 10 倍 快于 XML 20 到 100 倍 松耦合 使用程序工具来创建数据访问类，使数访问类更加简单 假设，你需要讲 person 这个数据进行定义，在 XML 你需要使用： <person>   <name>John Doe</name>   <email>jdoe@example.com</email> </person> 来进行定义。 在 Protocol Buffers 中针对上面的消息文本化（text format）后显示为： # Textual representation of a protocol buffer. # This is *not* the binary format used on the wire. person {   name: "John Doe"   email: "jdoe@example.com" } 当上面的消息被编码为 Protocol Buffer 二进制格式（binary format）上面的文字可能小于 28 bytes，并且可能需要 100-200 纳秒（nanoseconds）来进行处理。 我们将上面转换为可以人为读取的目的主要是为进行调试和编辑。 如果你使用 XML 的话，上面的信息至少需要 69 bytes （你需要删除所有的空格），同时你需要 5,000-10,000 纳秒（nanoseconds）来进行处理。 同时，对 protocol buffer 进行操作也是非常容易的： cout << "Name: " << person.name() <<…

文档编辑和持续集成状态： 本文档的 Protocol Buffer 的中文文档使用的是 Asciidoctor 进行编排的 http://docs.ossez.com/protocol-buffers-docs/index.html（本 WIKI 中的内容将会与在线发布的版本同步） Google Protocol Buffer( 简称 Protobuf) 是 Google 公司内部的混合语言数据标准，目前已经正在使用的有超过 48,162 种报文格式定义和超过 12,183 个 .proto 文件。 Protocol Buffer 相关快速导航 链接名称 链接地址 Protocol Buffer 中文文档 http://docs.ossez.com/protocol-buffers-docs/index.html 官方文档 https://developers.google.com/protocol-buffers/docs/overview 示例和测试代码 https://github.com/cwiki-us-demo/protocol-buffers-demo-java 如果你在互联网上搜索的话，你可能会看到下面的说明文字。 Google Protocol Buffer( 简称 Protobuf) 是 Google 公司内部的混合语言数据标准，目前已经正在使用的有超过 48,162 种报文格式定义和超过 12,183 个 .proto 文件。 他们用于 RPC 系统和持续数据存储系统。 Protocol Buffers 是一种轻便高效的结构化数据存储格式，可以用于结构化数据串行化，或者说序列化。 它很适合做数据存储或 RPC 数据交换格式。可用于通讯协议、数据存储等领域的语言无关、平台无关、可扩展的序列化结构数据格式。 目前提供了 C++、Java、Python 三种语言的 API。 我们是在实际的数据处理的时候，需要使用 JSON 来序列化数据，但是又考虑到 JSON 在传输的时候数据过大，同时还有很多并不需要的垃圾文件。我们才考虑到了 Protocol Buffer 提供的功能。 数据序列化和反序列化 序列化： 将数据结构或对象转换成二进制串的过程。 反序列化：将在序列化过程中所生成的二进制串转换成数据结构或者对象的过程。   https://www.cwiki.us/display/ProtocolBuffers/Protocol+Buffers

在进行开发 protoc 之前，你需要首先在你的计算机中安装 protoc 编译工具。 下载编译工具 进入 Protocol Buffers 的源代码中然后选择发布的版本中，找到对应的版本。项目的链接地址为：https://github.com/protocolbuffers/protobuf/releases 然后选择 https://github.com/protocolbuffers/protobuf/releases/download/v3.9.0/protoc-3.9.0-win64.zip，对应的版本进行下载。 请注意，如果你这里下载了 3.9.0 的版本的，那么在项目的 Gradle 文件也需要对应的 3.9.0 版本。 请下载对应的版本。 设置环境变量 在下载程序后，需要将下载 zip 文件中的 bin 目录设置到环境变量中。 然后运行 protoc --version 来确定你的编译运行版本已经被正确配置。 通过下图，可以查看配置的文件夹。 通过运行 protoc --version 来确定已经配置正确和编译器版本。 转换 Java 对象 假设我们有一个 proto 文件命名为：simple.proto simple.proto 的代码在 https://github.com/cwiki-us-demo/protocol-buffers-demo-java/blob/master/src/main/proto/simple.proto 页面中可以访问到。 你可以 Clone 项目到本地后进行执行。 你可以通过运行下面的命令来将 simple.proto 文件为基础生成一个 Java 对象 protoc --proto_path=src --java_out=src/main/java src/main/proto/simple.proto 生成结果如果正常的话，应该是没有输出的。 然后你访问特定的文件夹后就可以看到生成的 Java 对象。 生成的文件的路径和文件在  com.insight.demo.protocolbuffers.mode 这个包中。 请注意，你不能对手动对这个文件进行编译，这个文件都应该是通过程序自动生成的。 GitHub 示例源代码 本教程中的所有源代码都可以在 GitHub 中的 https://github.com/cwiki-us-demo/protocol-buffers-demo-java 项目访问到。 你可以 Clone 代码到你本地后进行运行测试。 https://www.cwiki.us/display/ProtocolBuffers/Protoc

如果你是第一次开始使用 Akka，我们推荐你先运行简单的 Hello World 项目。情况参考  Quickstart Guide 页面中的内容来下载和运行 Hello World 示例程序。上面链接中的 快速使用指南 来帮助你了解如何定义 actor 系统，actors 和消息，以及如何使用测试模块和日志系统。 在 30 分钟内，应该可以运行 Hello World 示例程序和项目的结构。 这个 快速使用指南  能够提供下一个级别的信息。这些文章提供了为什么  actor 模型符合现代分布式系统的需求同时包括了帮助你未来使用 Akka 需要的相关信息。主题包括有： Why modern systems need a new programming model How the actor model meets the needs of concurrent, distributed systems Overview of Akka libraries and modules 一些使用 Akka 设计模式用来构建 Hello World 的 更多的完整示例程序 https://www.cwiki.us/display/AkkaZH/Introduction+to+Akka

欢迎使用 Akka，Akka 是一套被用来在在多处理器核心和网络之间被设计可扩展和具有相关弹性的开源工具集。Akka 允许你更加关注商业需求而不是书写低级别的代码来提供可靠性，容错率和高性能。 很多常用的设计实践和已经接受的程序模型不能解决一些重要的挑战，这些挑战通常是现代计算机体系结构中固有的。为了让项目取得成功，分布式系统必须能够应付一些环境出现的问题，例如组件崩溃不能响应，发送的消息没有痕迹的就丢失了，为了让分布式系统能够成功的运行，以及网络延迟和波动等问题。这些问题在具有很好管理和监控环境下的数据中心经常会发生，针对虚拟架构环境就更加容易出现上面的这些问题了。 为了帮助你处理上面提到这些现实的问题，Akka 提供了： 不使用低级并发结构的多线程，例如原子或锁；让你免于考虑内存可见性的问题。 系统和组件之间的远程通讯透明性; 让你免于属性和维护复杂的网络代码。 一个高可用性的集群架构，这个集群具有相当的弹性，在线方式；让你真正能够部署一个反应系统。 Reactive System. A reactive system is a system that responds (reacts) to external events。 反应系统是一个能对外部事件做出相应反应的系统。早期所谓的reactive system是软件系统的一个分支，意思正如它的名字所描述的。后来这个概念被美国的David Harel明确下来，其最主要部分是描述反应行为。 什么是反应行为呢？下面看一个转换系统的例子 输入（开始）->软件系统（经过一段时间后停止运行）->（然后）输出 例子中用户把数据输入给计算机，软件对这些数据经过一段时间的计算，最后给出输出结果，我们可以看作一个会计的月结算或者一个测量的统计数据。 能够得知，输入数据经过特定的规则被转换，并且在结束计算过程以后给出结果。而reactive system却与此相反。 与转换系统相反，在reactive system里往往没有明确的时序安排。总体来讲，reactive system表示的是不限制运行时间的系统，这其中要和外部环境相互作用，也就是在外部刺激上的反应(reactive)，例如和不同使用者或者外部的硬件等，但是也包括内部发生的交流行为，因为reactive system是被集成在并行运行的分布式系统的规则中的。 例如，一个计算机的操作系统是这样一个reactive system，它不会停止运行,而总是反应用户给的输入,并且计算机中的各个组件之间要进行交流。 在电信领域，生产控制或者在硬件环境的构造（嵌入式系统）中还存在很多这样的例子。在信息系统中，也就是基于数据库的应用系统中也要用到 reactive system。在给一个典型的例子就是警报系统(Early Warning System). Akka 使用 actor 抽象模型能够让 Akka 更加容易的创建正确的并发，并行的分布式系统。actor 模型贯穿整个 Akka 的库，能够让你更加容易的理解和使用它们，并且能够保证更好的完整性。因此 Akka 提供了一个深度的整合和集成，如果你无法通过选择库来解决个别问题的时候，你可以尝试将这些整合在一起。 通过学习 Akka 和如何使用 actor 模型，你将访问到庞大和深入的工具集用来解决分布式并行系统中遇到的困难和挑战，通过统一的编程模型，其中所有的东西都能够紧密和高效的组合在了一起。   https://www.cwiki.us/display/AkkaZH/Introduction+to+Akka

问题 在进行 Travis CI 进行集成编译的时候出现错误。 <-------------> 0% WAITINGThe command "eval ./gradlew assemble " failed. Retrying, 2 of 3. FAILURE: Build failed with an exception. * What went wrong: Task 'assemble' not found in root project 'asciidoc-docs'. * Try: Run gradlew tasks to get a list of available tasks. Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights. * Get more help at https://help.gradle.org BUILD FAILED in 0s <-------------> 0% WAITINGThe command "eval ./gradlew assemble " failed. Retrying, 3 of 3. 具体的错误信息如下： BUILD FAILED in 8s <-------------> 0% WAITINGThe command "eval ./gradlew assemble " failed. Retrying, 2 of 3. FAILURE: Build failed with an exception. * What went wrong: Task 'assemble' not found in root project 'asciidoc-docs'. * Try: Run gradlew tasks to get a list of available tasks. Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights. * Get more help at https://help.gradle.org BUILD FAILED in 0s <-------------> 0% WAITINGThe command "eval ./gradlew assemble " failed. Retrying, 3 of 3. FAILURE: Build failed with an exception. * What went wrong: Task 'assemble' not found in root project 'asciidoc-docs'. * Try: Run gradlew tasks to get a list of available tasks. Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights. * Get more help at https://help.gradle.org BUILD…

问题 在 Travis CI 编译的时候出现 Error: Could not find or load main class org.gradle.wrapper.GradleWrapperMain 错误。 详细的错误日志为： Error: Could not find or load main class org.gradle.wrapper.GradleWrapperMain The command "eval ./gradlew assemble " failed. Retrying, 2 of 3. Error: Could not find or load main class org.gradle.wrapper.GradleWrapperMain The command "eval ./gradlew assemble " failed. Retrying, 3 of 3. Error: Could not find or load main class org.gradle.wrapper.GradleWrapperMain The command "eval ./gradlew assemble " failed 3 times. The command "./gradlew assemble" failed and exited with 1 during . Your build has been stopped.   解决方法 看看你提交的代码中 gradle 文件夹有没有提交上去。 如果没有提交这个文件夹的话，需要将源代码中的 gradle 提交到代码库上。