Skip to content

Commit

Permalink
add a new section(both in English and Chinese) named[Purpose] in READ…
Browse files Browse the repository at this point in the history
…ME.md illustrating why we need a Chinese version spec

fix invalid links in README.md
fix invalid links in spec_CN.md
fix invalid links in primer_CN.md

Signed-off-by: JieDing <dingjwilliams@gmail.com>
  • Loading branch information
JieDing committed Nov 12, 2021
1 parent b83625b commit 6803020
Show file tree
Hide file tree
Showing 3 changed files with 31 additions and 25 deletions.
22 changes: 14 additions & 8 deletions Chinese-Manual/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,22 @@

![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png)

Declaration: This manual aims to provide a fast and brief introduction of CloudEvents
## Purpose/规范目的

This manual aims to provide a fast and brief introduction of CloudEvents
in Chinese for people who are new to CloudEvents.
Most of the content is translated from the original English version.
It is strongly recommended to read the English version if you find anything lost in translation.

这份中文规范是为了让更多刚接触CloudEvents的中国开发者,能在最短时间内对CloudEvents有一个全局的认识。
本文档中的大多内容翻译自英文版的CloudEvents规范,如果你在阅读中发现一些难以理解的翻译,请参阅英文版文档。

## CloudEvents

事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。

对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。它同样限制了那些用来帮助事件数据完成
跨环境传输的库(如SDKs),工具(如事件路由器)和基础设施(如事件追踪系统)的发展。总体来看,这种匮乏严重阻碍了事件数据的
可移植性和生产力。
跨环境传输的库(如SDKs),工具(如事件路由器)和基础设施(如事件追踪系统)的发展。总体来看,这种匮乏严重阻碍了事件数据的可移植性和生产力。

CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。

Expand Down Expand Up @@ -56,7 +62,7 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent

## SDKs

除了上述文档,我们还提供了[SDK 提议](SDK.md)以及一些编程语言的SDK:
除了上述文档,我们还提供了[SDK 提议](../SDK.md)以及一些编程语言的SDK:

