中文 – 编码无悔 / Intent & Focused

[原创] JAVA sun HttpServer在handler中返回含中文的response应该怎么处理

learnhard — Thu, 23 Mar 2023 09:10:14 +0000

在JAVA中，使用sun HttpServer实现一个web server的时候，使用了下面的hander类来处理请求：

static class MyHandler implements HttpHandler {
  @Override
  public void handle(HttpExchange httpExchange) throws IOException {
    String response = "test";  // 返回固定内容
    httpExchange.sendResponseHeaders(200, response.length());
    OutputStream os = httpExchange.getResponseBody();
    os.write(response.getBytes());
    os.close();
  }
}

如果要在response里返回带中文的内容，例如：

String response = "中文";

那么你就会发现访问这个web server返回的是null，这说明handler实现有问题。那么代码应该怎么改？
文章来源：https://www.codelast.com/
如下：

static class MyHandler implements HttpHandler {
  @Override
  public void handle(HttpExchange httpExchange) throws IOException {
    String response = "中文";
    byte[] bytes = response.getBytes(StandardCharsets.UTF_8); // 转换为字节数组，指定编码为UTF-8
    httpExchange.sendResponseHeaders(200, bytes.length);
    OutputStream os = httpExchange.getResponseBody();
    os.write(bytes);
    os.close();
  }
}

此时你会发现，向server发请求返回的不再是null而是正确的内容了。

文章来源：https://www.codelast.com/
➤➤ 版权声明 ➤➤
转载需注明出处：codelast.com
感谢关注我的微信公众号（微信扫一扫）：

以及我的微信视频号：

[原创]《使用 fastText 做中文文本分类》文章合集

learnhard — Wed, 29 Jul 2020 10:46:59 +0000

本文描述了如何使用 fastText 对中文进行文本分类的过程，只有实操，基本没有理论。
以下按顺序编排。

✓ 使用 fastText 做中文文本分类(1)
✓ 使用 fastText 做中文文本分类(2)
✓ 使用 fastText 做中文文本分类(3)
✓ 使用 fastText 做中文文本分类(4)
✓ 使用 fastText 做中文文本分类(5)… Read More

[原创] 使用 fastText 做中文文本分类(5)

learnhard — Wed, 29 Jul 2020 09:48:07 +0000

查看本系列文章合集，请看这里。

前面说的模型训练、预测过程，是用 fastText 可执行程序完成的。fastText提供了Python的接口，同样的功能也可以用Python实现。如果数据量比较小，单机做文本分类没啥问题。但我的数据量比较大，几十G的文本数据，单机加载模型、预测分类太耗资源了，而且速度慢。
并行这种事嘛，交给Map-Reduce job来做是最合适不过了，不过，要在Hadoop集群上安装fastText的Python包是不可能的，所以我只能找一下，fastText的模型怎么用Java加载，从而在M-R job中并行地去做预测。

✓ 选择
网上能搜到好些个 fastText 的“Java版”，比如 JFastText，它是 fastText 的一个Java wrapper；又比如 FastText4j，它是一个完全由 Kotlin & Java 实现的 fastText 实现。还有其他的，没有调研。
看了 FastText4j 的自我介绍：

● 100%由Kotlin & Java实现

● 良好的API

● 兼容官方原版的预训练模型

● 提供所有的包括train、test等api

● 支持自有模型存储格式，可以使用MMAP快速加载大模型

我心动了，马上试用。

✓ Maven项目引入 FastText4j 依赖


  com.mayabot.mynlp
  fastText4j
  3.1.7

这样就能在代码里用了。
文章来源：https://www.codelast.com/
✓ 训练模型

// 用FastText4j训练一个文本分类模型，模型保存成单个文件
File trainFile = new File("/home/codelast/labeled-data_train");
InputArgs inputArgs = new InputArgs();
inputArgs.setLoss(LossName.softmax);
inputArgs.setLr(1.0);
inputArgs.setEpoch(25);
inputArgs.setWordNgrams(2);

FastText model = FastText.trainSupervised(trainFile, inputArgs);
model.saveModelToSingleFile(new File("/home/codelast/model"));

训练的参数，包括 lr，epoch，wordNgrams 的含义，都和 fastText 的原版一致。和 fastText 默认生成 .bin & .vec 两个模型文件不同，FastText4j 可以用 saveModelToSingleFile() 方法来生成一个单一的模型文件，如果用 saveModel() 方法的话，则会在一个目录下生成4个文件（如果是这种形式的话，加载模型的时候，4个文件缺一不可）：

args.bin

dict.bin

input.matrix

output.matrix

如果要在Java Map-Reduce job中加载模型，把模型放到 distributed cache 中分发，当然是一个文件最方便。所以强烈建议把模型save成单一文件。
文章来源：https://www.codelast.com/
✓ 加载模型并测试效果

// 加载模型
FastText model = FastText.Companion.loadModelFromSingleFile(new File("/home/codelast/model"));
System.out.println("load model done, will do test...");
// 测试模型效果
model.test(new File("/home/codelast/labeled-data_valid"), 1, 0, true);

输出：

load model done, will do test...

F1-Score : 0.953652 Precision : 0.949348 Recall : 0.957996 __label__娱乐

F1-Score : 0.704064 Precision : 0.702055 Recall : 0.706085 __label__社会

F1-Score : 0.929426 Precision : 0.917355 Recall : 0.941818 __label__历史

F1-Score : 0.784775 Precision : 0.784232 Recall : 0.785319 __label__时政

F1-Score : 0.969314 Precision : 0.967568 Recall : 0.971067 __label__汽车

F1-Score : 0.910314 Precision : 0.914414 Recall : 0.906250 __label__时尚

F1-Score : 0.899281 Precision : 0.903614 Recall : 0.894988 __label__健康

F1-Score : 0.929919 Precision : 0.905512 Recall : 0.955679 __label__美食

F1-Score : 0.908136 Precision : 0.894057 Recall : 0.922667 __label__军事

F1-Score : 0.967391 Precision : 0.975342 Recall : 0.959569 __label__体育

F1-Score : 0.907618 Precision : 0.915033 Recall : 0.900322 __label__育儿

F1-Score : 0.782895 Precision : 0.760383 Recall : 0.806780 __label__情感

F1-Score : 0.863946 Precision : 0.866894 Recall : 0.861017 __label__财经

F1-Score : 0.905188 Precision : 0.920000 Recall : 0.890845 __label__教育

F1-Score : 0.781431 Precision : 0.792157 Recall : 0.770992 __label__文化

F1-Score : 0.892495 Precision : 0.894309 Recall : 0.890688 __label__游戏

F1-Score : 0.830882 Precision : 0.801418 Recall : 0.862595 __label__科技

F1-Score : 0.795455 Precision : 0.781250 Recall : 0.810185 __label__旅游

F1-Score : 0.843537 Precision : 0.826667 Recall : 0.861111 __label__动漫

F1-Score : 0.960961 Precision : 0.969697 Recall : 0.952381 __label__占卜

F1-Score : 0.915361 Precision : 0.912500 Recall : 0.918239 __label__数码

F1-Score : 0.553191 Precision : 0.601852 Recall : 0.511811 __label__搞笑

F1-Score : 0.788104 Precision : 0.834646 Recall : 0.746479 __label__农林牧副渔

F1-Score : 0.797048 Precision : 0.830769 Recall : 0.765957 __label__科学

F1-Score : 0.788462 Precision : 0.828283 Recall : 0.752294 __label__家居

F1-Score : 0.831579 Precision : 0.877778 Recall : 0.790000 __label__房产

F1-Score : 0.674286 Precision : 0.710843 Recall : 0.641304 __label__生活方式

F1-Score : 0.908108 Precision : 0.933333 Recall : 0.884211 __label__宠物

F1-Score : 0.546667 Precision : 0.546667 Recall : 0.546667 __label__宗教

F1-Score : 0.706767 Precision : 0.671429 Recall : 0.746032 __label__职场

F1-Score : 0.951220 Precision : 0.928571 Recall : 0.975000 __label__天气

F1-Score : 0.666667 Precision : 0.909091 Recall : 0.526316 __label__摄影

F1-Score : 0.707692 Precision : 0.718750 Recall : 0.696970 __label__法律

F1-Score : 0.750000 Precision : 1.000000 Recall : 0.600000 __label__彩票

F1-Score : 0.333333 Precision : 1.000000 Recall : 0.200000 __label__移民

F1-Score : 0.000000 Precision : -------- Recall : 0.000000 __label__生活百科

N 10703

P@1 0.870

R@1 0.870

文章来源：https://www.codelast.com/
✓ 预测一段文本的label

// 预测一个分好词的string的label
List result = model.predict(Arrays.asList("人民网 辽宁 频道 人民网 沈阳 月 10 日电 日前 进一步 增强 全民 节能 意识".split(" ")), 1, 0);
System.out.println(result.get(0).getLabel());

输出：

__label__社会

注意这里的文本应该是分好词的、空格分隔的、清洗过的文本。
文章来源：https://www.codelast.com/
✓ 压缩模型
如果一个模型文件体积太大，可能放不进 distributed cache 中，所以压缩模型体积这个功能很有用。以我的模型为例，接近900MB的大小，压缩之后会变成 100 多MB，模型的Precision & Recall指标却没有变差多少，值。

// 压缩模型并保存。加载压缩过的模型可以节省内存
FastText qmodel = model.quantize(2, false, false);
qmodel.saveModelToSingleFile(new File("/home/codelast/model_compressed"));

保存成压缩过的模型是一次性的操作，以后再加载模型的话，就加载这个压缩过的模型了。

✓ 后记
通过 FastText4j 在 Map-Reduce job 中并行做文本分类，成功地让文本分类任务提高了无数倍的速度，达到了实用的水平。

文章来源：https://www.codelast.com/
➤➤ 版权声明 ➤➤
转载需注明出处：codelast.com
感谢关注我的微信公众号（微信扫一扫）：

[原创] 使用 fastText 做中文文本分类(4)

learnhard — Wed, 29 Jul 2020 09:47:42 +0000

查看本系列文章合集，请看这里。

✓ 开始训练第一个文本分类模型
标注好的数据，其格式为：

__label__科技月 10 日网通社从高合汽车获悉华人运通微软 2020 世界人工智能大会云端峰会 WAIC 2020 上达成战略合作依托微软小冰人工智能技术高合汽车上落地全球首个主动式人工智能伙伴 HiPhiGo 用户提供更好交通出行体验人工智能交通行业创新融合发展探讨成立联合智能计算实验室智能汽车载体智捷交通多个领域展开深度合作人工智能前瞻技术研发推动智慧出行社会持续发展微软亚洲互联网工程院院长王永东微软华人运通合作使人工智能技术切实可行落地场景得以转化真实有效生产力发挥更大价值微软华人运通携手推进人工智能新兴科技汽车智慧智慧出行领域广泛应用产业升级社会持续发展注入新活力华人运通董事长丁磊此次合作顶级人工智能企业智能汽车公司强强联手 AI 多项领先技术全球汽车行业首次量产落地世界内技术领先性首款智能汽车高合 HiPhi 有条不紊推进全球首条车路协同自动驾驶智能化城市道路示范项目盐城开通试运行再全球首个车路城一体化 5G 无人驾驶交通运营样板上海张江未来公园成功落地华人运通以人为本人性化需求出发人性化智慧打造智能汽车智捷交通智慧城市三智战略各项业务稳步推进高合首款量产车 HiPhi 2020 年底小批量试生产 2021 年上市交付

按 fastText 的指南，把这份数据按大概 9:1 的比例，分成training集和validation集，然后开始训练模型：

./fasttext supervised -input labeled-data_train -output model

其中，labeled-data_train 是training集文件，model 是输出模型的文件名前缀。
经过一段时间的等待（速度很快），当前目录下就生成了模型文件：model.bin 和 model.vec。

现在可以用validation集来检验一下模型效果了：

./fasttext test model.bin labeled-data_valid 1

其中，labeled-data_valid 是validation集文件，1表示只预测top 1的label。
输出：

N 10705

P@1 0.842

R@1 0.842

即 Precision为0.842，Recall为0.842。这个结果还可以，但还能优化。
文章来源：https://www.codelast.com/
✓ 模型调优
设置更详细的参数重新训练模型：

./fasttext supervised -input labeled-data_train -output model -lr 1.0 -epoch 25 -wordNgrams 2

其中：
-lr 1.0 表示 learning rate 设置成 1.0（通常值：0.1 ～ 1.0）。
-epoch 25 表示迭代的轮数设置成 25。
-wordNgrams 2 表示n-gram的值，一般使用2，表示2-gram。
这样训练出来的模型，再做一次test，结果变好了一些：

N 10705

P@1 0.878

R@1 0.878

这里只对模型优化做了简单的尝试。

✓ 交互模式下预测文本的分类
执行以下命令：

./fasttext predict model.bin -

fastText会加载 model.bin 模型，进入交互模式，等待用户输入。
此时输入的应该是分好词之后的文本，例如“网通社从高合汽车获悉华人运通微软 2020 世界人工智能大会云端峰会 WAIC 2020 上达成战略合作”。一回车，fastText马上会返回该段文本的预测分类：

__label__科技

这是个比较方便的调试方法。

文章来源：https://www.codelast.com/
➤➤ 版权声明 ➤➤
转载需注明出处：codelast.com
感谢关注我的微信公众号（微信扫一扫）：

[原创] 使用 fastText 做中文文本分类(3)

learnhard — Wed, 29 Jul 2020 09:47:20 +0000

查看本系列文章合集，请看这里。

为 training 数据做标注，这可能是一个艰巨的任务，也可能是一个有捷径的任务。
有时候，我们可以依据一些已知的规则来标注文本，比如不同的数据是从不同的来源获取到的，从来源可以知道它们所属的类别，这是一个捷径。不过我这里不具备这样的条件。
我的数据来源是网上的各种新闻，不是某些专业领域的数据，这种比较常见的文本分类任务，可以利用国内的几大云服务商提供的免费接口来完成。阿里云、腾讯云都有这样的接口。
以腾讯云为例，其“人工智能→自然语言处理”产品提供了文本分类功能：

文本分类接口能够对用户输入的文本进行自动分类，将其映射到具体的类目上，用户只需要提供待分类的文本，而无需关注具体实现。

该功能基于千亿级大规模互联网语料和LSTM、BERT等深度神经网络模型进行训练，并持续迭代更新，以保证效果不断提升。

目前已提供：

● 通用领域分类体系，包括15个分类类目，分别是汽车、科技、健康、体育、旅行、教育、职业、文化、军事、房产、娱乐、女性、奥运、财经以及其他，适用于通用的场景。

