为了避免和源代码的文件夹的冲突
This commit is contained in:
@@ -0,0 +1,47 @@
|
||||
# FHIR (Fast Health Interoperable Resources)
|
||||
|
||||
如果你对上面 2 个单词不熟悉的话，那就需要先脑补下了。
|
||||
|
||||
## HL7
|
||||
|
||||
HL7 可以认为是一个标准化的组织，这个组织主要对标准进行控制。
|
||||
|
||||
如果你希望在医疗系统中对数据进行交换，通常 HL7 现在就是事实上的标准了。
|
||||
|
||||
## FHIR
|
||||
|
||||
FHIR® – Fast Health Interoperable Resources (Index - FHIR v5.0.0) – 是由 HL7 提出的新一代标准框架。
|
||||
|
||||
FHIR 整合了 HL7 V2,V3 和 CDA 的优点,同时利用了最新的Web标准,紧紧围绕着 implementability 开发和实现。
|
||||
|
||||
|
||||
|
||||
有点绕？FHIR 是 HL7 标准化组织推出的标准，也就是现在医疗系统中使用的数据交换实现。
|
||||
|
||||
既然是实现，那么就需要基于 FHIR 标准有不同语言的实现了。
|
||||
|
||||
## FHIR Java 实现
|
||||
|
||||
FHIR Java 实现 目前应该使用的最多的是： https://hapifhir.io/
|
||||
|
||||
|
||||
|
||||
这个是一个开源版本的实现，所有的代码都在 GitHub 上能找到，地址为：https://github.com/hapifhir/hapi-fhir
|
||||
|
||||
如果你需要在 Java 中使用 FHIR 的话，应该直接使用上面的代码就可以了。
|
||||
|
||||
## 总结
|
||||
|
||||
HL7 是一个标准化租组织，他们定义了在医疗系统中进行数据传输的标准，FHIR 就是这标准的最新规范。
|
||||
|
||||
针对不同语言，有不同语言的实现罢了。
|
||||
|
||||
## 快速参考I
|
||||
|
||||
HL7 的内容还是比较多的，我们在这里对收集到的文档来进行整理。
|
||||
|
||||
| 网站名称 | 链接 | 备注说明 |
|
||||
|-----------------------|------------------------------------|---------------------|
|
||||
| 鲨鱼君（iSharkFly）FHIR 讨论 | https://www.isharkfly.com/tag/fhir | FHIR 相关技术在鲨鱼君平台上的讨论 |
|
||||
| HL7/FHIR | https://www.hl7.org/fhir/ | FHIR 标准的官方参考网站 |
|
||||
| HL7 | https://www.hl7.org/ | HL7 标准官方网站 |
|
||||
@@ -0,0 +1,179 @@
|
||||
|
||||
有关本文档的快速链接，请参考页面提示:
|
||||
|
||||
| 链接名称 | URL | 内容说明 |
|
||||
|----------------|-------------------------------------------------------------------------|------------------------------------|
|
||||
| GitHub MD 源代文件 | https://github.com/cwiki-us-docs/cwikius-docs/blob/master/jwt/README.md | 将本页面中的内容转换为 MD 文件的手册，并存于 Github 上面 |
|
||||
| Docsify 转换后的手册 | https://cwiki-us-docs.github.io/cwikius-docs/#/jwt/README | 将 MD 文件使用 Docsify 转换后的手册链接地址 |
|
||||
| 问题讨论和社区 | https://www.ossez.com/tag/jwt | 请访问使用 JWT 标签 |
|
||||
| CWIKI.US 页面链接 | https://www.cwiki.us/display/CWIKIUSDOCS/JWT+-+JSON+Web+Token | Confluence 平台的原始翻译文件更新地址 |
|
||||
|
||||
**NEW:** 获得 [免费的 JWT 手册（JWT Handbook）](https://auth0.com/resources/ebooks/jwt-handbook) 同时学习更多有关 JWT 的内容！
|
||||
|
||||
## 什么是 JSON Web Token（JWT）
|
||||
|
||||
JSON Web Token (JWT) 作为一个开放的标准 ([RFC 7519](https://tools.ietf.org/html/rfc7519)) 定义了一种简洁自包含的方法用于通信双方之间以 JSON 对象的形式安全的传递信息。因为有数字签名，所以这些通信的信息能够被校验和信任。
|
||||
|
||||
JWT 可以使用秘钥（secret）进行签名 (使用 **HMAC** 算法) 或使用 **RSA** 或 **ECDSA** 算法的公钥/私钥对（public/private key）。
|
||||
|
||||
尽管 JWT 可以在通讯的双方之间通过提供秘钥（secret）来进行签名，我们将会更多关注 **已签名（signed）**的 token。
|
||||
|
||||
通过签名的令牌可以验证其中数据的 *完整性（integrity）* ，而加密的令牌可以针对其他方 *隐藏（hide）* 申明。
|
||||
|
||||
当令牌（token）使用 公钥/私钥对（public/private key）进行签名的时候，只有持有私钥进行签名的一方是进行签名的。
|
||||
|
||||
### 关键术语的中英文对照
|
||||
* token - 令牌
|
||||
* secret - 秘钥
|
||||
* signature - 签名
|
||||
* claims - 要求或者数据
|
||||
|
||||
|
||||
## 什么时候应该使用 JSON Web Tokens
|
||||
在下面的一些场景中 JSON Web Tokens 可比较有用：
|
||||
|
||||
* **认证鉴权（Authentication）**： 这是 JWT 最常见的应用场景。一旦用户成功登入，在随后的每次请求中都将会包含JWT信息。 通过JWT的验证机制后，将允许该用户访问路由（routes）、服务（services）以及该Token所允许的资源。因为 JWT 的开销非常小，使其非常容易在跨域环境下使用，现如今 JWT 被广泛应用到单点登录（Single Sign On）中。
|
||||
|
||||
* **信息交换（Information Exchange）**： 因为 JSON Web Tokens 是可以进行签名的，因此 JWT 能够在不同系统之间安全的传递信息。
|
||||
|
||||
例如基于使用公钥/私钥对（public/private key pairs），你可以确保请求的发送者是可信的。
|
||||
|
||||
同时，因为头部（header）和负载（payload）的信息和内容都参与了计算，所以你可以验证内容是否被篡改过。
|
||||
|
||||
## JSON Web Token 的结构是什么？
|
||||
JSON Web Tokens 由使用 (`.`) 分开的 3 个部分组成的，这 3 个部分分别是：
|
||||
|
||||
- 头部（Header）
|
||||
- 负载（Payload）
|
||||
- 签名（Signature）
|
||||
|
||||
正是因为上面的组织形式，因此一个 JWT 通常看起如下面的表现形式。
|
||||
|
||||
`xxxxx.yyyyy.zzzzz`
|
||||
|
||||
让我们针对上面的形式来具体的分析下。
|
||||
|
||||
### 头部（Header）
|
||||
|
||||
在头部的数据中 *通常* 包含有 2 部分的内容：token 的类型，这里使用的是字符 JWT，和使用的的签名加密算法，例如 SHA256 或者 RSA。
|
||||
|
||||
例如下面的格式：
|
||||
|
||||
```
|
||||
{
|
||||
"alg": "HS256",
|
||||
"typ": "JWT"
|
||||
}
|
||||
```
|
||||
|
||||
然后，将上面的 JSON 数据格式使用 **Base64Url** 算法进行哈希，这样你就得到了 JWT 的第一部分。
|
||||
|
||||
### 负载（Payload）
|
||||
JWT 的第二部分为负载，在负载中是由一些 claims 组成的。 Claims 是一些实体（通常指用户）和其他的一一些信息。
|
||||
|
||||
有下面 3 种类型的 claims *registered*， *public* 和 *private* 。
|
||||
|
||||
**[Registered claims](https://tools.ietf.org/html/rfc7519#section-4.1)**：这些 claims 是预先定义的，这些配置的内容不是必须的但是是推荐使用的，因此提供了一系列约定俗成使用的。比如：iss（issuer）， exp（expiration time）, sub（subject），aud（audience）和其他的一些更多的配置。
|
||||
|
||||
请注意，这些约定俗称的配置只有 3 个字符，以便于压缩数据量。
|
||||
|
||||
|
||||
**[Public claims](https://tools.ietf.org/html/rfc7519#section-4.2)**：这些数据可以由使用 JWT 的用户自由去定义，但是为了避免冲突，你需要参考在 IANA JSON Web Token Registry 中对它们进行定义，或者将这些内容定义为 URI，并且需要避免可能出现的冲突。
|
||||
|
||||
**[Private claims](https://tools.ietf.org/html/rfc7519#section-4.3)**：这些内容是自定义的内容，这部分的内容被用于在数据传输短间进行转换的数据。这些数据是没有在 registered 和 public 中间没有定义的内容。
|
||||
|
||||
一个示例的负载：
|
||||
|
||||
````
|
||||
{
|
||||
"sub": "1234567890",
|
||||
"name": "John Doe",
|
||||
"admin": true
|
||||
}
|
||||
````
|
||||
|
||||
### 负载（payload）
|
||||
中的数据也是经过 Base64Url 进行加密的，这部分加密的内容组成了 JWT 的第二部分。
|
||||
|
||||
请注意：针对令牌这部分的签名已经被防范篡改。但是这部分还是可以被解密的，因此请不要将任何密钥放到这部分的数据中，除非你的密钥是已经加密过的密钥。
|
||||
|
||||
### 签名（Signature）
|
||||
为了创建一个加密部分，你需要有已经编码过的头部和负载，然后你还需要一个密钥（secret）和一个已经在头部中指定的加密算法来进行签名。
|
||||
|
||||
例如，如果你希望使用 HMAC SHA256 算法来进行签名，那么这个算法中使用的数据为：
|
||||
|
||||
````
|
||||
HMACSHA256(
|
||||
base64UrlEncode(header) + "." +
|
||||
base64UrlEncode(payload),
|
||||
secret)
|
||||
````
|
||||
签名的作用主要用于校验传输的令牌（Token）数据没有在过程中被篡改。
|
||||
|
||||
如果你的令牌是通过私有密钥进行签名的，那么也可以对 JWT 进行校验，以确定 JWT 的发送方使用是合法的签名。
|
||||
|
||||
## 将所有内容整合在一起
|
||||
|
||||
将这个 3 部分的内容使用 Base64-URL 编码后整合到一起，将每部分的数据直接使用 点号（.） 进行分隔，以确保令牌数据能够比较容易的在网络 HTTP 和 HTML 环境中进行传输。
|
||||
|
||||
针对使用 XML 的令牌，例如 SAML 来说，JWT 显得更加简洁和高效。
|
||||
|
||||
下面是使用了头部信息，负载信息和数字签名然后组合到一起的一个 JWT 令牌示例：
|
||||
|
||||
|
||||
|
||||
|
||||
如果你想使用 JWT，并且对一个已有的 JWT 令牌进行解密的话，你可以使用 https://jwt.io/#debugger-io 网站上提供的工具来对 JWT 字符串进行解密，校验和生产一个 JWT 令牌。
|
||||
|
||||
|
||||
|
||||
## JSON Web Tokens 是如何工作的
|
||||
在用户权限校验的过程中，一个用户如果使用授权信息成功登录后，一个 JSON Web Token 将会返回给用户端。
|
||||
|
||||
因为返回的令牌包含有授权信息，应用程序应小心保存这些授权信息，以避免不必要的安全问题。你的应用程序在不需要授权信息的时候，应用程序不应该保留授权成功后返回的令牌。
|
||||
|
||||
应用程序也不应该将这些敏感信息保存在浏览器中，因为这样会更加容易导致信息泄漏，请参考链接：https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html#local-storage 中的内容。
|
||||
|
||||
在任何时候，如果用户希望访问一个受保护的资源或者路由的时候，用户应该在访问请求中包含 JWT 令牌。通常这个令牌是存储在 HTTP 请求的头部信息，一般会使用 Authorization 字段，使用 Bearer 模式。
|
||||
|
||||
Http 头部发送给后台所包含的内容看起来如下所示：
|
||||
|
||||
|
||||
Authorization: Bearer <token>
|
||||
|
||||
在某些情况下，可以使用无状态的授权机制。服务器上受保护的路由将会检查随着访问提交的 JWT 令牌。如果令牌是有效的，用户将会被允许访问特定的资源。
|
||||
|
||||
如果 JWT 令牌中包含有必要的信息，服务器的服务端将不需要再次对数据库进行查询以加快访问速度。当然，不是所有的时候都可以这样进行处理。
|
||||
|
||||
当令牌随着头部中的 Authorization 信息一同发送，那么我们不需要使用 cookies，因此跨域访问（Cross-Origin Resource Sharing (CORS)）也不应该成为一个问题。
|
||||
|
||||
下面的示例图展示了JWT 是如何被获得的，同时也展示了 JWT 是如何被使用来访问服务器 API 的。
|
||||
|
||||
|
||||
|
||||
1. 应用程序或者客户端，通过对授权服务器的访问来获得授权。这个可能有不同的授权模式。例如，通常我们可以使用 OpenID Connect 提供的标准的授权地址来进行授权，请参考链接：http://openid.net/connect/。通常来说一个标准的授权地址为 /oauth/authorize，并且使用下面类似的标准授权流程，请参考链接：http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth 中的内容。
|
||||
2. 当授权完成后，授权服务器将会返回访问令牌（access token）给应用。
|
||||
3. 应用使用获得的令牌来访问收到保护的资源（例如 API）等。
|
||||
|
||||
需要注意的是，通过使用了签名的令牌，尽管用户可能没有办法对使用的令牌进行修改，但是令牌中包含的所有信息将会暴露给用户或者其他的应用。因此，你不应该在你的令牌中存储密钥或者任何的敏感信息。
|
||||
|
||||
|
||||
## 为什么我们需要使用 JSON Web Tokens
|
||||
|
||||
让我们讨论下 JSON Web Tokens (JWT) 针对 Simple Web Tokens (SWT) 和 Security Assertion Markup Language Tokens (SAML) 而言有什么优势吧。
|
||||
|
||||
相对 XML 来说，JSON 格式更加简洁，对 JSON 格式进行编码后的数据量更小，这就使得 JWT 相对 SAML 来说显得更加小巧，这使得 JWT 更加容易能够在 HTTP 和 HTML 环境之间传递数据。
|
||||
|
||||
在安全性上面，SWT 只能使用通过 HMAC 算法的对称方式签名。JWT 和 SAML 都可以使用基于 X.509 认证的公钥/私钥 密钥对的方式进行加密和解密。相比针对 JSON 格式的签名，针对XML 的数字签名更加容易导入安全漏洞。
|
||||
|
||||
在 JSON 格式的处理上，当前几乎所有的语言都能够支持和进行解析，这是因为 JSON 格式的数据更加容易映射到数据对象中。XML 则没有针对文本到对象的映射支持。这就导致了相对 SAML 来说，JWT 的处理更加容易。
|
||||
|
||||
在使用方面，JWT 已经被大量的在互联网上面取得了应用，针对多平台的使用上，JSON 格式在客户端上面更加容易被使用，尤其是针对移动平台。
|
||||
|
||||
针对 JSON 和 SAML 数据格式的内容对比，请参考下面的图片：
|
||||
|
||||
|
||||
|
||||
从上面的图片的对比上，我们可以看到基于 JSON 格式的内容更少，表达性更好。
|
||||
|
||||
如果你希望了解更多有关 JSON Web Tokens 的使用，并且打算开始在你的系统中应用这种格式，请参考由 Auth0 官方提供的介绍和文档，访问链接是：http://auth0.com/learn/json-web-tokens。
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
@@ -0,0 +1,549 @@
|
||||
# MessagePack 文档
|
||||
|
||||
中文标题【MessagePack Java 0.6.X 快速开始指南】
|
||||
|
||||
MessagePack 的相关文档，本文是根据官方的内容和我们项目中的具体实践进行编辑的。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
> :warning: 0.6.x 版本的 MessagePack 已经过期被淘汰了。如果你现在开始使用 MessagePack 话，请不要使用这个版本。
|
||||
|
||||
我们在这里保留 0.6.x 版本的内容主要用于参考用途。
|
||||
|
||||
最新的 MessagePack 版本请参考: https://github.com/msgpack/msgpack-java 中的项目源代码。
|
||||
|
||||
:information_source: MessagePack 中文文档请参考： http://docs.ossez.com/messagepack-docs/index.html
|
||||
|
||||
:information_source: MessagePack 测试和示例源代码： https://github.com/cwiki-us-demo/serialize-deserialize-demo-java
|
||||
|
||||
|
||||
这个指南提供了使用 msgpack-java 的快速指南。在开始的时候，我们将会介绍如何安装 msgpack-java，然后将会运行如何使用 msgpack 来对对象序列化/反序列化（serialize/deserizalize）对象。
|
||||
|
||||
## 安装
|
||||
你可以使用下面 2 种方法来安装 msgpack-java —— 从 maven 下载或者直接构建 jar 包。
|
||||
|
||||
### 从 Maven2 仓库中进行安装
|
||||
MessagePack 针对 Java 的使用已经发布到 Maven 的中央仓库中（Maven Central Repository）。你可以使用下面的参数来配置你项目的 pom.xml 文件。
|
||||
|
||||
````xml
|
||||
<dependency>
|
||||
<groupId>org.msgpack</groupId>
|
||||
<artifactId>msgpack</artifactId>
|
||||
<version>${msgpack.version}</version>
|
||||
</dependency>
|
||||
````
|
||||
|
||||
你需要将 ${msgpack.version} 替换为当前的 MessagePack 版本，有关可以使用的具体版本你可以访问 http://repo1.maven.org/maven2/org/msgpack/msgpack/ 中的版本。
|
||||
|
||||
请注意，在 0.6.x 版本中最新的版本只更新到 0.6.12。
|
||||
|
||||
### 从 git 仓库中进行安装
|
||||
你可以从代码仓库中获得最新的代码。
|
||||
|
||||
----
|
||||
```bash
|
||||
$ git clone git@github.com:msgpack/msgpack-java.git
|
||||
$ cd msgpack-java
|
||||
$ mvn package
|
||||
```
|
||||
|
||||
使用上面的代码进行编译后u，你将会在 msgpack-java/target 目录中得到 msgpack.jar 包。
|
||||
|
||||
同时你也需要 https://code.google.com/p/json-simple/ 和 https://github.com/jboss-javassist/javassist 来让 msgpack.jar 可以在项目中使用。否则你将会收到 NoClassDefFoundError 错误。
|
||||
|
||||
## 如何使用
|
||||
下面是如何使用的示例代码。
|
||||
|
||||
### 使用一个消息打包（message-packable）类
|
||||
使用注解 '_@Message_' 来让你可以序列化你自己类中对象的 public 字段。
|
||||
|
||||
本代码可以在 https://github.com/cwiki-us-demo/messagepack-6-demo-java/blob/master/src/test/java/com/insight/demo/msgpack/MessagePack6Object.java 中下载到本地后进行编译测试。
|
||||
|
||||
```java
|
||||
package com.insight.demo.msgpack;
|
||||
|
||||
import org.junit.Test;
|
||||
import org.msgpack.MessagePack;
|
||||
import org.msgpack.annotation.Message;
|
||||
import org.slf4j.Logger;
|
||||
import org.slf4j.LoggerFactory;
|
||||
|
||||
import java.util.UUID;
|
||||
|
||||
import static org.junit.Assert.assertEquals;
|
||||
|
||||
/**
|
||||
* MessagePack6Objects
|
||||
*
|
||||
* @author yhu
|
||||
*/
|
||||
public class MessagePack6Object {
|
||||
final Logger logger = LoggerFactory.getLogger(MessagePack6Object.class);
|
||||
|
||||
/**
|
||||
* MessageData Message Object
|
||||
*/
|
||||
@Message // Annotation
|
||||
public static class MessageData {
|
||||
// public fields are serialized.
|
||||
public String uuid;
|
||||
public String name;
|
||||
public double version;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Test MessagePack6Objects
|
||||
*/
|
||||
@Test
|
||||
public void testMessagePack6Objects() {
|
||||
logger.debug("MessagePack6Objects for Objects");
|
||||
|
||||
String uuid = UUID.randomUUID().toString();
|
||||
|
||||
// INIT OBJ
|
||||
MessageData src = new MessageData();
|
||||
src.uuid = uuid;
|
||||
src.name = "MessagePack6";
|
||||
src.version = 0.6;
|
||||
|
||||
try {
|
||||
MessagePack msgPack = new MessagePack();
|
||||
|
||||
// Serialization
|
||||
logger.debug("------ Serialization ------");
|
||||
byte[] bytes = msgPack.write(src);
|
||||
logger.debug("Bytes Array Length: [{}]", bytes.length);
|
||||
|
||||
// Deserialization
|
||||
logger.debug("------ Deserialization ------");
|
||||
MessageData dst = msgPack.read(bytes, MessageData.class);
|
||||
logger.debug("Check Object for UUID: [{}]", dst.uuid);
|
||||
|
||||
assertEquals(uuid, dst.uuid);
|
||||
|
||||
} catch (Exception ex) {
|
||||
logger.error("MessagePack Serialization And Deserialization error", ex);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果你希望按照顺序序列化多个对象的话，你可以使用 '_Packer_' 和 '_Unpacker_' 多个对象。
|
||||
|
||||
这是因为 '_MessagePack.write(Object)_' 和 '_read(byte[])_' 实际上每次都调用创建了 '_Packer_' 和 '_Unpacker_' 对象。
|
||||
|
||||
为了使用 '_Packer_' 和 '_Unpacker_' 对象，请调用 '_createPacker(OutputStream)_' 和 '_createUnpacker(InputStream)_'。
|
||||
|
||||
本代码可以 https://github.com/cwiki-us-demo/messagepack-6-demo-java/blob/master/src/test/java/com/insight/demo/msgpack/MessagePack6Objects.java 中查看。
|
||||
|
||||
|
||||
```java
|
||||
package com.insight.demo.msgpack;
|
||||
|
||||
import org.junit.Test;
|
||||
import org.msgpack.MessagePack;
|
||||
import org.msgpack.annotation.Message;
|
||||
import org.msgpack.packer.Packer;
|
||||
import org.msgpack.unpacker.Unpacker;
|
||||
import org.slf4j.Logger;
|
||||
import org.slf4j.LoggerFactory;
|
||||
|
||||
import java.io.ByteArrayInputStream;
|
||||
import java.io.ByteArrayOutputStream;
|
||||
import java.util.UUID;
|
||||
|
||||
import static org.junit.Assert.assertEquals;
|
||||
|
||||
/**
|
||||
* MessagePack6Objects
|
||||
*
|
||||
* @author yhu
|
||||
*/
|
||||
public class MessagePack6Objects {
|
||||
final Logger logger = LoggerFactory.getLogger(MessagePack6Objects.class);
|
||||
|
||||
/**
|
||||
* MessageData Message Objects
|
||||
*/
|
||||
@Message // Annotation
|
||||
public static class MessageData {
|
||||
// public fields are serialized.
|
||||
public String uuid;
|
||||
public String name;
|
||||
public double version;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Test MessagePack6Objects
|
||||
*/
|
||||
@Test
|
||||
public void testMessagePack6Objects() {
|
||||
logger.debug("MessagePack6Objects for Objects");
|
||||
|
||||
String uuid = UUID.randomUUID().toString();
|
||||
|
||||
// INIT OBJ
|
||||
MessageData src1 = new MessageData();
|
||||
src1.uuid = uuid;
|
||||
src1.name = "MessagePack6-src1";
|
||||
src1.version = 0.6;
|
||||
|
||||
MessageData src2 = new MessageData();
|
||||
src2.uuid = uuid;
|
||||
src2.name = "MessagePack6-src2";
|
||||
src2.version = 10.6;
|
||||
|
||||
MessageData src3 = new MessageData();
|
||||
src3.uuid = uuid;
|
||||
src3.name = "MessagePack6-src3";
|
||||
src3.version = 1.6;
|
||||
|
||||
try {
|
||||
MessagePack msgPack = new MessagePack();
|
||||
|
||||
// Serialization
|
||||
logger.debug("------ Serialization ------");
|
||||
ByteArrayOutputStream out = new ByteArrayOutputStream();
|
||||
Packer packer = msgPack.createPacker(out);
|
||||
packer.write(src1);
|
||||
packer.write(src2);
|
||||
packer.write(src3);
|
||||
|
||||
byte[] bytes = out.toByteArray();
|
||||
logger.debug("Bytes Array Length: [{}]", bytes.length);
|
||||
|
||||
// Deserialization
|
||||
logger.debug("------ Deserialization ------");
|
||||
ByteArrayInputStream in = new ByteArrayInputStream(bytes);
|
||||
Unpacker unpacker = msgPack.createUnpacker(in);
|
||||
|
||||
MessageData dst1 = unpacker.read(MessageData.class);
|
||||
MessageData dst2 = unpacker.read(MessageData.class);
|
||||
MessageData dst3 = unpacker.read(MessageData.class);
|
||||
|
||||
logger.debug("Check Object for UUID: [{}]", dst1.uuid);
|
||||
|
||||
assertEquals(uuid, dst1.uuid);
|
||||
|
||||
} catch (Exception ex) {
|
||||
logger.error("MessagePack Serialization And Deserialization error", ex);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 多种类型变量的序列化和反序列化（serialization/deserialization）
|
||||
|
||||
类 '_Packer/Unpacker_' 允许序列化和反序列化多种类型的变量，如后续程序所示。这个类启用序列化和反序列化多种类型的变量和序列化主要类型变量以及包装类，'_String_' 对象，
|
||||
'_byte[]_' 对象，'_ByteBuffer 对象等的方法相似。
|
||||
|
||||
如上面提示的，你可以序列化和反序列化你自己的对象，前提是你自己的对象需要使用 '_@Message_' 注解。
|
||||
|
||||
本代码可以在 https://github.com/cwiki-us-demo/messagepack-6-demo-java/blob/master/src/test/java/com/insight/demo/msgpack/MessagePack6Types.java 中查看。
|
||||
|
||||
```java
|
||||
package com.insight.demo.msgpack;
|
||||
|
||||
import org.junit.Test;
|
||||
import org.msgpack.MessagePack;
|
||||
import org.msgpack.packer.Packer;
|
||||
import org.msgpack.unpacker.Unpacker;
|
||||
import org.slf4j.Logger;
|
||||
import org.slf4j.LoggerFactory;
|
||||
|
||||
import java.io.ByteArrayInputStream;
|
||||
import java.io.ByteArrayOutputStream;
|
||||
import java.math.BigInteger;
|
||||
import java.nio.ByteBuffer;
|
||||
|
||||
/**
|
||||
* MessagePack6Types
|
||||
*
|
||||
* @author yhu
|
||||
*/
|
||||
public class MessagePack6Types {
|
||||
final Logger logger = LoggerFactory.getLogger(MessagePack6Types.class);
|
||||
|
||||
|
||||
/**
|
||||
* Test MessagePack6Types
|
||||
*/
|
||||
@Test
|
||||
public void testMessagePack6Types() {
|
||||
logger.debug("testMessagePack6Types for Types");
|
||||
|
||||
MessagePack msgpack = new MessagePack();
|
||||
try {
|
||||
|
||||
//
|
||||
// Serialization
|
||||
//
|
||||
ByteArrayOutputStream out = new ByteArrayOutputStream();
|
||||
Packer packer = msgpack.createPacker(out);
|
||||
|
||||
// Serialize values of primitive types
|
||||
packer.write(true); // boolean value
|
||||
packer.write(10); // int value
|
||||
packer.write(10.5); // double value
|
||||
|
||||
// Serialize objects of primitive wrapper types
|
||||
packer.write(Boolean.TRUE);
|
||||
packer.write(new Integer(10));
|
||||
packer.write(new Double(10.5));
|
||||
|
||||
// Serialize various types of arrays
|
||||
packer.write(new int[]{1, 2, 3, 4});
|
||||
packer.write(new Double[]{10.5, 20.5});
|
||||
packer.write(new String[]{"msg", "pack", "for", "java"});
|
||||
packer.write(new byte[]{0x30, 0x31, 0x32}); // byte array
|
||||
|
||||
// Serialize various types of other reference values
|
||||
packer.write("MessagePack"); // String object
|
||||
packer.write(ByteBuffer.wrap(new byte[]{0x30, 0x31, 0x32})); // ByteBuffer object
|
||||
packer.write(BigInteger.ONE); // BigInteger object
|
||||
|
||||
//
|
||||
// Deserialization
|
||||
//
|
||||
byte[] bytes = out.toByteArray();
|
||||
ByteArrayInputStream in = new ByteArrayInputStream(bytes);
|
||||
Unpacker unpacker = msgpack.createUnpacker(in);
|
||||
|
||||
// to primitive values
|
||||
boolean b = unpacker.readBoolean(); // boolean value
|
||||
int i = unpacker.readInt(); // int value
|
||||
double d = unpacker.readDouble(); // double value
|
||||
|
||||
// to primitive wrapper value
|
||||
Boolean wb = unpacker.read(Boolean.class);
|
||||
Integer wi = unpacker.read(Integer.class);
|
||||
Double wd = unpacker.read(Double.class);
|
||||
|
||||
// to arrays
|
||||
int[] ia = unpacker.read(int[].class);
|
||||
Double[] da = unpacker.read(Double[].class);
|
||||
String[] sa = unpacker.read(String[].class);
|
||||
byte[] ba = unpacker.read(byte[].class);
|
||||
|
||||
// to String object, ByteBuffer object, BigInteger object, List object and Map object
|
||||
String ws = unpacker.read(String.class);
|
||||
ByteBuffer buf = unpacker.read(ByteBuffer.class);
|
||||
BigInteger bi = unpacker.read(BigInteger.class);
|
||||
|
||||
} catch (Exception ex) {
|
||||
logger.error("MessagePack Serialization And Deserialization error", ex);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
方法 '_Packer#write()_' 允许序列化多种类型的数据。
|
||||
|
||||
类 '_Unpacker_' 针对反序列化二进制数据为主要变量，提供了一个反序列化方法。例如，你希望将二进制数据反序列化为 '_boolean_' (或者 '_int_') 数据类型，你可以使用 '_Unpacker_' 中的 '_readBoolean_' (或者 '_readInt_') 方法。
|
||||
|
||||
'_Unpacker_' 同时也为参考变量提供了一个读取的方法。这个方法允许为一个参考变量从二进制数据中进行反序列化。参考变量的定义为你将类型指定为一个参数。
|
||||
例如，你希望反序列化二进制数据到 '_String_' (或者 '_byte[]_') 对象，你必须在调用 '_read(String.class)_' (或者 '_read(byte[].class)_') 方法的时候定义描述。
|
||||
|
||||
## List, Map 对象的序列化和反序列化（serialization/deserialization）
|
||||
为了序列化原生的容器对象例如 '_List_' 和 '_Map_' 对象，你必须使用 '_Template_'。
|
||||
|
||||
'_Template_' 对象是 serializer 和 deserializer 的配对。例如，为了序列化一个 '_List_' 对象，在 '_List_' 对象中 '_Integer_' 对象为元素，你可以使用下面的方法来创建一个模板对象（Template object）。
|
||||
|
||||
```java
|
||||
Template listTmpl = Templates.tList(Templates.TInteger);
|
||||
```
|
||||
|
||||
类 '_tList_'， '_TInteger_' 是静态方法，字段为 '_Templates_'。
|
||||
|
||||
一个 '_List 和 '_Map_' 对象的用例如下显示：
|
||||
|
||||
本代码可以在 https://github.com/cwiki-us-demo/messagepack-6-demo-java/blob/master/src/test/java/com/insight/demo/msgpack/MessagePack6Template.java 中查看。
|
||||
|
||||
```java
|
||||
package com.insight.demo.msgpack;
|
||||
|
||||
import org.junit.Test;
|
||||
import org.msgpack.MessagePack;
|
||||
import org.msgpack.packer.Packer;
|
||||
import org.msgpack.template.Template;
|
||||
import org.msgpack.unpacker.Unpacker;
|
||||
import org.slf4j.Logger;
|
||||
import org.slf4j.LoggerFactory;
|
||||
|
||||
import java.io.ByteArrayInputStream;
|
||||
import java.io.ByteArrayOutputStream;
|
||||
import java.math.BigInteger;
|
||||
import java.nio.ByteBuffer;
|
||||
import java.util.ArrayList;
|
||||
import java.util.HashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
import static org.msgpack.template.Templates.*;
|
||||
|
||||
/**
|
||||
* MessagePack6Template
|
||||
*
|
||||
* @author yhu
|
||||
*/
|
||||
public class MessagePack6Template {
|
||||
final Logger logger = LoggerFactory.getLogger(MessagePack6Template.class);
|
||||
|
||||
|
||||
/**
|
||||
* Test MessagePack6Template
|
||||
*/
|
||||
@Test
|
||||
public void testMessagePack6Template() {
|
||||
logger.debug("MessagePack6Template for Template");
|
||||
|
||||
MessagePack msgpack = new MessagePack();
|
||||
try {
|
||||
|
||||
// Create templates for serializing/deserializing List and Map objects
|
||||
Template<List<String>> listTmpl = tList(TString);
|
||||
Template<Map<String, String>> mapTmpl = tMap(TString, TString);
|
||||
|
||||
//
|
||||
// Serialization
|
||||
//
|
||||
|
||||
ByteArrayOutputStream out = new ByteArrayOutputStream();
|
||||
Packer packer = msgpack.createPacker(out);
|
||||
|
||||
// Serialize List object
|
||||
List<String> list = new ArrayList<String>();
|
||||
list.add("msgpack");
|
||||
list.add("for");
|
||||
list.add("java");
|
||||
packer.write(list); // List object
|
||||
|
||||
// Serialize Map object
|
||||
Map<String, String> map = new HashMap<String, String>();
|
||||
map.put("sadayuki", "furuhashi");
|
||||
map.put("muga", "nishizawa");
|
||||
packer.write(map); // Map object
|
||||
|
||||
//
|
||||
// Deserialization
|
||||
//
|
||||
|
||||
byte[] bytes = out.toByteArray();
|
||||
ByteArrayInputStream in = new ByteArrayInputStream(bytes);
|
||||
Unpacker unpacker = msgpack.createUnpacker(in);
|
||||
|
||||
// to List object
|
||||
List<String> dstList = unpacker.read(listTmpl);
|
||||
|
||||
// to Map object
|
||||
Map<String, String> dstMap = unpacker.read(mapTmpl);
|
||||
|
||||
} catch (Exception ex) {
|
||||
logger.error("MessagePack Serialization And Deserialization error", ex);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 不使用注解（annotations）来序列化
|
||||
如果你不能添加 @Message 到你的定义对象中但是你还是希望进行序列化。你可以使用 register 方法来在类中启用序列化对象。
|
||||
|
||||
如下的代码所示：
|
||||
|
||||
```java
|
||||
MessagePack msgpack = new MessagePack();
|
||||
msgpack.register(MyMessage2.class);
|
||||
```
|
||||
|
||||
例如，如果 MyMessage2 类被包含到了外部的库中了。你没有办法比较容易的编辑源代码，添加 '_@Message_' 到源代码中。
|
||||
|
||||
register 方法能够允许为 MyMessage2 自动创建一个 serializer 和 deserializer 对。
|
||||
|
||||
你可以在执行方面后序列化对象 MyMessage2。
|
||||
|
||||
### 可选字段
|
||||
你可添加一个新的字段来保持可用性。在新字段中使用 '_@Optional_' 注解。
|
||||
|
||||
```java
|
||||
@Message
|
||||
public static class MyMessage {
|
||||
public String name;
|
||||
public double version;
|
||||
|
||||
// new field
|
||||
@Optional
|
||||
public int flag = 0;
|
||||
}
|
||||
```
|
||||
|
||||
如果你尝试反序列化老版本数据的话，可选字段将会被忽略。
|
||||
|
||||
### 动态类型
|
||||
我们知道 Java 是一个静态类型的语言。通过输入 '_Value_' MessagePack能够实现动态的特性。
|
||||
|
||||
'_Value_' 有方法来检查自己的类型（'_isIntegerType()_', '_isArrayType()_', 等...)，同时也转换为自己的类型 ('_asStringValue()_', '_convert(Template)_'）。
|
||||
|
||||
本代码可以在 https://github.com/cwiki-us-demo/messagepack-6-demo-java/blob/master/src/test/java/com/insight/demo/msgpack/MessagePack6DynamicTyping.java 中查看。
|
||||
|
||||
```java
|
||||
package com.insight.demo.msgpack;
|
||||
|
||||
import org.junit.Test;
|
||||
import org.msgpack.MessagePack;
|
||||
import org.msgpack.type.Value;
|
||||
import org.msgpack.unpacker.Converter;
|
||||
import org.slf4j.Logger;
|
||||
import org.slf4j.LoggerFactory;
|
||||
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
|
||||
import static org.msgpack.template.Templates.TString;
|
||||
import static org.msgpack.template.Templates.tList;
|
||||
|
||||
/**
|
||||
* MessagePack6Objects
|
||||
*
|
||||
* @author yhu
|
||||
*/
|
||||
public class MessagePack6DynamicTyping {
|
||||
final Logger logger = LoggerFactory.getLogger(MessagePack6DynamicTyping.class);
|
||||
|
||||
|
||||
/**
|
||||
* Test MessagePack6Objects
|
||||
*/
|
||||
@Test
|
||||
public void MessagePack6DynamicTyping() {
|
||||
logger.debug("MessagePack6Objects for Objects");
|
||||
|
||||
// Create serialize objects.
|
||||
List<String> src = new ArrayList<String>();
|
||||
src.add("msgpack");
|
||||
src.add("kumofs");
|
||||
src.add("viver");
|
||||
|
||||
MessagePack msgpack = new MessagePack();
|
||||
|
||||
try {
|
||||
|
||||
// Serialize
|
||||
byte[] raw = msgpack.write(src);
|
||||
|
||||
// Deserialize directly using a template
|
||||
List<String> dst1 = msgpack.read(raw, tList(TString));
|
||||
|
||||
// Or, Deserialze to Value then convert type.
|
||||
Value dynamic = msgpack.read(raw);
|
||||
List<String> dst2 = new Converter(dynamic).read(tList(TString));
|
||||
|
||||
} catch (Exception ex) {
|
||||
logger.error("MessagePack Serialization And Deserialization error", ex);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
@@ -0,0 +1,222 @@
|
||||
# Protocol Buffers 文档
|
||||
|
||||
Protocol Buffers 相关文档的内容。
|
||||
|
||||
|
||||
|
||||
## Protocol Buffers 简介
|
||||
如果你在互联网上搜索的话，你可能会看到下面的说明文字。
|
||||
|
||||
Google Protocol Buffer( 简称 Protobuf) 是 Google 公司内部的混合语言数据标准，目前已经正在使用的有超过 48,162 种报文格式定义和超过 12,183 个 .proto 文件。
|
||||
|
||||
他们用于 RPC 系统和持续数据存储系统。
|
||||
|
||||
Protocol Buffers 是一种轻便高效的结构化数据存储格式，可以用于结构化数据串行化，或者说序列化。
|
||||
|
||||
它很适合做数据存储或 RPC 数据交换格式。可用于通讯协议、数据存储等领域的语言无关、平台无关、可扩展的序列化结构数据格式。
|
||||
|
||||
目前提供了 C++、Java、Python 三种语言的 API。
|
||||
|
||||
|
||||
我们是在实际的数据处理的时候，需要使用 JSON 来序列化数据，但是又考虑到 JSON 在传输的时候数据过大，同时还有很多并不需要的垃圾文件。
|
||||
我们才考虑到了 Protocol Buffer 提供的功能。
|
||||
|
||||
|
||||
|
||||
|
||||
# Protocol Buffers 开发者指南
|
||||
|
||||
欢迎来到 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; 的代码。
|
||||
|
||||
```cpp
|
||||
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);
|
||||
```
|
||||
|
||||
随后，你可以对消息进行读取：
|
||||
|
||||
```cpp
|
||||
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 你需要使用：
|
||||
|
||||
```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 进行操作也是非常容易的：
|
||||
|
||||
```cpp
|
||||
cout << "Name: " << person.name() << endl;
|
||||
cout << "E-mail: " << person.email() << endl;
|
||||
```
|
||||
|
||||
如果使用的是 XML 的话，你需要进行下面的操作：
|
||||
|
||||
```cpp
|
||||
cout << "Name: "
|
||||
<< person.getElementsByTagName("name")->item(0)->innerText()
|
||||
<< endl;
|
||||
cout << "E-mail: "
|
||||
<< person.getElementsByTagName("email")->item(0)->innerText()
|
||||
<< endl;
|
||||
```
|
||||
|
||||
但是，protocol buffers 并不是任何时候都会比 XML 好。例如，针对基于文本的标记语言（例如，XML），protocol buffers 就不是一个很好的选项，
|
||||
因为你不能使用 protocol buffer 更好的在文档中进行交换。更主要的是 HTML 是人类可以阅读和编辑的。protocol buffer 也不是不可以人为的读取，但是针对原生的 protocol buffer 格式是没有办法人为进行读取和编辑的。
|
||||
|
||||
XML 与 HTML 一样，在某种程度上是一种自我描述数据。protocol buffer 只针对你在 .proto 文件中描述的内容进行表达。
|
||||
|
||||
## 看起来像一个解决方案，我应该如何开始呢
|
||||
Download the package – 这包中含有针对 Java, Python, 和 C++ protocol buffer 编译器源代码，和你需要进行 I/O 和测试的类。希望对你的编译器进行编译和构建，请参考代码中的 README 文件。
|
||||
|
||||
一旦你完成了所有的设置，请参考 tutorial 页面中的内容来选择你需要的语言——这个能够帮助你使用 protocol buffer 创建一个简单的应用程序。
|
||||
|
||||
## 介绍 proto3
|
||||
在我们最新的 version 3 发行版 中推出了新的语言版本 —— Protocol Buffers language version 3（另称 proto3），在这个版本中针对我们已经存在的语言版本（proto2）使用了一些新的特性。
|
||||
|
||||
Proto3 简化了 protocol buffer 语言，使其更加容易使用并且能够支持更多的语言：我们当前发行的 proto3 能够让你创建 Java, C++, Python, Java Lite, Ruby, JavaScript, Objective-C, and C#。
|
||||
|
||||
另外你也可以通过使用 Go protoc 插件来用 proto3 创建 Go 代码，这个插件你可以到 golang/protobuf Github 中下载到。更多的语言还在逐步进行支持中。
|
||||
|
||||
请注意，这 2 个版本的 API 并不是完全兼容的。为了照顾还在使用老版本的用户，我们将会在新的 protocol buffers 发行中同时支持老的版本。
|
||||
|
||||
你可以在下面的发行日志（release notes）查看 2 个版本的主要不同。有关 proto3 的句法，请参考 Proto3 Language Guide 中的内容，针对 proto3 的完整文档还没有编写完成，将会随后推出。
|
||||
|
||||
看起来 proto2 和 proto3 可能会产生一些混淆，这是因为原始的开源 protocol buffers 实际上是 Google 内部语言的第二个版本，同时我们的开源版本也是从 v2.0.0 开始的。
|
||||
|
||||
简单来说就是 proto 最开始的版本是 Google 内部使用的，在 proto 第二个版本的时候，Google 决定进行开源了，所以开源的 proto 是从 proto2 开始的。
|
||||
|
||||
## 一个简短的历史
|
||||
Protocol buffers 最开始是在 Google 内部进行开发的，用于处理在索引服务器上请求/响应（request/response）的协议。
|
||||
|
||||
在 Protocol buffers 之前，针对请求和响应，使用的是 marshalling/unmarshalling，这个能够支持一系列的协议。但是结果看起来却是非常的难看，例如：
|
||||
|
||||
```
|
||||
if (version == 3) {
|
||||
...
|
||||
} else if (version > 4) {
|
||||
if (version == 5) {
|
||||
...
|
||||
}
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
明确格式化的的协议也使新版本的协议更加难以推出，这是因为开发者必须能够了解老协议在服务器之间是如何进行处理的，同时也需要了解新的协议。只有对新老协议都有所了解后才能逐步使用新的协议替换老的协议。
|
||||
|
||||
Protocol buffers 被用来设计解决上面的很多问题：
|
||||
|
||||
* 新的字段比较能够容易的进行定义，中级服务器不需要对数据进行检查，直接对数据进行处理，同时也可以直接传输数据而不需要了解数据是如何进行定义的。
|
||||
* 格式使用自描述，能够更加容易支持更多的语言（C++，Java 等）。
|
||||
|
||||
但是，用户还是需要手动书写他们自己的处理diam。
|
||||
|
||||
作为系统的进化来说，它获得了许多其他的特性和用途：
|
||||
|
||||
* 自动生成序列化和反序列化代码而避免手动书写这些代码。
|
||||
* 除了开始使用短期RPC（远程过程调用）请求，人们开始使用 protocol buffers 作为高效的自描述结构化数据格式（主要针对数据短期存在，例如在 Bigtable）。
|
||||
* 服务器RPC接口开始被声明为协议文件的一部分，协议编译器生成根类，用户可以通过服务器接口的实现和重载它们。
|
||||
|
||||
Protocol buffers 在 Google 中成为针对数据的通用语言—— 随着时间的流逝，在 Google 内部已经有超过 348,952 .proto 文件被定义。这些被用在 RPC 系统和存储系统中存储数据。
|
||||
|
||||
[Protocol Buffers 安装](installation.md ':include')
|
||||
@@ -0,0 +1,40 @@
|
||||
# Protocol Buffers 安装
|
||||
本文主要介绍 protobuf 编译器在 Windows 下的安装。
|
||||
|
||||
## 下载编译器
|
||||
访问 https://github.com/protocolbuffers/protobuf/releases/ 链接然后针对不同的操作系统下载最新的编译器版本。
|
||||
|
||||
|
||||
|
||||
下载完成后到本地计算机上找到这个文件并且解压。
|
||||
|
||||
## 解压文件
|
||||
然后将下载的压缩文件解压到 D:\Dkits\protobuf 文件夹中。
|
||||
|
||||
当然你也可以解压到不同的文件夹中。
|
||||
|
||||
|
||||
|
||||
解压后的文件夹目录如下。
|
||||
|
||||
## 设置 PATH
|
||||
当完成下面解压后，你可以将文件所在的 bin 目录中设置到 PATH 里面。
|
||||
|
||||
|
||||
|
||||
上面就是设置好的 PATH 目录。
|
||||
|
||||
然后保存退出。
|
||||
|
||||
## 校验安装
|
||||
在命令行工具中，运行命令：
|
||||
|
||||
`protoc --version`
|
||||
|
||||
如果能够看到版本输出的话，就说明你的 protoc 已经被正确的配置到操作系统中了。
|
||||
|
||||
|
||||
|
||||
如上图，我们能看到正确的版本输出。
|
||||
|
||||
延伸阅读和参与讨论，请访问：[Protobuf 编译器 Windows 安装方法](https://www.ossez.com/t/protobuf-windows/13864)
|
||||
Reference in New Issue
Block a user