simonkuang/reveal.html

## reveal.html
<!doctype html>
<html>
	<head>
		<meta charset="utf-8">
		<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

		<title>reveal.js</title>

		<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/dist/reset.css">
		<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/dist/reveal.css">
		<!-- <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/dist/theme/solarized.css"> -->
		<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/dist/theme/sky.css">

		<!-- Theme used for syntax highlighted code -->
		<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/plugin/highlight/monokai.css">
	</head>
	<body>
		<!-- <div class="reveal">
			<div class="slides">
				<section>Slide 1</section>
				<section>Slide 2</section>
			</div>
		</div> -->
		<div class="reveal">
			<div class="slides">
				<section data-markdown>
					<textarea data-template>

# Protobuf 最佳实践

### 旷淇元

---

protobuf 遵从一系列最佳实践。

这些实践来自 Google 和其它重度使用 pb 的团队。

遵从这些实践可以避免踩坑，节省项目时间。

要站在巨人肩膀上成长。

---

## <sup>§</sup>01 - Message

1. Message 就是 Entity，是可以在 RPC 传输的单元。

2. Message 代表 Entity 时，必有逻辑主键。逻辑主键由业务保证有效性的。

3. 遵循一个逻辑 Entity 一个 proto 文件的方式组织文件。proto 文件划分和 Message 无关。

4. Protobuf 的设计哲学之一，是避免二义性。举例：包裹 Message A 和 B 的数组需要分别单独设计。

---

## <sup>§</sup>01 - Message

1. fields 的编号遵从下列规范。

	- 1～100，通用属性。例如：1 留给逻辑主键。
	- 101～1000，业务属性。
	- 1000～+∞，保留。
	- 字段顺序尽量按照序号从低到高排列。
	- 一定是按逻辑分段号。

2. 所有 fields 都用 `optional` 修饰符，禁止使用 `required`。数据设计上的向前兼容策略。

5. Message 字段只增不减不改。

6. 所有已经分配的字段名和序号，不可复用到别的含义。

7. 所以字段起名时，应当适度完善，避免通用含义的单词，例如：`status`。

---

# <sup>§</sup>02 - Message 嵌套

1. message 允许嵌套。如果复用性比较弱，或者从属关系比较强，应当选择嵌套。

2. 编译后的代码中，嵌套的 message 只是增加了一层命名空间，访问不受限制。

3. 选择 flat 结构还是嵌套子 message，应当从语义上判断，而非能否复用。

> 举个例子：找活领域中，当前所在地的信息，是应当作为子 message 还是在找活 message 中多几个字段？

> 根据情况，当前所在地信息是一组信息，有经纬度坐标，逆地理编码后的详细地址，省市区编码等，这是一组逻辑上相互依赖的整体，最好作为嵌套子 message。

> 从复用上讲，招工信息中的当前所在地也有这样一组信息，是否可以复用？建议不复用。二者是形式上相同，产品概念上是完全独立的两个事物。

					</textarea>
				</section>
			</div>
		</div>

		<script src="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/dist/reveal.js"></script>
		<script src="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/plugin/notes/notes.js"></script>
		<script src="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/plugin/markdown/markdown.js"></script>
		<script src="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/plugin/highlight/highlight.js"></script>
		<script>
			// More info about initialization & config:
			// - https://revealjs.com/initialization/
			// - https://revealjs.com/config/
			Reveal.initialize({
				hash: true,

				// Learn about plugins: https://revealjs.com/plugins/
				plugins: [ RevealMarkdown, RevealHighlight, RevealNotes ],

				markdown: {
					smartypants: true
				}
			});
		</script>
	</body>
</html>
	<!doctype html>
	<html>
	<head>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

	<title>reveal.js</title>

	<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/dist/reset.css">
	<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/dist/reveal.css">
	<!-- <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/dist/theme/solarized.css"> -->
	<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/dist/theme/sky.css">

	<!-- Theme used for syntax highlighted code -->
	<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/plugin/highlight/monokai.css">
	</head>
	<body>
	<!-- <div class="reveal">
	<div class="slides">
	<section>Slide 1</section>
	<section>Slide 2</section>
	</div>
	</div> -->
	<div class="reveal">
	<div class="slides">
	<section data-markdown>
	<textarea data-template>

	# Protobuf 最佳实践

	### 旷淇元

	---

	protobuf 遵从一系列最佳实践。

	这些实践来自 Google 和其它重度使用 pb 的团队。

	遵从这些实践可以避免踩坑，节省项目时间。

	要站在巨人肩膀上成长。

	---

	## <sup>§</sup>01 - Message

	1. Message 就是 Entity，是可以在 RPC 传输的单元。

	2. Message 代表 Entity 时，必有逻辑主键。逻辑主键由业务保证有效性的。

	3. 遵循一个逻辑 Entity 一个 proto 文件的方式组织文件。proto 文件划分和 Message 无关。

	4. Protobuf 的设计哲学之一，是避免二义性。举例：包裹 Message A 和 B 的数组需要分别单独设计。

	---

	## <sup>§</sup>01 - Message

	1. fields 的编号遵从下列规范。

	- 1～100，通用属性。例如：1 留给逻辑主键。
	- 101～1000，业务属性。
	- 1000～+∞，保留。
	- 字段顺序尽量按照序号从低到高排列。
	- 一定是按逻辑分段号。

	2. 所有 fields 都用 `optional` 修饰符，禁止使用 `required`。数据设计上的向前兼容策略。

	5. Message 字段只增不减不改。

	6. 所有已经分配的字段名和序号，不可复用到别的含义。

	7. 所以字段起名时，应当适度完善，避免通用含义的单词，例如：`status`。

	---

	# <sup>§</sup>02 - Message 嵌套

	1. message 允许嵌套。如果复用性比较弱，或者从属关系比较强，应当选择嵌套。

	2. 编译后的代码中，嵌套的 message 只是增加了一层命名空间，访问不受限制。

	3. 选择 flat 结构还是嵌套子 message，应当从语义上判断，而非能否复用。

	> 举个例子：找活领域中，当前所在地的信息，是应当作为子 message 还是在找活 message 中多几个字段？

	> 根据情况，当前所在地信息是一组信息，有经纬度坐标，逆地理编码后的详细地址，省市区编码等，这是一组逻辑上相互依赖的整体，最好作为嵌套子 message。

	> 从复用上讲，招工信息中的当前所在地也有这样一组信息，是否可以复用？建议不复用。二者是形式上相同，产品概念上是完全独立的两个事物。

	</textarea>
	</section>
	</div>
	</div>

	<script src="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/dist/reveal.js"></script>
	<script src="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/plugin/notes/notes.js"></script>
	<script src="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/plugin/markdown/markdown.js"></script>
	<script src="https://cdn.jsdelivr.net/gh/hakimel/reveal.js@master/plugin/highlight/highlight.js"></script>
	<script>
	// More info about initialization & config:
	// - https://revealjs.com/initialization/
	// - https://revealjs.com/config/
	Reveal.initialize({
	hash: true,

	// Learn about plugins: https://revealjs.com/plugins/
	plugins: [ RevealMarkdown, RevealHighlight, RevealNotes ],

	markdown: {
	smartypants: true
	}
	});
	</script>
	</body>
	</html>