● 新闻领域分类体系，包括37个一级分类类目，285个二级分类（详细请见类目体系映射表），已应用于腾讯新闻的文章分类。

更多垂直领域的分类体系即将推出，敬请期待。

默认接口请求频率限制：20次/秒。

该API每天有50万次免费调用额度，用来标注数据够用了：

如果你对这个接口的分类结果准确性有疑虑的话，可以亲自拿一些新闻的文本试一试，就会发现它的效果真的不错，完全可以用来当作人工标注的结果了，毕竟是大厂出品嘛。

同理，阿里云也有类似的接口。作为电商界的龙头，阿里云的文本分类接口不仅适用于新闻资讯领域类目体系，还能用于电商领域类目体系。所以，如果你的文本是电商领域的，可以试试阿里云。
文章来源：https://www.codelast.com/
下面，就来看看怎么薅腾讯云的羊毛。注册腾讯云账号、开通自然语言处理接口的权限，这些就不用说了，自己在网页上点几下就可以完成。
✓ 测试接口
腾讯云NLP接口提供了一个在线测试的网页，从这个链接可以进去（“点击调试”）：

进入调试页面：

对这个接口：
Region只能选“华南地区(广州)”。
Text是待分类的文本，注意不需要分词。只需要把我们前面清洗过（去掉了HTML tag等内容）的句子拿来用即可。
Flag为 1 表示通用领域，为 2 表示新闻领域。
文章来源：https://www.codelast.com/
接口返回的数据是JSON格式，FirstClassName 是一级分类的名称，SecondClassName 是二级分类的名称。
调试页面还提供了“代码生成”功能，Java、Python、PHP、Go等都有，支持非常全面。选一个你熟悉的语言，就可以在代码里实现了。

由于免费的接口的QPS上限为20次/秒，所以并行什么的就不要想了，单线程就能跑满。
通过腾讯云的接口，我们能在半天内为几十万条文本打上标签，再整理成 fastText 规定的格式，就可以训练模型了。
如果觉得50万条都不够多，可以注册多个腾讯云账号来薅羊毛，或者用几天的时间累积够标注数据。

文章来源：https://www.codelast.com/
➤➤ 版权声明 ➤➤
转载需注明出处：codelast.com
感谢关注我的微信公众号（微信扫一扫）：

[原创] 使用 fastText 做中文文本分类(2)

learnhard — Wed, 29 Jul 2020 09:46:54 +0000

查看本系列文章合集，请看这里。

做好文本预处理，才能输入fastText训练一个效果好的模型出来。

✓ 原文示例
有时我们拿到的源数据是很粗糙的，带有很多会影响模型效果的内容，例如下面这样：

罗望子，是豆科酸豆属唯一的种，是热带乔木，原产于东部非洲，包括马达加斯加落叶森林，但已被引入热带亚洲、拉丁美洲和加勒比海。柽柳是中国海南省三亚的一种城市树木。罗望子最适合生长在温度高、日照长、气候干燥、干湿季节分明的地区。

罗望子富含糖、乙酸、酒石酸、甲酸、柠檬酸等成分，主要用于调味品、饮料、果酱等食品领域。吃一点罗望子有很多好处。当我们吃罗望子时，罗望子中含有的多糖是一种非常好的抗光物质。当我们吃这种物质时，它可以防止紫外线辐射伤害皮肤。通常吃一点罗望子，饭前吃一点罗望子可以增进食欲，改善我们的饮食质量。在炎热的夏日，吃一点罗望子可以生津止渴，清热解毒，降低中暑的风险。

罗望子种子含有丰富的抗氧化物质。多吃罗望子籽可以延缓人体衰老，保持皮肤湿润有光泽。罗望子种子还含有一些清热解毒、消炎的物质，可以帮助我们的人体抵抗一些有害细菌，保护我们的健康。

这里面不仅带有URL、大量的HTML标签，而且还有标点符号等，这些都要清洗掉。

✓ 清除掉HTML标签、URL
这里给出Java版的一个实现(从网上借鉴来的)，它们并不完善，但是够用了：

    /**
     * 移除一个字符串中的HTML标签。
     *
     * @param inputStr 输入的字符串。
     * @return 移除了HTML标签之后的字符串。
     */
    private String removeHtmlTags(String inputStr) {
      if (StringUtils.isEmpty(inputStr)) {
        return inputStr;
      }
      return inputStr.replaceAll("<[^>]*>", "");
    }

    /**
     * 移除一个字符串中的URL。
     *
     * @param inputStr 输入的字符串。
     * @return 移除了URL之后的字符串。
     */
    private String removeUrl(String inputStr) {
      String urlPattern = "((https?|ftp|gopher|telnet|file|Unsure|http):((//)|(\\\$$)+[\\w\\d:#@%/;$()~_?+-=\\\\.&]*)";
      Pattern p = Pattern.compile(urlPattern, Pattern.CASE_INSENSITIVE);
      Matcher m = p.matcher(inputStr);
      StringBuffer sb = new StringBuffer(inputStr.length());
      while (m.find()) {
        m.appendReplacement(sb, "");
      }
      return sb.length() == 0 ? inputStr : sb.toString();
    }

文章来源：https://www.codelast.com/
以前面的内容为例，依次经过上面两个方法处理后，得到的结果是：

罗望子，是豆科酸豆属唯一的种，是热带乔木，原产于东部非洲，包括马达加斯加落叶森林，但已被引入热带亚洲、拉丁美洲和加勒比海。柽柳是中国海南省三亚的一种城市树木。罗望子最适合生长在温度高、日照长、气候干燥、干湿季节分明的地区。罗望子富含糖、乙酸、酒石酸、甲酸、柠檬酸等成分，主要用于调味品、饮料、果酱等食品领域。吃一点罗望子有很多好处。当我们吃罗望子时，罗望子中含有的多糖是一种非常好的抗光物质。当我们吃这种物质时，它可以防止紫外线辐射伤害皮肤。通常吃一点罗望子，饭前吃一点罗望子可以增进食欲，改善我们的饮食质量。在炎热的夏日，吃一点罗望子可以生津止渴，清热解毒，降低中暑的风险。罗望子种子含有丰富的抗氧化物质。多吃罗望子籽可以延缓人体衰老，保持皮肤湿润有光泽。罗望子种子还含有一些清热解毒、消炎的物质，可以帮助我们的人体抵抗一些有害细菌，保护我们的健康。

这样看上去就干净多了。
文章来源：https://www.codelast.com/
除此之外，还有标点符号，以及一些无用的词需要被除掉，这些词对表达文本的主要含义作用不大，比如“啊”，“嘿”之类的词，它们一般称为停用词(stop words)。我们可以从网上下载到常用的停用词表，比如这个链接。
在对文本进行分词之后，出现在停用词表中的，全都过滤掉。

✓ 分词并去除停用词
Python下比较流行的中文分词器之一是结巴分词：

import jieba


my_text = '罗望子，是豆科酸豆属唯一的种，...'



# 分词
segmented_words = jieba.cut(my_text, cut_all=False)  # 精确分词模式



# 去除停用词

for single_word in segmented_words:
    #TODO: 去除停用词

文章来源：https://www.codelast.com/
Java版的结巴分词作者已经不维护了，建议换其他的分词器，比如用户量很大的HanLP。其使用也非常简单，在Maven项目的 pom.xml 中添加：

    <dependency>
      <groupId>com.hankcsgroupId>
      <artifactId>hanlpartifactId>
      <version>portable-1.7.8version>
    dependency>

就可以用了：

import com.hankcs.hanlp.seg.common.Term;
import com.hankcs.hanlp.tokenizer.StandardTokenizer;

String myText = "罗望子，是豆科酸豆属唯一的种，...";

List termList = StandardTokenizer.segment(myText);
for (Term term : termList) {
    System.out.println(term.word);  // term.word即分出来的每个词
    //TODO: 去除停用词
}

现在得到的是分好的词，并且把停用词等杂七杂八的东西都去掉了，也许对某些情况很糟糕的文本，还会有漏网之鱼，但对一般情况来说基本上够用了。
不同的分词器分出来的词结果不尽相同，这里以Java版为例，得到：

罗望子豆科酸豆属唯一种热带乔木原产东部非洲包括马达加斯加落叶森林已引入热带亚洲拉丁美洲加勒比海柽柳是中国海南省三亚种城市树木罗望子最适合生长温度高日照长气候干燥干湿季节分明地区罗望子富含糖乙酸酒石酸甲酸柠檬酸成分用于调味品饮料果酱食品领域吃一点罗望子很多好处吃罗望子时罗望子中含有多糖种好抗光物质吃物质时紫外线辐射伤害皮肤吃一点罗望子饭前吃一点罗望子增进食欲改善饮食质量炎热夏日吃一点罗望子生津止渴清热解毒降低中暑风险罗望子种子含有抗氧化物质吃罗望子籽延缓人体衰老皮肤湿润光泽罗望子种子还含有清热解毒消炎物质人体抵抗有害细菌保护健康

为了清晰展示结果，词与词之间用空格隔开了。
如果对分词结果不满意，比如人名，特殊物品名，可以为分词器添加字典，让分词器识别它们。这些调优的工作就不详述了。
文章来源：https://www.codelast.com/
✓ 文本标注
fastText对训练数据的格式要求是这样的：

__label__健康罗望子豆科酸豆属唯一种热带乔木原产东部非洲包括马达加斯加落叶森林已引入热带亚洲拉丁美洲加勒比海柽柳是中国海南省三亚种城市树木罗望子最适合生长温度高日照长气候干燥干湿季节分明地区罗望子富含糖乙酸酒石酸甲酸柠檬酸成分用于调味品饮料果酱食品领域吃一点罗望子很多好处吃罗望子时罗望子中含有多糖种好抗光物质吃物质时紫外线辐射伤害皮肤吃一点罗望子饭前吃一点罗望子增进食欲改善饮食质量炎热夏日吃一点罗望子生津止渴清热解毒降低中暑风险罗望子种子含有抗氧化物质吃罗望子籽延缓人体衰老皮肤湿润光泽罗望子种子还含有清热解毒消炎物质人体抵抗有害细菌保护健康

每两个字符串之间都用空格隔开，以“__label__”开头的（前后均为双下划线）是后面文本的标签，这里可以有多个标签，比如“__label__健康 __label__生活”，也是用空格分隔开。前面说过，本文以1个标签举例，所以这里只有1个。
这是文本预处理的最后一步，完成之后就可以把数据喂给fastText训练出一个模型啦。
比如说上面分好词的文本，我们要为它标注一个类别（例如“健康”）。
然鹅，我们难道用人工肉眼看的方法来标注吗？并且，类别有哪些，我怎么知道？
就算有一目十行的能力，看瞎我的钛合金狗眼，我一天也标不了10万条数据啊！
欲知解决方法，请看下一篇文章。

文章来源：https://www.codelast.com/
➤➤ 版权声明 ➤➤
转载需注明出处：codelast.com
感谢关注我的微信公众号（微信扫一扫）：

[原创] 使用 fastText 做中文文本分类(1)

learnhard — Wed, 29 Jul 2020 09:46:10 +0000

查看本系列文章合集，请看这里。

✓ 什么是“文本分类”

它是图书馆学，信息学和计算机科学中的一个问题。其任务是将一个文档分配到一个或者多个类别中。

举例：

文本	类别
瑞幸咖啡今日发布声明称，瑞幸咖啡公司将于6月29日在纳斯达克停牌，并进行退市备案。声明表示，在国内消费市场方面，瑞幸咖啡全国4000多家门店将正常运营，近3万名员工仍将一如既往的为用户提供优质产品和服务。公司衷心感谢广大消费者的支持厚爱，并再次为事件造成的恶劣影响向社会各界诚挚道歉。	财经
明朝中后期西南沿海一个重要的问题就是倭寇的骚扰，这个问题本来是有希望被当时的浙江总督用和平的方法解决掉的，但是中途就出了个王本固这个插曲。	历史

其中，“类别”是事先定义好的。一段文本可以属于多个类别，例如，第2个例子可以同时属于“历史”和“明朝”这两个类别。

✓ fastText是什么
fastText是Facebook于2016年开源的一个词向量计算和文本分类工具，官方定义：

Library for efficient text classification and representation learning

工具如其名，“fast”，表明它的速度很快。
fastText应用很广泛，本文以只有1个类别的中文文本分类任务为例，展示如何从源数据开始，到数据处理，到最后完成分类的过程。
文章来源：https://www.codelast.com/
✓ 安装fastText
fastText 有一个在命令行直接就能用的可执行程序，也有Python的接口，这两样东西我们都装上。
安装、使用fastText对编译器版本、Python版本都有一定的要求，可以查看fastText网站了解这些信息。

wget https://github.com/facebookresearch/fastText/archive/v0.9.2.zip
unzip v0.9.2.zip
cd fastText-0.9.2
make
pip install .

本文写作时，fastText的最新版是 0.9.2，如果版本有更新，上面的命令要跟着修改。
我们会看到当前目录下生成了一个名为“fasttext”的可执行程序。这样，fastText就可以开始用了。但这只是万里长征第一步，之后的文本预处理、类别标注才是最麻烦的。

✓ 文本分类的流程
并不是我们有了文本数据（一行一个字符串），就能直接喂给fastText训练出来一个分类模型了，我们不仅要对数据进行一些细致的清洗，还要把输入fastText的数据做成它要求的格式，这样它才能识别并训练出模型。

简单地说，文本分类的过程主要由以下步骤构成：
● 对待分类的文本数据做预处理。例如：去掉文本里的乱七八糟的字符、标点符号，等等。并且，由于中文不像英文有天然的空格做为词与词之间的分隔符，因此，我们只能使用分词器来对中文句子进行分词。
● 对文本进行标注。fastText训练的是有监督的文本分类模型，你得先给它一堆例子：什么样的文本，对应的正确分类是什么。这样它才能学出一个模型，用于预测一个没有见过的文本的类别。标注可以由人工完成（效率低，一般不现实），也可以从一些可信的数据源获取文本的正确分类。
● 把处理好的文本数据拆分成training集和validation集，training集用于训练模型，validation集用于检验模型效果。
● 用fastText训练training集得到一个模型，用validation集检验模型效果，如果效果不好，调整模型训练的参数训练一个新模型继续检验效果。

下面，就依次描述以上各项。请看下一篇文章。

文章来源：https://www.codelast.com/
➤➤ 版权声明 ➤➤
转载需注明出处：codelast.com
感谢关注我的微信公众号（微信扫一扫）：

[原创] gnuplot调教记

learnhard — Fri, 24 Oct 2014 09:48:59 +0000