- [CSharp](https://github.com/cloudevents/sdk-csharp)
- [Go](https://github.com/cloudevents/sdk-go)
Expand All @@ -72,11 +78,11 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent
在社区里,你可以了解到更多致力于搭建一个动态、云原生的生态系统的成员和组织。
他们不断尝试提升现有系统和CloudEvents间的互操作性和兼容性。

- 我们的 [管理](community/GOVERNANCE.md) 文档。
- 如何通过 issues 和 PR 为我们做[贡献](community/CONTRIBUTING.md)
- [贡献者](community/contributors.md):
- 我们的 [管理](../community/GOVERNANCE.md) 文档。
- 如何通过 issues 和 PR 为我们做[贡献](../community/CONTRIBUTING.md)
- [贡献者](../community/contributors.md):
是指那些帮助我们制定规范或是积极活跃在CloudEvents规范相关工作的成员和组织。
- [Demos & open source](community/README.md)
- [Demos & open source](../community/README.md)
-- 如果你希望向我们分享关于你对CloudEvents的使用,请通过提交PR让我们看到。

## 步骤
Expand Down
22 changes: 11 additions & 11 deletions Chinese-Manual/primer_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ Serverless相关技术并为CNCF推荐相关领域的未来发展计划的。工

为了更好地解释一个系统如何使用CloudEvents,下图展示了一个从事件源生产的事件是如何触发一个行为的。

![alt text](source-event-action.png "A box representing the source with
![alt text](../source-event-action.png "A box representing the source with
arrow pointing to a box representing the action. The arrow is annotated with
'e' for event and 'protocol'.")

Expand Down Expand Up @@ -115,7 +115,7 @@ CloudEvents的核心规范中定义了一组称之为属性的元数据,
CloudEvents 规范不应包括协议级路由信息(例如,将事件发送到的目标的URL)。
经过深思熟虑,工作组得出的结论是,CloudEvents规范中不需要路由信息:
因为任何现有的协议(例如 HTTP、MQTT、XMPP 或 Pub/Sub 总线)都已经定义了路由语义。
例如,CloudEvents [HTTP 绑定](http-protocol-binding.md) 规定了头部和请求正文内容。
例如,CloudEvents [HTTP 绑定](../http-protocol-binding.md) 规定了头部和请求正文内容。
CloudEvents 不需要在规范中包含目标 URL 即可与 HTTP 兼容;HTTP 规范已经在
[请求行](https://tools.ietf.org/html/rfc2616#section-5.1) 中包含了所需的目标URL。

Expand Down Expand Up @@ -148,15 +148,15 @@ CloudEvents 规范集定义了四种有助于形成分层架构模型的不同
该模型由属性(键值对)和构成 CloudEvent 的相关规则组成。
2. [扩展属性](./spec_CN.md#扩展上下文属性)
添加了特定于用例且可能重叠的扩展属性集和相关规则,如支持不同的追踪标准的规则。
3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式,
3. 事件格式编码,如 [JSON](../json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式,
以将其映射到应用程序协议的头部和负载元素。
4. 协议绑定, 如. [HTTP协议绑定](http-protocol-binding.md),
4. 协议绑定, 如. [HTTP协议绑定](../http-protocol-binding.md),
在HTTP to HTTP的情况下,
定义了 CloudEvent 如何绑定到应用程序协议的传输层 。
协议绑定不限制传输层的使用方式,这意味着 HTTP绑定可用于任何 HTTP方法以及请求和响应消息。

为了确保更广泛的互操作性,CloudEvents规范集为使用专有应用协议的事件传输提供了特定约束。
[HTTP Webhook](http-webhook.md)规范并非特定于 CloudEvents,
[HTTP Webhook](../http-webhook.md)规范并非特定于 CloudEvents,
而是可用于将任何类型的单向事件和通知发布到符合标准的 HTTP 端点。
但是,由于其他地方缺乏此类规范,因此 CloudEvents 需要对其进行定义。

Expand Down Expand Up @@ -266,7 +266,7 @@ CloudEvents 规范不强制要求要使用的特定模式,甚至不要求必

工作组考虑到某些属性不够常见而不能归入上述两个类别,
但此类属性的良好定义仍会使系统间的互操作性级别受益,
因此将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中,
因此将这些属性放入了“扩展”类别并记录在[扩展文档](../documented-extensions.md)中,
本规范定义了这些扩展属性在 CloudEvent 中的显示方式。

在确定提议的属性属于哪个类别时,
Expand All @@ -280,7 +280,7 @@ CloudEvent 规范的扩展属性是需要包含的附加元数据,它们能确

扩展属性应保持最少,以确保 CloudEvent 可以正确序列化和传输。
事件生产者应该考虑在向 CloudEvent 添加扩展时可能遇到的技术限制。
例如,[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode)
例如,[HTTP Binary Mode](../http-protocol-binding.md#31-binary-content-mode)
使用 HTTP 头来传输元数据;
大多数 HTTP 服务器会拒绝包含过多 HTTP 头部数据的请求,要求限制其低至 8kb。
因此,扩展属性的大小和数量应保持最小。
Expand All @@ -290,8 +290,8 @@ CloudEvent 规范的扩展属性是需要包含的附加元数据,它们能确

### JSON 扩展

[CloudEvents JSON 事件格式](json-format.md)
[属性](json-format.md#2-attributes)部分所述,
[CloudEvents JSON 事件格式](../json-format.md)
[属性](../json-format.md#2-attributes)部分所述,
CloudEvent 扩展属性与已定义属性(必要属性、可选属性)在序列化时处于同一等级 -
也就是说,它们都是 JSON 对象的顶层属性。
CloudEvent的作者花了很长时间考虑所有选项,并认为这是最好的选择。
Expand Down Expand Up @@ -356,7 +356,7 @@ CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死

可能存在需要创建包含另一个 CloudEvent 的 CloudEvent 的特殊情况。
虽然规范没有明确定义嵌套,但它是可能的。
虽然内部事件将始终以[独立的事件格式](spec_CN.md#数据格式) 编码,
虽然内部事件将始终以[独立的事件格式](spec_CN.md#事件格式) 编码,
但外部事件可能是二进制或结构化模式的。
外部事件的 `datacontenttype` 属性不得设置为 application/cloudevents+json
或任何其它用于表示使用结构化模式的媒体类型。
Expand Down Expand Up @@ -421,7 +421,7 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工
为了鼓励更多人采用 CloudEvents,本仓库将自动收集专有协议和编码。
本仓库的维护人员不负责创建、维护或通知专有规范的维护人员有关专有规范和CloudEvents规范间的偏差。

专有规范将托管在他们自己的仓库或文档站点中,并记录在[专有规范](proprietary-specs.md)
专有规范将托管在他们自己的仓库或文档站点中,并记录在[专有规范](../proprietary-specs.md)
文件中。 专有规范应遵循与核心协议和编码相关的其他规范相同的格式。

专有规范将比核心规范受到更少的审查,并且随着 CloudEvents 规范的发展,
Expand Down
12 changes: 6 additions & 6 deletions Chinese-Manual/spec_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了

事件格式指定如何使用某些编码格式序列化一个 CloudEvent。
支持那些编码且兼容 CloudEvents 的实现必须遵守相应事件格式中指定的编码规则。
所有实现都必须支持 [JSON 格式](json-format.md)
所有实现都必须支持 [JSON 格式](../json-format.md)

有关规范背后的历史、开发和设计原理等更多信息,
请参阅 CloudEvents [入门文档](primer_CN.md)
Expand Down Expand Up @@ -96,7 +96,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了

#### 上下文

上下文环境元数据被封装在[上下文-属性](#上下文-属性)中。
上下文环境元数据被封装在[上下文-属性](#上下文属性)中。
工具和应用程序代码可以使用此信息来识别事件与系统方面或事件与其他事件的关系。

#### 数据
Expand All @@ -107,7 +107,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了
#### 事件格式

一个事件格式会指定如何将 CloudEvent 序列化为字节序列。
独立事件格式(例如 [JSON 格式](json-format.md))指定独立于任何协议或存储介质的序列化。
独立事件格式(例如 [JSON 格式](../json-format.md))指定独立于任何协议或存储介质的序列化。
协议绑定可以定义依赖于协议的格式。

#### 消息
Expand Down Expand Up @@ -293,11 +293,11 @@ CloudEvents 协议绑定或事件格式实现同样必须能够
- 类型: `String` [RFC 2046](https://tools.ietf.org/html/rfc2046)
- 描述: `data`值的内容类型。 此属性使`data`能够承载任何类型的内容,
因此格式和编码可能与所选事件格式的不同。
例如,使用 [JSON envelope](./json-format.md#3-envelope)
例如,使用 [JSON envelope](../json-format.md#3-envelope)
格式呈现的事件可能在数据中携带 XML 的payload,这个属性可以用来通知消费者
设置"application/xml"。
关于`data`内容如何提供不同的`datacontenttype`的值的规则在事件格式规范中定义。
例如,JSON 事件格式定义了 [3.1 节](./json-format.md#31-handling-of-data)中的关系。
例如,JSON 事件格式定义了 [3.1 节](../json-format.md#31-handling-of-data)中的关系。

对于某些二进制模式协议绑定,
此字段直接能映射到相应协议的内容类型的元数据属性上。
Expand Down Expand Up @@ -387,7 +387,7 @@ CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性

扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。
新的扩展定义应该使用一个足够描述性的名称来减少与其他扩展的名称冲突的机会。
特别是,扩展作者应该检查[扩展文件](documented-extensions.md)
特别是,扩展作者应该检查[扩展文件](../documented-extensions.md)
已知的扩展集——不仅是可能的名称冲突,还有相同目的冲突的扩展。

许多协议为发送者提供了包含额外元数据的能力,例如作为 HTTP 头部。
Expand Down

0 comments on commit 6803020

Please sign in to comment.