gnuplot是命令行绘图的极佳选择之一。用它画出一副简单的图极其容易，但是对画出的图进行微调却很令人抓狂，这主要“得益”于gnuplot超级强大的功能，以及无穷无尽纷繁复杂的说明文档，通常让人没时间去细细研究。
如果你经常有gnuplot的使用需求，那么可以仔细研读一下它的文档，否则，还是像我一样，现学现用吧。
我折腾了一天多时间，把我想要的一副图给画出来了，里面涉及到了很多图像的微调过程，有些解决方案很难搜到，但我运气稍好，终究还是弄出来了，在此，作为一个使用案例来分析一下。因此，本文并不是gnuplot的使用教程，而是用gnuplot绘图时，对某些奇怪问题的解决办法的分享。

本文基于gnuplot版本：4.4，系统：RHEL 5.3

『1』基本需求
先说一下我要画图的基本需求。听上去很简单：就是二维平面上的X，Y坐标点线图。我有一个数据文件data.txt，第一列是日期，第二列是该日期下的数值，例如：

20141020	1525
20141019	1429
20141018	1321
20141017	1780
20141016	1655

下面来看看怎么把它画成图。

『2』编写最简单的shell脚本
在shell脚本中调用gnuplot，绘制出一个最简单的图：

#!/bin/bash

gnuplot << EOF
  set terminal png
  set xdata time
  set timefmt "%Y%m%d"
  set output "output.png"
  plot "data.txt" using 1:2
    quit
EOF

画出的图是这样的：

文章来源：http://www.codelast.com/
显然这个图非常难看，并且图上的某些内容让人匪夷所思，我们先不管它，先看看它是怎么运作的。
在shell脚本中两个 EOF 中间的是gnuplot的绘图参数设置命令，每一条命令的含义分别是：
set terminal png：将输出图片设置为png格式。
set xdata time：设置X轴为时间。
set timefmt "%Y%m%d"：设置输入数据的时间格式。
set output "output.png"：设置输出图片的文件名，这里你可以使用绝对路径，此处为了简单，只使用相对路径，将输出到当前目录下。
plot "data.txt" using 1:2：将 data.txt 作为输入数据文件，使用其第一列作为X轴，第2列作为Y轴。
文章来源：http://www.codelast.com/
可见要画出一幅图是相当简单的，但是正如前面所说，要调整这幅图到你满意的程度，并不是一件简单的事情——如果不调整，上面的乱糟糟图根本就没法看嘛！

『3』漫长的参数调整过程
（1）去掉右上角的文字说明
右上角有一个 "data.txt" using 1:2 的说明，要去掉它，需要添加一句：

set nokey

画出的图变成了：

文章来源：http://www.codelast.com/
现在干净一点了。

（2）更改X轴的日期显示格式
将X轴的日期改为“月-日”（例如“10-16”），加一句代码即可：

set format x "%m-%d"

画出的图变成了：

文章来源：http://www.codelast.com/
X轴日期显示格式已改，没有悬念。有人说，但是它怎么有重复的日期啊？这个问题后面再说。

（3）清除Y轴显示的数值
添加代码：

set format y ""

画出的图变成了：

文章来源：http://www.codelast.com/
现在Y轴没数字了。

（4）添加网格
图中的任意两个点，它们的Y坐标值是否相同？如果这两个点离得稍微远一点，就看不清楚了，因此，为图像添加上网格，可以很好地辅助我们识别它们是否在同一水平线上：

set grid

画出的图变成了：

文章来源：http://www.codelast.com/
（5）去除X轴上重复的日期
添加如下代码：

set xtics 60*60*24

画出的图变成了：

文章来源：http://www.codelast.com/
这句代码为什么能“神奇”地修复X轴坐标重复的问题？如果你有耐心，可以看看这篇文章的解释。它的大概原理是：当X轴显示的值是时间的时候，xtics 的增量单位是秒，如果你要它的增量单位是天，就需要将 xtics 设置为一天的秒数，即60*60*24。

（6）设置输入的数据文件的分隔符
前面我们输入的数据文件data.txt以\t为两列的数据分隔符，但如果我有自定义的分隔符，是否要先把它转成\t，然后才能给gnuplot使用呢？不需要，只要用命令指定分隔符就可以了：

set datafile separator "\t"

（7）点与点之间连线
上面的图，画出的点实在太小了，如果相邻两点之间能用直线相连，看起来就清楚得多了：

plot "data.txt" using 1:2 with linespoints

画出的图变成了：

文章来源：http://www.codelast.com/
这是怎么做到的呢？plot 命令中的 with linespoints 指定了画出的图是点线图。

（8）修改一下线的颜色，线的粗细，点的大小
代码：

plot "data.txt" using 1:2 with linespoints linecolor 3 linewidth 1 pointtype 5 pointsize 1

画出的图变成了：

文章来源：http://www.codelast.com/
这下就好看多了，在上面的代码中，linecolor指定了线的颜色，linewidth指定了线的宽度，pointtype指定了点的类型，pointsize指定了点的大小，可以参考gnuplot的官方文档获知诸如pointtype之类的代号分别代表什么样的点/线。

（9）在点的旁边显示其纵坐标值
前面我们已经把Y轴刻度去掉了，因此有必要在点的旁边显示其纵坐标值：

plot "data.txt" using 1:2 with linespoints linecolor 3 linewidth 1 pointtype 5 pointsize 1, "" using 1:2:2 with labels

画出的图变成了：

文章来源：http://www.codelast.com/
这一步的代码，比之前的代码多了 "" using 1:2:2 with labels 这部分。其中，with labels 表示在点旁边画上标签（label），但是这个label的值是什么呢？这里使用 using 1:2:2 表示第一列为X坐标值，第二列为Y坐标值，同时第二列也作为label的值。如果数据文件data.txt中有第三列，你可以用 using 1:2:3 来使用第三列作为label的值。有人说，上面还有一个空的双引号，是作什么用的呢？Sorry，这个真不记得了...

（10）不要让label和数据点交错在一起
上面的数据点被label的数值盖住了，看起来很不爽，我们把数值偏移一定的位置，让它们错开：

plot "data.txt" using 1:2 with linespoints linecolor 3 linewidth 1 pointtype 5 pointsize 1, "" using 1:2:2 with labels center offset 0,0.5

文章来源：http://www.codelast.com/
这下漂亮多了！起这个作用的代码是 center offset 0,0.5。其中，center 加不加我没发现有什么区别；offset 0,0.5 表示把label在X轴方向平称0，在Y轴方向平移0.5。注意，平移的单位既不是像素，也不是和Y轴一样的单位，而是“相对距离”，不信我们可以把 offset 0,0.5 改成 offset -1,1，会看到label向左、向上都平移了一个单位，也就是下面这个样子：

文章来源：http://www.codelast.com/
可见label平移的距离远不止一个像素点，并且向上平移的距离也不是Y轴的“1”。
这个把label和数据点错开的方法，代码极其简单，但是为了找到这个solution，我搜遍了网页，试了无数种方法，其他的都有各种各样的显示问题，就是这样写才最好，找得我要吐血。

（11）为X轴添加上说明文字
添加代码：

set xlabel "Date" textcolor lt 1

画出的图变成了：

文章来源：http://www.codelast.com/
其中，textcolor lt 1 指定了文字的颜色。

（12）把X轴的说明文字改成中文
简单地把上面的“Date”改为中文的“日期”，看看画出的图会变成什么：

文章来源：http://www.codelast.com/
不出所料，中文乱码了。
解决这个问题没有那么容易，虽然解决方案有千千万，不过我认为最实用的方法就是：在系统中安装支持中文的字体，并且在使用gnuplot绘图时指定使用这个字体：

set term png font "/usr/share/fonts/truetype/wqy/wqy-microhei.ttc,12"

这句话的前半部分含义与 set terminal png 相同，后半部分指定了使用的字体的路径以及文字的大小。wqy-microhei.ttc 即为文泉驿微米黑字体文件，可以从很多地方下载到，当然你也可以尝试使用其他的字体。字体文件不一定要放在 /usr/share/fonts/truetype/wqy/ 路径下，但是最好遵循Linux系统中其他字体的规则。
这样，画出的图就变成了：

文章来源：http://www.codelast.com/
（13）为图片添加标题（title）
在上面已经搞定中文输出的基础上，我们再添加中文的title就很容易了：

set title "每天售出的商品数量" textcolor lt 1

画出的图变成了：

文章来源：http://www.codelast.com/
（14）图片两边太挤了，空出一定的空隙
添加代码：

set offset graph 0.10, 0.10

画出的图变成了：

文章来源：http://www.codelast.com/
上面的代码使得我们最左、最右的两个点不会碰到坐标轴，看上去舒服多了。至于它的具体含义，我不记得了，总之可以通过调整offset的数值来观察效果。

『4』总结
经过上面的一系列调整，我们终于得到了一幅看上去比较顺眼的图片。最后把完整的代码贴上来：

#!/bin/bash

gnuplot << EOF
  set term png font "/usr/share/fonts/truetype/wqy/wqy-microhei.ttc,12"
  set nokey
  set xdata time
  set timefmt "%Y%m%d"
  set format x "%m-%d"
  set format y ""
  set offset graph 0.10, 0.10
  set xtics 60*60*24
  set grid
  set title "每天售出的商品数量" textcolor lt 1
  set xlabel "日期" textcolor lt 1
  set output "output.png"
  set datafile separator "\t"
  plot "data.txt" using 1:2 with linespoints linecolor 3 linewidth 1 pointtype 5 pointsize 1, "" using 1:2:2 with labels center offset 0,0.5
    quit
EOF

另附几个常见错误的解决办法：
（1）Could not find/open font when opening font "arial", using internal non-scalable font
没有设置字体的时候可能会出现这个错误，这时，你可以指定一个系统中已有的字体，或者安装一个新字体并指定使用它，就可以避免这个问题，例如，安装文泉驿正黑字体：

yum install wqy-zenhei-fonts.noarch

然后在绘图代码中：

set term png font "/usr/share/fonts/wqy-zenhei/wqy-zenhei.ttc" 10

表示使用 /usr/share/fonts/wqy-zenhei/wqy-zenhei.ttc 这个刚安装上的字体文件作为图像中的字体，并且字号为10。
文章来源：http://www.codelast.com/
（2）shell调用gnuplot时，shell的内置变量（$1，$2，…）与gnuplot的内置变量冲突的问题
在shell脚本中，$1，$2，… 表示传给shell脚本的参数，这与在gnuplot的交互模式下，gnuplot定义的含义是不同的。
在gnuplot的交互模式下，$1，$2，… 之类的变量是指输入数据文件的第1列，第2列，…
所以现在问题来了，当用shell脚本调用gnuplot时（就像本文上面给出的代码一样），如何能让gnuplot代码的$1，$2仍然取到的是数据文件的第1列，第2列？
这篇文章给出了解答，这里把几种方法列举如下：

'$1'
"\$1"
\$1

（3）如何在画出的曲线图中，每N个坐标点才标一个Y坐标值，而不是每个坐标点都标？
某些数据的点非常密集，如果我们把每个点旁边都标上它的Y坐标值，会导致图上的文字密密麻麻地挤在一起，从而使得我们根本看不清，因此，在这种情况下，我们只需要每N个点才标一个Y坐标值就可以了。
这个解决办法需要有点技巧。
假设某个数据文件 data.txt 的第1列是点的顺序编号（1，2，3，……），第2列是该点的纵坐标值，假设最后绘制图像的那一句是：

plot "data.txt" using 1:2 with linespoints linecolor 3 linewidth 1 pointtype 5 pointsize 1, "" using 1:2:2 with labels center offset 0,0.5

现在要对这一句进行特殊处理，使得它做到“每5个点绘制一个Y坐标值”，那么我们只需要把 using 1:2:2 这里改成：

using 1:2:(int(\$1) % 5 == 0 ? sprintf("%.3f", \$2) : "")

解释：
本来1:2:2的最后一个 2 表示将数据文件data.txt的第2列作为label的值（在这里也就是Y坐标值），但是我们把它改成了一个条件判断语句，gnuplot是支持的，很强大。
这个条件判断语句的含义是：当data.txt数据文件的第1列的值是5的整数倍的时候，我们打印出第2列的实际数值（以小数点后3位小数的格式），否则我们就打印出一个空字符串（这实际上导致了什么也不会打印出来）。
大家注意了，这里的为了取数据文件的第1列、第2列，用了 \$1 以及 \$2 的形式，我在前面第（2）条里说过了，这是由于shell脚本内置的参数变量$1，$2与gnuplot有冲突，所以要转义。
另外，为什么会在 \$1 外面包一个 int() 呢？如果没有的话，gnuplot会打印出类似于“can only mod ints”的一个错误提示。
这种解决方案比较微妙，但是它确实达到了我想要的效果。
那有人会说，如果data.txt的第一列不是点的顺序编号呢？在这种情况下，可以用程序自动地为data.txt加上一列（第1列），使其成为顺序编号，然后用第2、第3列来绘图就可以了。

文章来源：https://www.codelast.com/
➤➤ 版权声明 ➤➤
转载需注明出处：codelast.com
感谢关注我的微信公众号（微信扫一扫）：

[原创] Google Protocol Buffers中文教程

learnhard — Sun, 27 Oct 2013 08:43:29 +0000

注：前面这些是本人的翻译，可能不准确，可能有错误，但是基本上可以理解，希望能对大家有所帮助。

Protocol Buffer Basics: C++中文翻译（Google Protocol Buffers中文教程）

Language Guide中文翻译（Google Protocol Buffers中文教程）

Style Guide中文翻译（Google Protocol Buffers中文教程）

Techniques 中文翻译（Google Protocol Buffers中文教程）

下面是我使用Google Protocol Buffers的一些总结：

Protocol Buffers的Emacs语法高亮

文章来源：https://www.codelast.com/
➤➤ 版权声明 ➤➤
转载需注明出处：codelast.com
感谢关注我的微信公众号（微信扫一扫）：

shell脚本因文件编码问题不能正确执行的问题

learnhard — Tue, 14 Dec 2010 12:26:44 +0000

遇到一例因shell文件的编码问题导致执行后不能得到正确结果的问题。一般来说脚本中不会带有中文，不过有时候例外，例如你要查找一个文本中的字符串，cat test.txt | grep "汽车" 这样的命令，如果文件编码不对，就可能得不到正确结果。

我的问题是：有一个脚本，无论怎么执行结果都不对，但是我把它里面的关键的几句话单独拿出来，在SecureCRT终端下依次执行，最后得到的结果却正确，奇了。于是我终于想起来可能有中文的影响，在终端里查看shell脚本的内容，发现不能正确显示出一处中文（乱码了），可见正是这处乱码，导致了grep输出的结果不正确。但是在SecureCRT终端下，无论是用vi还是emacs，我都无法向文件中输入中文（上屏的中文全都乱码），于是怀疑是文件编码问题。

文章来源：http://www.codelast.com/

然后我就将脚本下载到Windows下，用UltraEdit将其另存为UTF-8格式，再上传到Linux中，再执行脚本，竟然报错：cannot execute binary file

这种问题的原因之一是脚本中有不可识别字符。于是我再用UltraEdit，将文件重新存为“UTF-8 无 BOM”格式（如下图），再上传到Linux中，就可以正确执行了。

网上还有很多文章，介绍了如何用emacs，vi 或 vim更改文件编码的方法，应该也是可以的，但用UltraEdit最方便。

文章来源：http://www.codelast.com/

另外再记一个小技巧：用 ps -ef | grep XXX 命令查看系统中是否存在某个进程的时候，输出结果中会包含有grep命令这一行，例如：

ps -ef | grep httpd

部分输出为：

root     27154 27129  0 20:35 pts/3    00:00:00 grep httpd
daemon   28834  2955  3 13:35 ?        00:16:23 /usr/local/apache2/bin/httpd -k start

可见第一行是干扰，我们不想看到它，那么可以有两种方法来过滤掉这一行：

ps -ef | grep httpd | grep -v grep

或：

ps -Ao pid,comm,args | grep httpd

这种方法输出的内容中只包含进程号、进程名、调用参数，具体使用可man ps。

文章来源：https://www.codelast.com/
➤➤ 版权声明 ➤➤
转载需注明出处：codelast.com
感谢关注我的微信公众号（微信扫一扫）：

[原创] Techniques 中文翻译（Google Protocol Buffers中文教程）

learnhard — Tue, 14 Sep 2010 05:37:00 +0000

Techniques 技巧

注：这是本人的翻译，可能不准确，可能有错误，但是基本上可以理解，希望能对大家有所帮助！（转载须注明出处：本文来自learnhard的博客：http://www.codelast.com/& http://blog.csdn.net/learnhard/）

· Streaming Multiple Messages

· Large Data Sets

· Union Types

· Self-describing Messages

This page describes some commonly-used design patterns for dealing with Protocol Buffers. You can also send design and usage questions to the Protocol Buffers discussion group.
文章来源：http://www.codelast.com/

l 将多个消息转化为流

l 大数据集

l 联合类型

l 自描述的消息

本文描述了处理Protocol Buffers的时候一些常用的设计模式。你也可以向Protocol Buffers讨论组（Protocol Buffers discussion group）发送设计和使用方面的问题寻求解答。

Streaming Multiple Messages 将多个消息转化为流

If you want to write multiple messages to a single file or stream, it is up to you to keep track of where one message ends and the next begins. The Protocol Buffer wire format is not self-delimiting, so protocol buffer parsers cannot determine where a message ends on their own. The easiest way to solve this problem is to write the size of each message before you write the message itself. When you read the messages back in, you read the size, then read the bytes into a separate buffer, then parse from that buffer. (If you want to avoid copying bytes to a separate buffer, check out the CodedInputStream class (in both C++ and Java) which can be told to limit reads to a certain number of bytes.)

如果你想将多个消息写入一个文件或流（stream）中，那么是由你来记录一个消息的终点以及另一个消息的起点的。Protocol Buffer数据传输格式不是自我限定的（self-delimiting），所以protocol buffer解析器无法自己决定一个消息结束于何处。解决这个问题的最简单的方法就是：在写入每一个消息之前，先写入消息的大小。当你读取消息的时候，先读取消息大小，然后将指定的字节数读入一个独立的缓冲区中，然后再解析缓冲区里的东西。如果你不想将数据拷贝到一个独立的缓冲区中，请查看CodedInputStream类（C++和Java都可用）的使用方法——你可以用它来限制只读取指定字节的数据。

文章来源：http://www.codelast.com/

Large Data Sets 大数据集

Protocol Buffers are not designed to handle large messages. As a general rule of thumb, if you are dealing in messages larger than a megabyte each, it may be time to consider an alternate strategy.

Protocol Buffers不是设计来处理大消息的。根据一般经验，如果你要处理的单条消息大于1M，那就是采取其他策略的时候了。

That said, Protocol Buffers are great for handling individual messages within a large data set. Usually, large data sets are really just a collection of small pieces, where each small piece may be a structured piece of data. Even though Protocol Buffers cannot handle the entire set at once, using Protocol Buffers to encode each piece greatly simplifies your problem: now all you need is to handle a set of byte strings rather than a set of structures.

也就是说，Protocol Buffers非常适合于处理一个大数据集内有多个单独的消息。通常，大数据集只是许多小块数据的集合，每一小块都是一块结构化的数据。即使是这样，Protocol Buffers也不能马上处理整个数据集，使用Protocol Buffers来编码每一块数据可以极大地简化你的问题：现在你所需要的只是处理一组字符串，而不是一组结构体了。

Protocol Buffers do not include any built-in support for large data sets because different situations call for different solutions. Sometimes a simple list of records will do while other times you may want something more like a database. Each solution should be developed as a separate library, so that only those who need it need to pay the costs.

Protocol Buffers没有内置任何对大数据集的支持，因为不同的情况需要不同的解决方案。

有时，一个简单的记录列表就解决问题了，而在某些情况下，你可能更想要的是类似于数据库的东西。每个解决方案都应该作为一个独立的库来开发，所以只有需要它的人才需要付出代价。

Union Types 联合类型

You may sometimes want to send a message that could be one of several different types. However, protocol buffer parsers cannot necessarily determine the type of a message based on the contents alone. So how do you make sure that the recipient application knows how to decode your message? One solution is to create a wrapper message that has one optional field for each possible message type.

有时，你可能想发送一个消息，它的类型可以是几种不同的类型之一。然而，protocol buffer解析器无法仅凭消息内容来决定消息的类型。所以，你如何确保接收方应用程序能知道怎么解析消息呢？有一个解决方案是：创建一个封装的消息，其含有N个optional的字段，每一个字段对应一种可能的消息类型。

文章来源：http://www.codelast.com/

For example, if you have message types Foo, Bar, and Baz, you can combine them with a type like:

例如，如果你有消息类型Foo，Bar和Baz，那么你可以将它们与类型结合起来，像这样：

message OneMessage {

// One of the following will be filled in.

optional Foo foo = 1;

optional Bar bar = 2;

optional Baz baz = 3;

}

You may also want to have an enum field that identifies which message is filled in, so that you can switch on it:

你也可能想这样做：添加一个枚举字段来标识是哪个消息被填充了，这样的话你就可以对它使用switch（来进行不同的处理）：

message OneMessage {

enum Type { FOO = 1; BAR = 2; BAZ = 3; }

// Identifies which field is filled in.

required Type type = 1;

// One of the following will be filled in.

optional Foo foo = 2;

optional Bar bar = 3;

optional Baz baz = 4;

}

If you have a very large number of possible types, listing every one of them in your container type may be unwieldy. Instead, you should consider using extensions:

如果你有大量“可能的类型”，那么在你的容器类型中将它们一一列举出来可能非常困难。在这种情况下，你应该考虑使用扩展（extensions）：

message OneMessage {

extensions 100 to max;

}

// Elsewhere...

extend OneMessage {

optional Foo foo_ext = 100;

optional Bar bar_ext = 101;

optional Baz baz_ext = 102;

}

Note that you can use the ListFields reflection method (in C++, Java, and Python) to get a list of all fields present in the message, including extensions. You might use this as part of a scheme for registering handlers for diverse message types.

注意：你可以使用反射函数ListFields（C++，Java和Python都可用）来获取一个消息中的所有字段的列表（包括扩展）。在实现一个为不同消息类型分别注册句柄的技术方案的时候，你可能用得上这个功能。

Self-describing Messages 自描述的消息

Protocol Buffers do not contain descriptions of their own types. Thus, given only a raw message without the corresponding .proto file defining its type, it is difficult to extract any useful data.

However, note that the contents of a .proto file can itself be represented using protocol buffers. The file src/google/protobuf/descriptor.protoin the source code package defines the message types involved. protoc can output a FileDescriptorSet – which represents a set of .proto files – using the --descriptor_set_out option. With this, you could define a self-describing protocol message like so:

Protocol Buffers不包含自我类型描述的信息。因此，如果只提供原始消息，而不提供对应的.proto文件，你将很难从中提取出任何有用的数据。

然而，请注意：一个.proto文件的内容可以使用protocol buffers来描述。通过使用--descriptor_set_out选项，源代码包中的src/google/protobuf/descriptor.proto文件定义了相关的消息类型。protoc编译器可以输出一个FileDescriptorSet——这个集合表示一系列的.proto文件。利用它，你可以像这样定义一个自描述的协议消息：

message SelfDescribingMessage {

// Set of .proto files which define the type.

required FileDescriptorSet proto_files = 1;

// Name of the message type. Must be defined by one of the files in

// proto_files.

required string type_name = 2;

// The message data.

required bytes message_data = 3;

}

By using classes like DynamicMessage (available in C++ and Java), you can then write tools which can manipulate SelfDescribingMessages.

All that said, the reason that this functionality is not included in the Protocol Buffer library is because we have never had a use for it inside Google.

通过使用像DynamicMessage这样的类（C++和Java都可用），你可以编写出操作SelfDescribingMessage的工具。

总之，Protocol Buffer库之所以没有包含这个特性，是因为我们在Google还从没有需要用它的机会。

文章来源：https://www.codelast.com/
➤➤ 版权声明 ➤➤
转载需注明出处：codelast.com
感谢关注我的微信公众号（微信扫一扫）：

[原创] Style Guide中文翻译（Google Protocol Buffers中文教程）

learnhard — Tue, 14 Sep 2010 05:30:16 +0000

Style Guide 风格指南

注：这是本人的翻译，可能不准确，可能有错误，但是基本上可以理解，希望能对大家有所帮助！（转载须注明出处：本文来自learnhard的博客：http://www.codelast.com/& http://blog.csdn.net/learnhard/）

This document provides a style guide for .proto files. By following these conventions, you'll make your protocol buffer message definitions and their corresponding classes consistent and easy to read.

本文档提供了.proto文件的书写风格指南。通过遵守这些约定，你的protocol buffer消息定义和它们的对应类将会风格一致且易于阅读。

Message And Field Names 消息和字段名

Use CamelCase (with an initial capital) for message names – for example, SongServerRequest. Use underscore_separated_names for field names – for example, song_name.

消息名使用驼峰格式（每个单词首字母大写）来书写——例如SongServerRequest。字段名使用小写的下划线分隔式（underscore_separated_names）来书写——例如song_name。

文章来源：http://www.codelast.com/

message SongServerRequest {

required string song_name = 1;

}

Using this naming convention for field names gives you accessors like the following:

字段名使用这种形式的命名约定的话，生成的访问类中的函数就有如下形式：

C++:
conststring& song_name(){...}
void set_song_name(conststring& x){...}

Java:
public String getSongName(){...}
public Builder setSongName(String v){...}

Enums 枚举

Use CamelCase (with an initial capital) for enum type names and CAPITALS_WITH_UNDERSCORES for value names:

枚举名使用驼峰格式（每个单词首字母大写）来书写，值名使用大写的下划线分隔式（CAPITALS_WITH_UNDERSCORES）来书写：

enum Foo {
FIRST_VALUE =1;
SECOND_VALUE =2;
}

Each enum value should end with a semicolon, not a comma.

每一个枚举值都应该以分号结尾，而不是逗号。

文章来源：http://www.codelast.com/

Services 服务

If your .proto defines an RPC service, you should use CamelCase (with an initial capital) for both the service name and any RPC method names:

如果你的.proto文件定义了一个RPC服务，那么服务名和任何RPC函数名都应该使用驼峰格式（每个单词首字母大写）来书写：

service FooService {

rpc GetSomething(FooRequest) returns (FooResponse);

}

文章来源：https://www.codelast.com/
➤➤ 版权声明 ➤➤
转载需注明出处：codelast.com
感谢关注我的微信公众号（微信扫一扫）：

[原创] Language Guide中文翻译（Google Protocol Buffers中文教程）

learnhard — Tue, 14 Sep 2010 05:22:37 +0000

Language Guide 语言指南

· Defining A Message Type

· Scalar Value Types

· Optional And Default Values

· Enumerations

· Using Other Message Types

· Nested Types

· Updating A Message Type

· Extensions

· Packages

· Defining Services

· Options

· Generating Your Classes

This guide describes how to use the protocol buffer language to structure your protocol buffer data, including .proto file syntax and how to generate data access classes from your .proto files.

This is a reference guide – for a step by step example that uses many of the features described in this document, see the tutorial for your chosen language.

l 定义一个消息（message）类型

l 标量值类型

l 可选的（optional）字段以及默认值

l 枚举

l 使用其他消息类型

l 嵌套类型

l 更新一个消息类型

l 扩展

l 包（package）

l 定义服务（service）

l 选项（option）

l 生成访问类

本指南描述了怎样使用protocol buffer语言来构造你的protocol buffer数据，包括.proto文件语法以及怎样生成.proto文件的数据访问类。

本文是一个参考指南——如果要查看如何使用本文中描述的多个特性的循序渐进的例子，请在tutorial中查找你需要的语言的教程。

Defining A Message Type 定义一个消息类型

First let's look at a very simple example. Let's say you want to define a search request message format, where each search request has a query string, the particular page of results you are interested in, and a number of results per page. Here's the .proto file you use to define the message type.

首先看一个非常简单的例子。假设你想定义一个“搜索请求”（search request）的消息格式，每一个搜索请求含有一个查询字符串、你感兴趣的查询结果所在的页数，以及每一页多少条查询结果。那么下面这个就是用来定义消息类型的.proto文件了：

message SearchRequest {

required string query = 1;

optional int32 page_number = 2;

optional int32 result_per_page = 3;

}

The SearchRequest message definition specifies three fields (name/value pairs), one for each piece of data that you want to include in this type of message. Each field has a name and a type.

SearchRequest消息类型指定了3个字段（名/值 对），你想在消息中承载的数据分别对应于每一个字段。每个字段都有一个名字（name）和一个类型（type）。

文章来源：http://www.codelast.com/

Specifying Field Types 指定字段类型

In the above example, all the fields are scalar types: two integers (page_number and result_per_page) and a string (query). However, you can also specify composite types for your fields, including enumerations and other message types.

在上面的例子中，所有字段都是标量类型（scalar types）:两个整型（page_number和result_per_page），一个string（query）。然而，你也可以为字段指定合成的类型，包括枚举（enumerations）以及其他消息类型。

Assigning Tags 分配标识号

As you can see, each field in the message definition has a unique numbered tag. These tags are used to identify your fields in the message binary format, and should not be changed once your message type is in use. Note that tags with values in the range 1 through 15 take one byte to encode. Tags in the range 16 through 2047 take two bytes. So you should reserve the tags 1 through 15 for very frequently occurring message elements. Remember to leave some room for frequently occurring elements that might be added in the future.

The smallest tag number you can specify is 1, and the largest is 2²⁹ - 1, or 536,870,911. You also cannot use the numbers 19000 though 19999 (FieldDescriptor::kFirstReservedNumber through FieldDescriptor::kLastReservedNumber), as they are reserved for the Protocol Buffers implementation - the protocol buffer compiler will complain if you use one of these reserved numbers in your .proto.

如你所见，在消息定义中，每一个字段都有一个独一无二的标识号（unique numbered tag）。这些标识号是用来在消息二进制格式（message binary format）中识别你的字段的。注意：[1,15]之内的标识号在编码的时候会占用一个字节。[16,2047]之内的标识号则占用2个字节。所以你应该为那些频繁出现的消息元素保留[1,15]之内的标识号。切记：要为将来有可能添加的、频繁出现的标识号预留一些标识号。

Specifying Field Rules 指定字段规则

You specify that message fields are one of the following:

· required: a well-formed message must have exactly one of this field.

· optional: a well-formed message can have zero or one of this field (but not more than one).

· repeated: this field can be repeated any number of times (including zero) in a well-formed message. The order of the repeated values will be preserved.

你所指定的消息字段必须是如下之一：

l required：一个格式良好的消息一定要含有1个这种字段。

l optional：一个格式良好的消息可以有0个或1个这种字段（但不超过1个）。

l repeated：在一个格式良好的消息中，这种字段可以重复任意多次（包括0次）。重复的值的顺序会被保留。

（译者注：这一段内容我不太理解，因为Google提供的.proto示例文件并没有按这个说法来编写…）

For historical reasons, repeated fields of basic numeric types aren't encoded as efficiently as they could be. New code should use the special option [packed=true] to get a more efficient encoding. For example:

由于历史原因，基本数值类型的repeated的字段并没有被尽可能地高效编码。在新的代码（译者注：这里是指.proto文件的内容）中，用户应该使用特殊选项[packed=true]来保证更高效的编码。例如：

repeated int32 samples = 4 [packed=true];

Required Is Forever You should be very careful about marking fields as required. If at some point you wish to stop writing or sending a required field, it will be problematic to change the field to an optional field – old readers will consider messages without this field to be incomplete and may reject or drop them unintentionally. You should consider writing application-specific custom validation routines for your buffers instead. Some engineers at Google have come to the conclusion that using required does more harm than good; they prefer to use onlyoptional and repeated. However, this view is not universal.

required是永久性的：在把一个字段标识为required的时候，你应该特别小心。如果在某些情况下你不想写入或者发送一个required的字段，那么将该字段更改为optional可能会遇到问题——旧版本的读者（译者注：即读取、解析消息的一方）会认为不含该字段的消息（message）是不完整的，从而有可能会拒绝解析。在这种情况下，你应该考虑编写特别针对于应用程序的、自定义的消息校验函数。Google的一些工程师得出了一个结论：使用required弊多于利；他们更愿意使用optional和repeated而不是required。当然，这个观点并不具有普遍性。

文章来源：http://www.codelast.com/

Adding More Message Types 添加更多消息类型

Multiple message types can be defined in a single .proto file. This is useful if you are defining multiple related messages – so, for example, if you wanted to define the reply message format that corresponds to your SearchResponse message type, you could add it to the same .proto:

在一个.proto文件中可以定义多个消息类型。在定义多个相关的消息的时候，这一点特别有用——例如，如果你想定义与你的SearchResponse消息类型对应的回复消息格式的话，你可以将它添加到相同的.proto文件中：

message SearchRequest {

required string query = 1;

optional int32 page_number = 2;

optional int32 result_per_page = 3;

}

message SearchResponse {

...

}

Adding Comments 添加注释

To add comments to your .proto files, use C/C++-style // syntax.

向.proto文件添加注释，可以使用C/C++风格的双斜杠（//） 语法格式。

message SearchRequest {

required string query = 1;

optional int32 page_number = 2;// Which page number do we want?

optional int32 result_per_page = 3;// Number of results to return per page.

}

What's Generated From Your .proto? 从你的.proto文件生成了什么？

When you run the protocol buffer compiler on a .proto, the compiler generates the code in your chosen language you'll need to work with the message types you've described in the file, including getting and setting field values, serializing your messages to an output stream, and parsing your messages from an input stream.

当你对.proto文件运行protocol buffer编译器（protocol buffer compiler）的时候，编译器生成你所选择的语言的代码，这些代码可以操作你在.proto文件中定义的消息类型，包括获取、设置字段值，将你的消息序列化到一个输出流中，以及从一个输入流中解析你的消息。

For C++, the compiler generates a .h and .cc file from each .proto, with a class for each message type described in your file.

For Java, the compiler generates a .java file with a class for each message type, as well as a special Builder classes for creating message class instances.

对C++来说，编译器为每一个.proto文件生成了一个.h文件和一个.cc文件，.proto文件中的每一个消息有一个对应的类。

对Java来说，编译器为每一个消息类型生成了一个.java文件，以及一个特殊的Builder类（这个类是用来创建消息类接口的）。

Python is a little different – the Python compiler generates a module with a static descriptor of each message type in your .proto, which is then used with a metaclass to create the necessary Python data access class at runtime.

You can find out more about using the APIs for each language by following the tutorial for your chosen language. For even more API details, see the relevant API reference.

对Python来说，有点不一样——Python编译器为.proto文件中的每个消息类型生成一个模型，其含有一个静态描述符（static descriptor，译者注：没用过Python，不清楚这样翻译正确与否），该模型与一个元类（metaclass）在运行时（runtime）被用来创建必需的Python数据访问类。

你可以从每种语言的教程中找到更多使用使用API的方法。如欲查看更详细的API信息，请阅相关的文章API reference。

Scalar Value Types 标量数值类型

A scalar message field can have one of the following types – the table shows the type specified in the .proto file, and the corresponding type in the automatically generated class:

一个标量消息字段可以含有一个如下的类型——该表格展示了定义于.proto文件中的类型，以及与之对应的、在自动生成的访问类中定义的类型：

.proto Type

Notes

C++ Type

Java Type

double

float

int32

Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.

使用可变长编码方式。编码负数时不够高效——如果你的字段可能含有负数，那么请使用sint32。

int32

int

int64

Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.

使用可变长编码方式。编码负数时不够高效——如果你的字段可能含有负数，那么请使用sint64。

int64

long

uint32

Uses variable-length encoding.

使用可变长编码方式。

uint32

int^[1]

uint64

Uses variable-length encoding.

使用可变长编码方式。

uint64

long^[1]

sint32

Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.

使用可变长编码方式。有符号的整型值。编码时比通常的int32高效。

int32

int

sint64

Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.

使用可变长编码方式。有符号的整型值。编码时比通常的int64高效。

int64

long

fixed32

Always four bytes. More efficient than uint32 if values are often greater than 2²⁸.

总是4个字节。如果数值总是比总是比2²⁸大的话，这个类型会比uint32高效。

uint32

int^[1]

fixed64

Always eight bytes. More efficient than uint64 if values are often greater than 2⁵⁶.

总是8个字节。如果数值总是比总是比2⁵⁶大的话，这个类型会比uint64高效。

uint64

long^[1]

sfixed32

Always four bytes.

总是4个字节。

int32

int

sfixed64

Always eight bytes.

总是8个字节。

int64

long

bool

boolean

string

A string must always contain UTF-8 encoded or 7-bit ASCII text.

一个字符串必须是UTF-8编码或者7-bit ASCII编码的文本。

string

String

bytes

May contain any arbitrary sequence of bytes.

可能包含任意顺序的字节数据。

string

ByteString

You can find out more about how these types are encoded when you serialize your message in Protocol Buffer Encoding.

^[1] In Java, unsigned 32-bit and 64-bit integers are represented using their signed counterparts, with the top bit simply being stored in the sign bit.

你可以在文章Protocol Buffer Encoding中，找到更多“序列化消息时各种类型如何编码”的信息。

^[1]在Java中，无符号32位和64位整型以它们对应的有符号类型来表示。

Optional Fields And Default Values Optional的字段和默认值

As mentioned above, elements in a message description can be labeled optional. A well-formed message may or may not contain an optional element. When a message is parsed, if it does not contain an optional element, the corresponding field in the parsed object is set to the default value for that field. The default value can be specified as part of the message description. For example, let's say you want to provide a default value of 10 for a SearchRequest's result_per_page value.

如上所述，消息描述中的一个元素可以被标记为“可选的”（optional）。一个格式良好的消息可以包含一个optional的元素，也可以不包含。当解析一个消息的时候，如果它不包含optional的元素，那么解析出来的对象中的对应字段就被置为默认值。默认值可以在消息描述文件中指定。例如，要为SearchRequest消息的result_per_page字段指定默认值10，可以这样做：

optional int32 result_per_page = 3 [default = 10];

If the default value is not specified for an optional element, a type-specific default value is used instead: for strings, the default value is the empty string. For bools, the default value is false. For numeric types, the default value is zero. For enums, the default value is the first value listed in the enum's type definition.

如果没有为optional的元素指定默认值，那么就会使用与特定类型相关的默认值：对string来说，默认值是空字符串。对bool来说，默认值是false。对数值类型来说，默认值是0。对枚举来说，默认值是枚举类型定义中的第一个值。

文章来源：http://www.codelast.com/

Enumerations 枚举

When you're defining a message type, you might want one of its fields to only have one of a pre-defined list of values. For example, let's say you want to add a corpus field for each SearchRequest, where the corpus can be UNIVERSAL, WEB, IMAGES, LOCAL, NEWS, PRODUCTS or VIDEO. You can do this very simply by adding an enum to your message definition - a field with an enum type can only have one of a specified set of constants as its value (if you try to provide a different value, the parser will treat it like an unknown field). In the following example we've added an enum called Corpuswith all the possible values, and a field of type Corpus:

当你定义一个消息类型的时候，你可能想为一个字段指定某“预定义值序列”（pre-defined list of values）中的一个值。例如，假设你想为每一个SearchRequest消息添加一个corpus字段，而corpus的值可能是UNIVERSAL，WEB，IMAGES，LOCAL，NEWS，PRODUCTS或VIDEO中的一个。你可以很容易地实现这一点：通过向你的消息定义中添加一个枚举（enum）就可以了。一个enum类型的字段只能用指定的常量集（specified set of constants）中的一个值作为其值（如果你尝试指定不同的值，解析器就会把它当作一个未知的字段来对待）。在下面的例子中，我们已经添加了一个叫做Corpus的枚举（enum）——它含有所有可能的值——以及一个类型为Corpus的字段：

message SearchRequest {

required string query = 1;

optional int32 page_number = 2;

optional int32 result_per_page = 3 [default = 10];

enum Corpus {

UNIVERSAL = 0;

WEB = 1;

IMAGES = 2;

LOCAL = 3;

NEWS = 4;

PRODUCTS = 5;

VIDEO = 6;

}

optional Corpus corpus = 4 [default = UNIVERSAL];

}

Enumerator constants must be in the range of a 32-bit integer. Since enum values use varint encoding on the wire, negative values are inefficient and thus not recommended. You can define enums within a message definition, as in the above example, or outside – these enums can be reused in any message definition in your .proto file. You can also use an enum type declared in one message as the type of a field in a different message, using the syntax MessageType.EnumType.

When you run the protocol buffer compiler on a .proto that uses an enum, the generated code will have a corresponding enum for Java or C++, or a special EnumDescriptor class for Python that's used to create a set of symbolic constants with integer values in the runtime-generated class.

For more information about how to work with message enums in your applications, see the generated code guide for your chosen language.

枚举常量必须在32位整型值的范围内。因为enum值是使用可变编码方式的，对负数不够高效，因此不推荐在enum中使用负数。如上例所示，你可以在一个消息定义的内部或外部定义枚举——这些枚举可以在你的.proto文件中的任何消息定义里重用。你也可以在一个消息中声明一个枚举类型，而在另一个不同的消息中使用它——采用MessageType.EnumType的语法格式。

当你对一个使用了枚举的.proto文件运行protocol buffer编译器的时候，生成的代码中将有一个对应的enum（对Java或C++来说），或者一个特殊的EnumDescriptor类（对Python来说），它被用来在运行时生成的类中创建一系列的整型值符号常量（symbolic constants）。

关于如何在你的应用程序的消息中使用枚举的更多信息，请查看你所选择的语言的generated code guide。

Using Other Message Types 使用其他消息类型

You can use other message types as field types. For example, let's say you wanted to include Result messages in each SearchResponsemessage – to do this, you can define a Result message type in the same .proto and then specify a field of type Result in SearchResponse:

你可以将其他消息类型用作字段类型。例如，假设你想在每一个SearchResponse消息中包含Result消息，你可以这样做——在相同的.proto文件中定义一个Result消息类型，然后在SearchResponse消息中指定一个Result类型的字段：

message SearchResponse {

repeated Result result = 1;

}

message Result {

required string url = 1;

optional string title = 2;

repeated string snippets = 3;

}

Importing Definitions 导入定义

In the above example, the Result message type is defined in the same file as SearchResponse – what if the message type you want to use as a field type is already defined in another .proto file?

在上面的例子中，Result消息类型与SearchResponse是定义在同一文件中的——如果你要使用的消息类型已经在其他.proto文件中已经定义过了呢？

You can use definitions from other .proto files by importing them. To import another .proto's definitions, you add an import statement to the top of your file:

你可以通过导入（importing）其他.proto文件中的定义来使用它们。要导入其他.proto文件的定义，你需要在你的文件中添加一个导入声明：

import "myproject/other_protos.proto";

The protocol compiler searches for imported files in a set of directories specified on the protocol compiler command line using the -I/--import_path flag. If no flag was given, it looks in the directory in which the compiler was invoked.

然后，protocol编译器就会在一系列目录中查找需要被导入的文件，这些目录通过protocol编译器的命令行参数-I/--import_path指定。如果不提供参数，编译器就在其调用目录下查找。

文章来源：http://www.codelast.com/

Nested Types 嵌套类型

You can define and use message types inside other message types, as in the following example – here the Result message is defined inside the SearchResponse message:

你可以在其他消息类型中定义、使用消息类型，在下面的例子中，Result消息就定义在SearchResponse消息内：

message SearchResponse {

message Result {

required string url = 1;

optional string title = 2;

repeated string snippets = 3;

}

repeated Result result = 1;

}

If you want to reuse this message type outside its parent message type, you refer to it as Parent.Type:

如果你想在它的父消息类型的外部重用这个消息类型，你需要以Parent.Type的形式使用它：

message SomeOtherMessage {

optional SearchResponse.Result result = 1;

}

You can nest messages as deeply as you like:

你可以将消息嵌套任意多层：

message Outer { // Level 0

message MiddleAA { // Level 1

message Inner { // Level 2

required int64 ival = 1;

optional bool booly = 2;

}

message MiddleBB { // Level 1

message Inner { // Level 2

required int32 ival = 1;

optional bool booly = 2;

}

Groups 组

Note that this feature is deprecated and should not be used when creating new message types – use nested message types instead.

注意：这个特性已经被弃用了，在创建新的消息类型的时候，不应该再使用它——你应该使用嵌套消息类型来代替它。

Groups are another way to nest information in your message definitions. For example, another way to specify a SearchResponse containing a number of Results is as follows:

“组”是在你的消息定义中嵌套信息的另一种方法。例如，在SearchResponse中包含若干Result的另一种方法是：

message SearchResponse {

repeated group Result = 1 {

required string url = 2;

optional string title = 3;

repeated string snippets = 4;

}

A group simply combines a nested message type and a field into a single declaration. In your code, you can treat this message just as if it had aResult type field called result (the latter name is converted to lower-case so that it does not conflict with the former). Therefore, this example is exactly equivalent to the SearchResponse above, except that the message has a different wire format.

一个“组”只是简单地将一个嵌套消息类型和一个字段捆绑到一个单独的声明中。在你的代码中，你可以把它看成是含有一个Result类型、名叫result的字段的消息（后面的名字被转换成了小写，所以它不会与前面的冲突）。

因此，除了数据传输格式（wire format）不同之外，这个例子与上面的SearchResponse例子是完全等价的。

Updating A Message Type 更新一个消息类型

If an existing message type no longer meets all your needs – for example, you'd like the message format to have an extra field – but you'd still like to use code created with the old format, don't worry! It's very simple to update message types without breaking any of your existing code. Just remember the following rules:

如果一个已有的消息无法再满足你的需求——例如，你想在消息中添加一个额外的字段——但是你同时还想让为旧版本写的代码仍然可用，不用怕！更新消息而不破坏已有代码是非常简单的。只要你记住下面的规则：

· Don't change the numeric tags for any existing fields.

· Any new fields that you add should be optional or repeated. This means that any messages serialized by code using your "old" message format can be parsed by your new generated code, as they won't be missing any required elements. You should set up sensible default values for these elements so that new code can properly interact with messages generated by old code. Similarly, messages created by your new code can be parsed by your old code: old binaries simply ignore the new field when parsing. However, the unknown fields are not discarded, and if the message is later serialized, the unknown fields are serialized along with it – so if the message is passed on to new code, the new fields are still available. Note that preservation of unknown fields is currently not available for Python.

· Non-required fields can be removed, as long as the tag number is not used again in your updated message type (it may be better to rename the field instead, perhaps adding the prefix "OBSOLETE_", so that future users of your .proto can't accidentally reuse the number).

· A non-required field can be converted to an extension and vice versa, as long as the type and number stay the same.

· int32, uint32, int64, uint64, and bool are all compatible – this means you can change a field from one of these types to another without breaking forwards- or backwards-compatibility. If a number is parsed from the wire which doesn't fit in the corresponding type, you will get the same effect as if you had cast the number to that type in C++ (e.g. if a 64-bit number is read as an int32, it will be truncated to 32 bits).

· sint32 and sint64 are compatible with each other but are not compatible with the other integer types.

· string and bytes are compatible as long as the bytes are valid UTF-8.

· Embedded messages are compatible with bytes if the bytes contain an encoded version of the message.

· fixed32 is compatible with sfixed32, and fixed64 with sfixed64.

l 不要更改任何已有的字段的数值标识（tag）。

l 你添加的任何字段都必须是optional或repeated的。这就意味着任何使用你的“旧”消息格式的代码序列化的消息可以被你的新代码所解析，因为它们不会丢掉任何required的元素。你应该为这些元素设置合理的默认值（default values），这样新的代码就能够正确地与老代码生成的消息交互了。类似地，你的新代码创建的消息也能被你的老代码解析：老的二进制程序在解析的时候只是简单地将新字段忽略。然而，未知的字段是没有被抛弃的，此后，如果消息被序列化，未知的字段会随之一起被序列化——所以，如果消息传到了新代码那里，则新的字段仍然可用。注意：对Python来说，对未知字段的保留策略是无效的。

l 非required的字段可以移除——只要它们的标识号（tag number）在你的新消息类型中不再使用（更好的做法可能是重命名那个字段，例如在字段前添加“OBSOLETE_”前缀，那样的话，你的.proto文件的用户将来就不会无意中重新使用了那些不该使用的标识号）。

l 一个非required的字段可以转换为一个扩展（extension），反之亦然——只要它的类型和标识号保持不变。

l int32, uint32, int64, uint64,和bool是全部兼容的，这意味着你可以将这些类型中的一个转换为另外一个，而不会破坏前向、后向的兼容性。如果解析出来的数字与对应的类型不相符，那么结果就像在C++中对它进行了强制类型转换一样（例如，如果把一个64位数字当作int32来读取，那么它就会被截断为32位的数字）。

l sint32和sint64是互相兼容的，但是它们与其他整数类型不兼容。

l string和bytes是兼容的——只要bytes是有效的UTF-8编码。

l 嵌套消息与bytes是兼容的——只要bytes包含该消息的一个编码过的版本。

l fixed32与sfixed32是兼容的，fixed64与sfixed64是兼容的。

Extensions 扩展

Extensions let you declare that a range of field numbers in a message are available for third-party extensions. Other people can then declare new fields for your message type with those numeric tags in their own .proto files without having to edit the original file. Let's look at an example:

通过扩展，你可以将一个范围内的字段标识号声明为可被第三方扩展所用。然后，其他人就可以在他们自己的.proto文件中为你的消息类型声明新的字段，而不必去编辑原始文件了。让我们看个例子：

message Foo {

// ...

extensions 100 to 199;

}

This says that the range of field numbers [100, 199] in Foo is reserved for extensions. Other users can now add new fields to Foo in their own.proto files that import your .proto, using tags within your specified range – for example:

这个例子表明：在消息Foo中，范围[100,199]之内的字段标识号被保留为扩展用。现在，其他人就可以在他们自己的.proto文件中添加新字段到Foo里了，但是添加的字段标识号要在指定的范围内——例如：

extend Foo {

optional int32 bar = 126;

}

This says that Foo now has an optional int32 field called bar.

When your user's Foo messages are encoded, the wire format is exactly the same as if the user defined the new field inside Foo. However, the way you access extension fields in your application code is slightly different to accessing regular fields – your generated data access code has special accessors for working with extensions. So, for example, here's how you set the value of bar in C++:

这个例子表明：消息Foo现在有一个名为bar的optional int32字段。

当用户的Foo消息被编码的时候，数据的传输格式与用户在Foo里定义新字段的效果是完全一样的。

然而，你在程序代码中访问扩展字段的方法与访问普通的字段稍有不同——你生成的数据访问代码为扩展准备了特殊的访问函数来访问它。例如，下面是你如何在C++中设置bar的值：

Foo foo;
foo.SetExtension(bar, 15);

Similarly, the Foo class defines templated accessors HasExtension(), ClearExtension(), GetExtension(), MutableExtension(), andAddExtension(). All have semantics matching the corresponding generated accessors for a normal field. For more information about working with extensions, see the generated code reference for your chosen language.

Note that extensions can be of any field type, including message types.

类似地，Foo类也定义了模板函数HasExtension()，ClearExtension()，GetExtension()，MutableExtension()，以及AddExtension()。这些函数的语义都与对应的普通字段的访问函数相符。要查看更多使用扩展的信息，请参考相应语言的代码生成指南。

注意：扩展可以是任何字段类型，包括消息类型。

文章来源：http://www.codelast.com/

Nested Extensions 嵌套的扩展

You can declare extensions in the scope of another type:

你可以在另一个类型的范围内声明扩展：

message Baz {

extend Foo {

optional int32 bar = 126;

}

...

}

In this case, the C++ code to access this extension is:

在此例中，访问此扩展的C++代码是：

Foo foo;

foo.SetExtension(Baz::bar, 15);

In other words, the only effect is that bar is defined within the scope of Baz.

换句话说，唯一的效果就是bar被定义在Baz的范围内。

This is a common source of confusion: Declaring an extend block nested inside a message type does not imply any relationship between the outer type and the extended type. In particular, the above example does not mean that Baz is any sort of subclass of Foo. All it means is that the symbol bar is declared inside the scope of Baz; it's simply a static member.

这是个引起混淆的来源：在一个消息类型中嵌套声明一个extend块并没有暗示外部类型（outer type）与扩展类型（extended type）之间有任何联系。特别地，上面的例子没有表明Baz是Foo的任何类型的子类。它所表明的仅仅是：符号bar是在Baz的内部声明的；它只是一个静态成员罢了。

A common pattern is to define extensions inside the scope of the extension's field type – for example, here's an extension to Foo of type Baz, where the extension is defined as part of Baz:

一个通常的设计模式就是：在扩展的字段类型的范围内定义该扩展——例如，下面是一个Foo的扩展（该扩展是Baz类型的），其中，扩展被定义为了Baz的一部分：

（译者注：这样的定义形式确很容易引起混淆，请继续往下看，以帮助你消除这种混淆）

message Baz {

extend Foo {

optional Baz foo_ext = 127;

}

...

}

However, there is no requirement that an extension with a message type be defined inside that type. You can also do this:

然而，并没有强制要求一个消息类型的扩展一定要定义在那个消息中。你也可以这样做：

message Baz {

...

}

// This can even be in a different file.

extend Foo {

optional Baz foo_baz_ext = 127;

}

In fact, this syntax may be preferred to avoid confusion. As mentioned above, the nested syntax is often mistaken for subclassing by users who are not already familiar with extensions.

事实上，这种语法格式更能防止引起混淆。正如上面所提到的，嵌套的语法通常被错误地认为有子类化的关系——尤其是对那些还不熟悉扩展的用户来说。

文章来源：https://www.codelast.com/
➤➤ 版权声明 ➤➤
转载需注明出处：codelast.com
感谢关注我的微信公众号（微信扫一扫）：

[原创] Protocol Buffer Basics: C++中文翻译（Google Protocol Buffers中文教程）

learnhard — Tue, 14 Sep 2010 05:04:12 +0000

Protocol Buffer Basics: C++（Protocol Buffer基础：C++篇）

注：这是本人的翻译，可能不准确，可能有错误，但是基本上可以理解，希望能对大家有所帮助！（转载需注明出处：本文来自learnhard的博客：http://www.codelast.com/ & http://blog.csdn.net/learnhard/）

This tutorial provides a basic C++ programmer's introduction to working with protocol buffers. By walking through creating a simple example application, it shows you how to

· Define message formats in a .proto file.

· Use the protocol buffer compiler.

· Use the C++ protocol buffer API to write and read messages.

本教程提供了面向C++程序员的protocol buffers的基本介绍。通过创建一个简单的示例程序，它教你如何：

l 定义.proto文件的消息格式。

l 使用protocol buffer的编译器。

l 使用protoco buffer的C++ API来读写消息。

This isn't a comprehensive guide to using protocol buffers in C++. For more detailed reference information, see the Protocol Buffer Language Guide, the C++ API Reference, the C++ Generated Code Guide, and the Encoding Reference.

本文并不是关于protocol buffers的C++使用的全面教程。要查看更详细的参考资料，请阅如下文章：Protocol Buffer Language Guide，C++ API Reference，C++ Generated Code Guide，以及 Encoding Reference。

Why Use Protocol Buffers? 为什么要使用protocol buffers？

The example we're going to use is a very simple "address book" application that can read and write people's contact details to and from a file. Each person in the address book has a name, an ID, an email address, and a contact phone number.

How do you serialize and retrieve structured data like this? There are a few ways to solve this problem:

· The raw in-memory data structures can be sent/saved in binary form. Over time, this is a fragile approach, as the receiving/reading code must be compiled with exactly the same memory layout, endianness, etc. Also, as files accumulate data in the raw format and copies of software that are wired for that format are spread around, it's very hard to extend the format.

· You can invent an ad-hoc way to encode the data items into a single string – such as encoding 4 ints as "12:3:-23:67". This is a simple and flexible approach, although it does require writing one-off encoding and parsing code, and the parsing imposes a small run-time cost. This works best for encoding very simple data.

· Serialize the data to XML. This approach can be very attractive since XML is (sort of) human readable and there are binding libraries for lots of languages. This can be a good choice if you want to share data with other applications/projects. However, XML is notoriously space intensive, and encoding/decoding it can impose a huge performance penalty on applications. Also, navigating an XML DOM tree is considerably more complicated than navigating simple fields in a class normally would be.

Protocol buffers are the flexible, efficient, automated solution to solve exactly this problem. With protocol buffers, you write a .proto description of the data structure you wish to store. From that, the protocol buffer compiler creates a class that implements automatic encoding and parsing of the protocol buffer data with an efficient binary format. The generated class provides getters and setters for the fields that make up a protocol buffer and takes care of the details of reading and writing the protocol buffer as a unit. Importantly, the protocol buffer format supports the idea of extending the format over time in such a way that the code can still read data encoded with the old format.

（这一段不翻译了，没意思）

Where to Find the Example Code 在哪可以找到示例代码

The example code is included in the source code package, under the "examples" directory. Download it here.

示例代码包含在源代码包中的“examples”目录下。点击此处下载。

Defining Your Protocol Format 定义你自己的协议格式

To create your address book application, you'll need to start with a .proto file. The definitions in a .proto file are simple: you add a message for each data structure you want to serialize, then specify a name and a type for each field in the message. Here is the .proto file that defines your messages, addressbook.proto.

要创建你的地址薄应用程序，你需要从编写一个.proto文件开始。.proto文件的定义是比较简单的：为每一个你需要序列化的数据结构添加一个消息（message），然后为消息（message）中的每一个字段（field）指定一个名字和一个类型。下面就是一个定义你的多个消息（messages）的文件addressbook.proto：

package tutorial;

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;

}

message AddressBook {

repeated Person person = 1;

}

As you can see, the syntax is similar to C++ or Java. Let's go through each part of the file and see what it does.

正如你所看到的一样，该语法类似于C++或Java的语法。让我们依次来看看文件的每一部分的作用。

The .proto file starts with a package declaration, which helps to prevent naming conflicts between different projects. In C++, your generated classes will be placed in a namespace matching the package name.

.proto文件以一个package声明开始。这个声明是为了防止不同项目之间的命名冲突。对应到C++中去，你用这个.proto文件生成的类将被放置在一个与package名相同的命名空间中。

文章来源：http://www.codelast.com/

Next, you have your message definitions. A message is just an aggregate containing a set of typed fields. Many standard simple data types are available as field types, including bool, int32, float, double, and string. You can also add further structure to your messages by using other message types as field types – in the above example the Person message contains PhoneNumber messages, while the AddressBook message contains Person messages. You can even define message types nested inside other messages – as you can see, the PhoneNumber type is defined inside Person. You can also define enum types if you want one of your fields to have one of a predefined list of values – here you want to specify that a phone number can be one of MOBILE, HOME, or WORK.

再往下看，就是若干消息（message）定义了。一个消息就是某些类型的字段的集合。许多标准的、简单的数据类型都可以用作字段类型，包括bool，int32，float，double，以及string。你也可以使用其他的消息（message）类型来作为你的字段类型——在上面的例子中，消息Person就是一个被用作字段类型的例子。

The " = 1", " = 2" markers on each element identify the unique "tag" that field uses in the binary encoding. Tag numbers 1-15 require one less byte to encode than higher numbers, so as an optimization you can decide to use those tags for the commonly used or repeated elements, leaving tags 16 and higher for less-commonly used optional elements. Each element in a repeated field requires re-encoding the tag number, so repeated fields are particularly good candidates for this optimization.

在每一项后面的、类似于“= 1”，“= 2”的标志指出了该字段在二进制编码中使用的唯一“标识（tag）”。标识号1~15编码所需的字节数比更大的标识号使用的字节数要少1个，所以，如果你想寻求优化，可以为经常使用或者重复的项采用1~15的标识（tag），其他经常使用的optional项采用≥16的标识（tag）。在重复的字段中，每一项都要求重编码标识号（tag number），所以重复的字段特别适用于这种优化情况。

Each field must be annotated with one of the following modifiers:

· required: a value for the field must be provided, otherwise the message will be considered "uninitialized". If libprotobuf is compiled in debug mode, serializing an uninitialized message will cause an assertion failure. In optimized builds, the check is skipped and the message will be written anyway. However, parsing an uninitialized message will always fail (by returning false from the parse method). Other than this, a required field behaves exactly like an optional field.

· optional: the field may or may not be set. If an optional field value isn't set, a default value is used. For simple types, you can specify your own default value, as we've done for the phone number type in the example. Otherwise, a system default is used: zero for numeric types, the empty string for strings, false for bools. For embedded messages, the default value is always the "default instance" or "prototype" of the message, which has none of its fields set. Calling the accessor to get the value of an optional (or required) field which has not been explicitly set always returns that field's default value.

· repeated: the field may be repeated any number of times (including zero). The order of the repeated values will be preserved in the protocol buffer. Think of repeated fields as dynamically sized arrays.

每一个字段都必须用以下之一的修饰符来修饰：

l required：必须提供字段值，否则对应的消息就会被认为是“未初始化的”。如果libprotobuf是以debug模式编译的，序列化一个未初始化的消息（message）将会导致一个断言错误。在优化过的编译情况下（译者注：例如release），该检查会被跳过，消息会被写入。然而，解析一个未初始化的消息仍然会失败（解析函数会返回false）。除此之外，一个required的字段与一个optional的字段就没有区别了。

l optional：字段值指定与否都可以。如果没有指定一个optional的字段值，它就会使用默认值。对简单类型来说，你可以指定你自己的默认值，就像我们在上面的例子中对phone number的type字段所做的一样。如果你不指定默认值，就会使用系统默认值：数据类型的默认值为0，string的默认值为空字符串，bool的默认值为false。对嵌套消息（message）来说，其默认值总是消息的“默认实例”或“原型”，即：没有任何一个字段是指定了值的。调用访问类来取一个未显式指定其值的optional（或者required）的字段的值，总是会返回字段的默认值。

l repeated：字段会重复N次（N可以为0）。重复的值的顺序将被保存在protocol buffer中。你只要将重复的字段视为动态大小的数组就可以了。

文章来源：http://www.codelast.com/

You'll find a complete guide to writing .proto files – including all the possible field types – in the Protocol Buffer Language Guide. Don't go looking for facilities similar to class inheritance, though – protocol buffers don't do that.

你可以在Protocol Buffer Language Guide一文中找到编写.proto文件的完整指南（包括所有可能的字段类型）。但是，不要想在里面找到与类继承相似的特性，因为protocol buffers不是拿来做这个的。

Compiling Your Protocol Buffers 编译你的protocol buffers

Now that you have a .proto, the next thing you need to do is generate the classes you'll need to read and write AddressBook (and hence Personand PhoneNumber) messages. To do this, you need to run the protocol buffer compiler protoc on your .proto:

1. If you haven't installed the compiler, download the package and follow the instructions in the README.

2. Now run the compiler, specifying the source directory (where your application's source code lives – the current directory is used if you don't provide a value), the destination directory (where you want the generated code to go; often the same as $SRC_DIR), and the path to your.proto. In this case, you...:

protoc -I=$SRC_DIR --cpp_out=$DST_DIR $SRC_DIR/addressbook.proto

Because you want C++ classes, you use the --cpp_out option – similar options are provided for other supported languages.

This generates the following files in your specified destination directory:

· addressbook.pb.h, the header which declares your generated classes.

· addressbook.pb.cc, which contains the implementation of your classes.

在得到了一个.proto文件之后，下一步你就要生成可以读写AddressBook消息（当然也就包括了Person以及PhoneNumber消息）的类了。此时你需要运行protocol buffer编译器来编译你的.proto文件：

1. 如果你还没有安装该编译器，下载安装包 并参照README文件中的说明来安装。

2. 安装了之后，就可以运行编译器了。指定源目录（即你的应用程序源代码所在的目录——如果不指定的话，就使用当前目录）、目标目录（即生成的代码放置的目录，通常与$SRC_DIR是一样的），以及你的.proto文件所在的目录。在我们这里，可以这样用：

protoc -I=$SRC_DIR --cpp_out=$DST_DIR $SRC_DIR/addressbook.proto

因为需要生成的是C++类，所以使用了--cpp_out选项参数——protocol buffers也为其他支持的语言提供了类似的选项参数。这样就可以在你指定的目标目录下生成如下文件：

l addressbook.pb.h：声明你生成的类的头文件。

l addressbook.pb.cc：你生成的类的实现文件。

The Protocol Buffer API

Let's look at some of the generated code and see what classes and functions the compiler has created for you. If you look in tutorial.pb.h, you can see that you have a class for each message you specified in tutorial.proto. Looking closer at the Person class, you can see that the complier has generated accessors for each field. For example, for the name, id, email, and phone fields, you have these methods:

让我们看一下生成的代码，了解一下编译器为你创建了什么样的类和函数。如果你看了tutorial.pb.h文件，就会发现你得到了一个类，它对应于tutorial.proto文件中写的每一个消息（message）。更深入一步，看看Person 类：编译器为每一个字段生成了读写函数。例如，对name，id，email以及phone字段，分别有如下函数：

// name
inline bool has_name() const;
inline void clear_name();
inline const ::std::string& name() const;
inline void set_name(const ::std::string& value);
inline void set_name(const char* value);
inline ::std::string* mutable_name();

// id
inline bool has_id() const;
inline void clear_id();
inline int32_t id() const;
inline void set_id(int32_t value);

// email
inline bool has_email() const;
inline void clear_email();
inline const ::std::string& email() const;
inline void set_email(const ::std::string& value);
inline void set_email(const char* value);
inline ::std::string* mutable_email();

// phone
inline int phone_size() const;
inline void clear_phone();
inline const ::google::protobuf::RepeatedPtrField< ::tutorial::Person_PhoneNumber >& phone() const;
inline ::google::protobuf::RepeatedPtrField< ::tutorial::Person_PhoneNumber >* mutable_phone();
inline const ::tutorial::Person_PhoneNumber& phone(int index) const;
inline ::tutorial::Person_PhoneNumber* mutable_phone(int index);
inline ::tutorial::Person_PhoneNumber* add_phone();

As you can see, the getters have exactly the name as the field in lowercase, and the setter methods begin with set_. There are also has_ methods for each singular (required or optional) field which return true if that field has been set. Finally, each field has a clear_ method that un-sets the field back to its empty state.

正如你所看到的，getter函数具有与字段名一模一样的名字，并且是小写的，而setter函数都是以set_前缀开头。此外，还有has_前缀的函数，对每一个单一的（required或optional的）字段（译者注：此处估计是“非repeated字段”的意思）来说，如果字段被置（set）了值，该函数会返回true。最后，每一个字段还有一个clear_前缀的函数，用来将字段重置（un-set）到空状态（empty state）。

文章来源：http://www.codelast.com/

While the numeric id field just has the basic accessor set described above, the name and email fields have a couple of extra methods because they're strings – a mutable_ getter that lets you get a direct pointer to the string, and an extra setter. Note that you can call mutable_email() even ifemail is not already set; it will be initialized to an empty string automatically. If you had a singular message field in this example, it would also have a mutable_ method but not a set_ method.

然而，数值类型的字段id就只有如上所述的基本读写函数，name和email字段则有一些额外的函数，因为它们是string——前缀为mutable_的函数返回string的直接指针（direct pointer）。除此之外，还有一个额外的setter函数。注意：你甚至可以在email还没有被置（set）值的时候就调用mutable_email()，它会被自动初始化为一个空字符串。在此例中，如果有一个单一消息字段，那么它也会有一个mutable_ 前缀的函数，但是没有一个set_ 前缀的函数。

Repeated fields also have some special methods – if you look at the methods for the repeated phone field, you'll see that you can

· check the repeated field's _size (in other words, how many phone numbers are associated with this Person).

· get a specified phone number using its index.

· update an existing phone number at the specified index.

· add another phone number to the message which you can then edit (repeated scalar types have an add_ that just lets you pass in the new value).

重复的字段也有一些特殊的函数——如果你看一下重复字段phone 的那些函数，就会发现你可以：

l 得到重复字段的_size（换句话说，这个Person关联了多少个电话号码）。

l 通过索引（index）来获取一个指定的电话号码。

l 通过指定的索引（index）来更新一个已经存在的电话号码。

l 向消息（message）中添加另一个电话号码，然后你可以编辑它（重复的标量类型有一个add_前缀的函数，允许你传新值进去）。

For more information on exactly what members the protocol compiler generates for any particular field definition, see the C++ generated code reference.

关于编译器如何生成特殊字段的更多信息，请查看文章C++ generated code reference。

Enums and Nested Classes 枚举和嵌套类

The generated code includes a PhoneType enum that corresponds to your .proto enum. You can refer to this type as Person::PhoneType and its values as Person::MOBILE, Person::HOME, and Person::WORK (the implementation details are a little more complicated, but you don't need to understand them to use the enum).

生成的代码中包含了一个PhoneType 枚举，它对应于.proto文件中的那个枚举。你可以把这个类型当作Person::PhoneType，其值为Person::MOBILE，Person::HOME和Person::WORK（实现的细节稍微复杂了点，但是没关系，不理解它也不会影响你使用该枚举）。

The compiler has also generated a nested class for you called Person::PhoneNumber. If you look at the code, you can see that the "real" class is actually called Person_PhoneNumber, but a typedef defined inside Person allows you to treat it as if it were a nested class. The only case where this makes a difference is if you want to forward-declare the class in another file – you cannot forward-declare nested types in C++, but you can forward-declare Person_PhoneNumber.

编译器还生成了一个名为Person::PhoneNumber的嵌套类。如果你看看代码，就会发现“真实的”类实际上是叫做Person_PhoneNumber，只不过Person 内部的一个typedef允许你像一个嵌套类一样来对待它。这一点所造成的唯一一个区别就是：如果你想在另一个文件中对类进行前向声明（forward-declare）的话，你就不能在C++中对嵌套类型进行前向声明了，但是你可以对Person_PhoneNumber进行前向声明。

Standard Message Methods 标准消息函数

Each message class also contains a number of other methods that let you check or manipulate the entire message, including:

· bool IsInitialized() const;: checks if all the required fields have been set.

· string DebugString() const;: returns a human-readable representation of the message, particularly useful for debugging.

· void CopyFrom(const Person& from);: overwrites the message with the given message's values.

· void Clear();: clears all the elements back to the empty state.

These and the I/O methods described in the following section implement the Message interface shared by all C++ protocol buffer classes. For more info, see the complete API documentation for Message.

每一个消息（message）还包含了其他一系列函数，用来检查或管理整个消息，包括：

l bool IsInitialized() const;：检查是否全部的required字段都被置（set）了值。

l string DebugString() const;：返回一个易读的消息表示形式，对调试特别有用。

l void CopyFrom(const Person& from);：用外部消息的值，覆写调用者消息内部的值。

l void Clear();：将所有项复位到空状态（empty state）。

这些函数以及后面章节将要提到的I/O函数实现了Message 的接口，它们被所有C++ protocol buffer类共享。更多信息，请查看文章 complete API documentation for Message。

Parsing and Serialization 解析&序列化

Finally, each protocol buffer class has methods for writing and reading messages of your chosen type using the protocol buffer binary format. These include:

· bool SerializeToString(string* output) const;: serializes the message and stores the bytes in the given string. Note that the bytes are binary, not text; we only use the string class as a convenient container.

· bool ParseFromString(const string& data);: parses a message from the given string.

· bool SerializeToOstream(ostream* output) const;: writes the message to the given C++ ostream.

· bool ParseFromIstream(istream* input);: parses a message from the given C++ istream.

These are just a couple of the options provided for parsing and serialization. Again, see the Message API reference for a complete list.

最后，每一个protocol buffer类都有读写你所选择的消息类型的函数。它们包括：

l bool SerializeToString(string* output) const;：将消息序列化并储存在指定的string中。注意里面的内容是二进制的，而不是文本；我们只是使用string作为一个很方便的容器。

l bool ParseFromString(const string& data);：从给定的string解析消息。

l bool SerializeToOstream(ostream* output) const;：将消息写入到给定的C++ ostream中。

l bool ParseFromIstream(istream* input);：从给定的C++ istream解析消息。

这些函数只是用于解析和序列化的几个函数罢了。请再次参考Message API reference以查看完整的函数列表。

Protocol Buffers and O-O Design Protocol buffer classes are basically dumb data holders (like structs in C++); they don't make good first class citizens in an object model. If you want to add richer behaviour to a generated class, the best way to do this is to wrap the generated protocol buffer class in an application-specific class. Wrapping protocol buffers is also a good idea if you don't have control over the design of the .proto file (if, say, you're reusing one from another project). In that case, you can use the wrapper class to craft an interface better suited to the unique environment of your application: hiding some data and methods, exposing convenience functions, etc. You should never add behaviour to the generated classes by inheriting from them. This will break internal mechanisms and is not good object-oriented practice anyway.

protocol buffers和面向对象的设计 protocol buffer类通常只是纯粹的数据存储器（就像C++中的结构体一样）；它们在对象模型中并不是一等公民。如果你想向生成的类中添加更丰富的行为，最好的方法就是在应用程序中对它进行封装。如果你无权控制.proto文件的设计的话，封装protocol buffers也是一个好主意（例如，你从另一个项目中重用一个.proto文件）。在那种情况下，你可以用封装类来设计接口，以更好地适应你的应用程序的特定环境：隐藏一些数据和方法，暴露一些便于使用的函数，等等。但是你绝对不要通过继承生成的类来添加行为。这样做的话，会破坏其内部机制，并且不是一个好的面向对象的实践。

Writing A Message 写消息

Now let's try using your protocol buffer classes. The first thing you want your address book application to be able to do is write personal details to your address book file. To do this, you need to create and populate instances of your protocol buffer classes and then write them to an output stream.

Here is a program which reads an AddressBook from a file, adds one new Person to it based on user input, and writes the new AddressBook back out to the file again. The parts which directly call or reference code generated by the protocol compiler are highlighted.

现在让我们尝试使用你的protocol buffer类。你想让你的address book程序完成的第一件事情就是向你的address book文件写入详细的个人信息。要实现这一点，你需要创建protocol buffer类的实例并将它们写入到一个输出流（output stream）中。

下面的这个程序从一个文件中读取AddressBook ，然后根据用户的输入向其中添加一个新的Person ，然后再将新的AddressBook 写回文件中。由protocol buffer编译器生成的代码或者直接调用的代码都被突出显示了。

#include
#include
#include
#include "addressbook.pb.h"
using namespace std;

// This function fills in a Person message based on user input.
void PromptForAddress(tutorial::Person* person) {
cout << "Enter person ID number: ";
int id;
cin >> id;
person->set_id(id);
cin.ignore(256, '\n'); // cin.ignore(a,ch)方法是从输入流（cin）中提取字符，提取的字符被忽略（ignore），不被使用。每抛弃一个字符，它都要计数和比较字符：如果计数值达到a或者被抛弃的字符是ch，则cin.ignore()函数执行终止；否则，它继续等待。它的一个常用功能就是用来清除以回车结束的输入缓冲区的内容，消除上一次输入对下一次输入的影响。比如可以这么用：cin.ignore(1024,'\n')，通常把第一个参数设置得足够大，这样实际上总是只有第二个参数'\n'起作用，所以这一句就是把回车（包括回车）之前的所以字符从输入缓冲（流）中清除出去。

cout << "Enter name: ";
getline(cin, *person->mutable_name());

cout << "Enter email address (blank for none): ";
string email;
getline(cin, email);
if (!email.empty()) {
person->set_email(email);
}

while (true) {
cout << "Enter a phone number (or leave blank to finish): ";
string number;
getline(cin, number);
if (number.empty()) {
break;
}

tutorial::Person::PhoneNumber* phone_number = person->add_phone();
phone_number->set_number(number);

cout << "Is this a mobile, home, or work phone? ";
string type;
getline(cin, type);
if (type == "mobile") {
phone_number->set_type(tutorial::Person::MOBILE);
} else if (type == "home") {
phone_number->set_type(tutorial::Person::HOME);
} else if (type == "work") {
phone_number->set_type(tutorial::Person::WORK);
} else {
cout << "Unknown phone type. Using default." << endl;
}
}
}

// Main function: Reads the entire address book from a file,
// adds one person based on user input, then writes it back out to the same
// file.
int main(int argc, char* argv[]) {
// Verify that the version of the library that we linked against is
// compatible with the version of the headers we compiled against.
GOOGLE_PROTOBUF_VERIFY_VERSION;

if (argc != 2) {
cerr << "Usage: " << argv[0] << " ADDRESS_BOOK_FILE" << endl;
return -1;
}

tutorial::AddressBook address_book;

{
// Read the existing address book.
fstream input(argv[1], ios::in | ios::binary);
if (!input) {
cout << argv[1] << ": File not found. Creating a new file." << endl;
} else if (!address_book.ParseFromIstream(&input)) {
cerr << "Failed to parse address book." << endl;
return -1;
}
}

// Add an address.
PromptForAddress(address_book.add_person());

{
// Write the new address book back to disk.
fstream output(argv[1], ios::out | ios::trunc | ios::binary);
if (!address_book.SerializeToOstream(&output)) {
cerr << "Failed to write address book." << endl;
return -1;
}
}

// Optional: Delete all global objects allocated by libprotobuf.
google::protobuf::ShutdownProtobufLibrary();

return 0;
}

Notice the GOOGLE_PROTOBUF_VERIFY_VERSION macro. It is good practice – though not strictly necessary – to execute this macro before using the C++ Protocol Buffer library. It verifies that you have not accidentally linked against a version of the library which is incompatible with the version of the headers you compiled with. If a version mismatch is detected, the program will abort. Note that every .pb.cc file automatically invokes this macro on startup.

注意GOOGLE_PROTOBUF_VERIFY_VERSION宏。你最好像这样——尽管这不是严格要求的——在使用C++ Protocol Buffer库之前执行该宏。它会检查你是不是在无意中链接到了与你使用的头文件不兼容的protocol buffer库。如果检测到了不匹配情况，程序会中止运行下去。注意：每一个.pb.cc文件在开始的时候都会自动调用该宏。

文章来源：http://www.codelast.com/

Also notice the call to ShutdownProtobufLibrary() at the end of the program. All this does is delete any global objects that were allocated by the Protocol Buffer library. This is unnecessary for most programs, since the process is just going to exit anyway and the OS will take care of reclaiming all of its memory. However, if you use a memory leak checker that requires that every last object be freed, or if you are writing a library which may be loaded and unloaded multiple times by a single process, then you may want to force Protocol Buffers to clean up everything.

另外还需要注意的是程序结尾处调用的ShutdownProtobufLibrary()函数。该函数所做的所有工作就是删除由Protocol Buffer库分配的全局对象。在大多数程序中，这都是没有必要的，因为进程一退出，操作系统就回收了它的内存。然而，如果你使用了内存检查工具（译者注：例如valgrind）来检查你的程序的话（内存检查工具要求每一个对象最后都要被释放），或者你写了一个可能会在一个进程中多次被加载、卸载的库，那么你可能就需要强制Protocol Buffer来清理一切了。

Reading A Message 读消息

Of course, an address book wouldn't be much use if you couldn't get any information out of it! This example reads the file created by the above example and prints all the information in it.

当然，如果你不能从一个address book中取出信息的话，那么它也就没什么用了！下面的例子展示了如何读取上面的程序创建的文件，并将读到的所有信息打印出来。

#include
#include
#include
#include "addressbook.pb.h"
using namespace std;

// Iterates though all people in the AddressBook and prints info about them.
void ListPeople(const tutorial::AddressBook& address_book) {
for (int i = 0; i < address_book.person_size(); i++) {
const tutorial::Person& person = address_book.person(i);

cout << "Person ID: " << person.id() << endl;
cout << " Name: " << person.name() << endl;
if (person.has_email()) {
cout << " E-mail address: " << person.email() << endl;
}

for (int j = 0; j < person.phone_size(); j++) {
const tutorial::Person::PhoneNumber& phone_number = person.phone(j);

switch (phone_number.type()) {
case tutorial::Person::MOBILE:
cout << " Mobile phone #: ";
break;
case tutorial::Person::HOME:
cout << " Home phone #: ";
break;
case tutorial::Person::WORK:
cout << " Work phone #: ";
break;
}
cout << phone_number.number() << endl;
}
}
}

// Main function: Reads the entire address book from a file and prints all
// the information inside.
int main(int argc, char* argv[]) {
// Verify that the version of the library that we linked against is
// compatible with the version of the headers we compiled against.
GOOGLE_PROTOBUF_VERIFY_VERSION;

if (argc != 2) {
cerr << "Usage: " << argv[0] << " ADDRESS_BOOK_FILE" << endl;
return -1;
}

tutorial::AddressBook address_book;

{
// Read the existing address book.
fstream input(argv[1], ios::in | ios::binary);
if (!address_book.ParseFromIstream(&input)) {
cerr << "Failed to parse address book." << endl;
return -1;
}
}

ListPeople(address_book);

// Optional: Delete all global objects allocated by libprotobuf.
google::protobuf::ShutdownProtobufLibrary();

return 0;
}

Extending a Protocol Buffer 扩展一个protocol buffer

Sooner or later after you release the code that uses your protocol buffer, you will undoubtedly want to "improve" the protocol buffer's definition. If you want your new buffers to be backwards-compatible, and your old buffers to be forward-compatible – and you almost certainly do want this – then there are some rules you need to follow. In the new version of the protocol buffer:

· you must not change the tag numbers of any existing fields.

· you must not add or delete any required fields.

· you may delete optional or repeated fields.

· you may add new optional or repeated fields but you must use fresh tag numbers (i.e. tag numbers that were never used in this protocol buffer, not even by deleted fields).

(There are some exceptions to these rules, but they are rarely used.)

If you follow these rules, old code will happily read new messages and simply ignore any new fields. To the old code, optional fields that were deleted will simply have their default value, and deleted repeated fields will be empty. New code will also transparently read old messages. However, keep in mind that new optional fields will not be present in old messages, so you will need to either check explicitly whether they're set with has_, or provide a reasonable default value in your .proto file with [default = value] after the tag number. If the default value is not specified for an optional element, a type-specific default value is used instead: for strings, the default value is the empty string. For booleans, the default value is false. For numeric types, the default value is zero. Note also that if you added a new repeated field, your new code will not be able to tell whether it was left empty (by new code) or never set at all (by old code) since there is no has_ flag for it.

无论或早或晚，在你放出你那使用protocol buffer的代码之后，你必定会想“改进”protocol buffer的定义。如果你想让你的新buffer向后兼容（backwards-compatible），并且旧的buffer能够向前兼容（forward-compatible）——你一定希望如此——那么你在新的protocol buffer中就要遵守其他的一些规则了：

l 对已存在的任何字段，你都不能更改其标识（tag）号。

l 你绝对不能添加或删除任何required的字段。

l 你可以添加新的optional或repeated的字段，但是你必须使用新的标识（tag）号（例如，在这个protocol buffer中从未使用过的标识号——甚至于已经被删除过的字段使用过的标识号也不行）。

（有一些例外情况，但是它们很少使用。）

如果你遵守这些规则，老的代码将能很好地解析新的消息（message），并忽略掉任何新的字段。对老代码来说，已经被删除的optional字段将被赋予默认值，已被删除的repeated字段将是空的。新的代码也能够透明地读取旧的消息。但是，请牢记心中：新的optional字段将不会出现在旧的消息中，所以你要么需要显式地检查它们是否由has_前缀的函数置（set）了值，要么在你的.proto文件中，在标识（tag）号的后面用[default = value]提供一个合理的默认值。如果没有为一个optional项指定默认值，那么就会使用与特定类型相关的默认值：对string来说，默认值是空字符串。对boolean来说，默认值是false。对数值类型来说，默认值是0。还要注意：如果你添加了一个新的repeated字段，你的新代码将无法告诉你它是否被留空了（被新代码），或者是否从未被置（set）值（被旧代码），这是因为它没有has_标志。

Optimization Tips 优化小技巧

The C++ Protocol Buffers library is extremely heavily optimized. However, proper usage can improve performance even more. Here are some tips for squeezing every last drop of speed out of the library:

· Reuse message objects when possible. Messages try to keep around any memory they allocate for reuse, even when they are cleared. Thus, if you are handling many messages with the same type and similar structure in succession, it is a good idea to reuse the same message object each time to take load off the memory allocator. However, objects can become bloated over time, especially if your messages vary in "shape" or if you occasionally construct a message that is much larger than usual. You should monitor the sizes of your message objects by calling the SpaceUsed method and delete them once they get too big.

· Your system's memory allocator may not be well-optimized for allocating lots of small objects from multiple threads. Try using Google's tcmalloc instead.

Protocol Buffer 的C++库已经做了极度优化。但是，正确的使用方法仍然会提高很多性能。下面是一些小技巧，用来提升protocol buffer库的最后一丝速度能力：

l 如果有可能，重复利用消息（message）对象。即使被清除掉，消息（message）对象也会尽量保存所有被分配来重用的内存。这样的话，如果你正在处理很多类型相同的消息以及一系列相似的结构，有一个好办法就是重复使用同一个消息（message）对象，从而使内存分配的压力减小一些。然而，随着时间的流逝，对象占用的内存也有可能变得越来越大，尤其是当你的消息尺寸（译者注：各消息内容不同，有些消息内容多一些，有些消息内容少一些）不同的时候，或者你偶尔创建了一个比平常大很多的消息（message）的时候。你应该自己监测消息（message）对象的大小——通过调用SpaceUsed函数——并在它太大的时候删除它。

l 在多线程中分配大量小对象的内存的时候，你的操作系统的内存分配器可能优化得不够好。在这种情况下，你可以尝试用一下Google's tcmalloc。

Advanced Usage 高级使用

Protocol buffers have uses that go beyond simple accessors and serialization. Be sure to explore the C++ API reference to see what else you can do with them.

One key feature provided by protocol message classes is reflection. You can iterate over the fields of a message and manipulate their values without writing your code against any specific message type. One very useful way to use reflection is for converting protocol messages to and from other encodings, such as XML or JSON. A more advanced use of reflection might be to find differences between two messages of the same type, or to develop a sort of "regular expressions for protocol messages" in which you can write expressions that match certain message contents. If you use your imagination, it's possible to apply Protocol Buffers to a much wider range of problems than you might initially expect!

Reflection is provided by the Message::Reflection interface.

Protocol Buffers的作用绝不仅仅是简单的数据存取以及序列化。请阅读C++ API reference全文来看看你还能用它来做什么。

protocol消息类所提供的一个关键特性就是反射。你不需要编写针对一个特殊的消息（message）类型的代码，就可以遍历一个消息的字段，并操纵它们的值，就像XML和JSON一样。“反射”的一个更高级的用法可能就是可以找出两个相同类型的消息之间的区别，或者开发某种“协议消息的正则表达式”，利用正则表达式，你可以对某种消息内容进行匹配。只要你发挥你的想像力，就有可能将Protocol Buffers应用到一个更广泛的、你可能一开始就期望解决的问题范围上。

“反射”是由Message::Reflection interface提供的。

文章来源：https://www.codelast.com/
➤➤ 版权声明 ➤➤
转载需注明出处：codelast.com
感谢关注我的微信公众号（微信扫一扫）：