docs: update communication.md

zhangyuang · zhangyuang · Apr 25, 2021 · Apr 6, 2021 · Apr 6, 2021 · Apr 12, 2021
commit bfae65e34706dc363bce1c4aa9a414a266ee44f7
diff --git a/docs/web/markdown/features/csr.md b/docs/web/markdown/features/csr.md
@@ -1,56 +1,65 @@
 # 渲染降级
- 框架支持渲染降级，服务端渲染可以一键降级为客户端渲染
-
+
+相比于其他框架的功能。本框架还额外具备一键从 `服务端渲染` 降级为 `客户端渲染` 的功能
 ## 服务端和客户端渲染
 
- ### 区别
+下面让我们来看看  `服务端渲染` 和 `客户端渲染` 有什么区别
+### 区别
 
-` 客户端渲染（client-side Renderingende)`, HTML 仅仅作为静态文件，客户端在请求时，服务端不做任何处理，直接以原文件的形式返回给客户端客户端，然后根据 HTML 上的 JavaScript，生成 DOM 插入 HTML
+`客户端渲染（client-side Renderingende)`, `HTML` 仅仅作为静态估价，客户端在请求时，服务端不做任何处理，直接以原文件的形式返回给客户端客户端，然后根据 `HTML` 上的 `JavaScript`，生成 `DOM` 插入 HTML
 
- `服务端渲染（Server-Side Rendering`）,在浏览器请求页面URL的时候，服务端将我们需要的 HTML 文本组装好，并返回给浏览器，这个 HTML 文本被浏览器解析之后，不需要经过 JavaScript 脚本的执行，即可直接构建出希望的 DOM 树并展示到页面中。
+ `服务端渲染（Server-Side Rendering`）,在浏览器请求页面URL的时候，服务端将我们需要的 `HTML` 文本组装好，并返回给浏览器，这个 `HTML` 文本被浏览器解析之后，不需要经过 `JavaScript` 脚本的执行，即可直接构建出希望的 DOM 树并展示到页面中。
 
- 客户端渲染和服务器端渲染的最重要的区别就是究竟是谁来完成 HTML 文件的完整拼接，如果是在服务器端完成的，然后返回给客户端，就是服务器端渲染，而如果是前端做了更多的工作完成了 HTML 的拼接，则就是客户端渲染。
+客户端渲染和服务器端渲染的最重要的区别就是究竟是谁来完成 `HTML` 文件的完整拼接，如果是在服务器端完成的，然后返回给客户端，就是服务器端渲染，而如果是客户端端做了更多的工作完成了 `HTML` 的拼接，则就是客户端渲染。
 
 ![](/images/ssr&csr.png)
 
+> 注: 在不同的多渲染模式下本框架的渲染方式获取数据的时机不同，具体可查看 [数据获取](./docs/features$fetch)
 
-> 注: 本框架的渲染方式获取数据的方式不同，具体可查看 [服务端渲染](/docs/features$fetch#%E6%9C%8D%E5%8A%A1%E7%AB%AF%E6%B8%B2%E6%9F%93%E6%A8%A1%E5%BC%8F) 和 [客户端渲染](docs/features$fetch#客户端渲染模式)
+### 服务端渲染优势
 
- ### 服务端渲染优势
-  - **利于SEO** 
+- SEO
 
-  其实就是有利于爬虫来爬你的页面，然后在别人使用搜索引擎搜索相关的内容时，你的网页排行能靠得更前，这样你的流量就有越高
+有利于爬虫来爬你的页面，然后在搜索引擎搜索相关的内容时，你的网页排行能靠得更前，这样你的流量就有越高
 
-  - **白屏时间更短**
+- 白屏时间更短
 
-  相对于客户端渲染，服务端渲染在浏览器请求 URL 之后已经得到了一个带有数据的 HTML 文本，浏览器只需要解析 HTML，直接构建 DOM 树就可以。而客户端渲染，需要先得到一个空的 HTML 页面，这个时候页面已经进入白屏，之后还需要经过加载并执行 JavaScript、请求后端服务器获取数据、JavaScript 渲染页面几个过程才可以看到最后的页面。特别是在复杂应用中，由于需要加载 JavaScript 脚本，越是复杂的应用，需要加载的 JavaScript 脚本就越多、越大，这会导致应用的首屏加载时间非常长，进而降低了体验感。
+相对于客户端渲染，服务端渲染在浏览器请求 URL 之后已经得到了一个带有数据的 HTML 文本，浏览器只需要解析 HTML，直接构建 DOM 树就可以。而客户端渲染，需要先得到一个空的 HTML 页面，这个时候页面已经进入白屏，之后还需要经过加载并执行 JavaScript、请求后端服务器获取数据、JavaScript 渲染页面几个过程才可以看到最后的页面。特别是在复杂应用中，由于需要加载 JavaScript 脚本，越是复杂的应用，需要加载的 JavaScript 脚本就越多、越大，这会导致应用的首屏加载时间非常长，进而降低了体验感。
 
-- **无需占用客户端资源**
-即解析模板的工作完全交由后端来做，客户端只要解析标准的 HTML 页面即可，这样对于客户端的资源占用更少，尤其是移动端，也可以更省电
+### 客户端渲染优势
 
+- 更少的服务器负载
 
-### 客户端渲染优势
-- **前后端分离**
-前端专注于前端UI，后端专注于 Api 开发，且前端有更多的选择性，而不需要遵循后端特定的模板
-- **体验更好**
-比如，我们将网站做成SPA或者部分内容做成SPA，这样，尤其是移动端，可以使体验更接近于原生app
+由于服务端只需要返回最简单的页面骨架，故服务端的压力会更小，可以承担更多的 `QPS`
+
+- 更少的心智负担
+
+编写一个成熟的服务端渲染应用对开发者的心智要求以及能力要求无疑是更高的
 
+## 如何降级为客户端渲染
 
-## 启用渲染降级
+在 `ssr` 框架中我们提供了多种降级到客户端渲染的方案
+### URL Query 参数
 
-### URL 添加 query 参数
- 框架启动的时候默认使用服务端渲染方式，如果想要启用渲染降级，只需要在请求 URL 后面添加 query 参数`?csr=1`或者`?csr=true`；举个栗子， [http://ssr-fc.com](http://ssr-fc.com/) 网站默认启用了服务端渲染,可以明显感受到页面秒开，没有白屏等待时间，而添加参数后 [http://ssr-fc.com?csr=true](http://ssr-fc.com?csr=true)，也就是启动客户端渲染之后再打开网站，可以明显感受到有一定的白屏时间，具体表现为有一个页面闪烁的过程
+框架启动的时候默认使用服务端渲染方式，如果想要启用渲染降级，只需要在请求 `URL` 后面添加 `query` 参数 `?csr=xxx` 
+
+举个栗子， [http://ssr-fc.com](http://ssr-fc.com/) 网站默认启用了服务端渲染,可以明显感受到页面秒开，没有白屏等待时间，而添加参数后 [http://ssr-fc.com?csr=true](http://ssr-fc.com?csr=true)，也就是启动客户端渲染之后再打开网站，可以明显感受到有一定的白屏时间，具体表现为有一个页面闪烁的过程。
+
+此方案适用于开发者本地进行测试
 
 ### config.js 配置
- 服务发布的时候支持两种模式，默认是`mode: 'ssr'`模式，你也可以通过 config.js 中的 `mode: 'csr'` 将csr设置默认渲染模式。
+
+服务发布的时候支持两种模式，默认是 `mode: 'ssr'` 模式，你也可以通过 [应用配置](./api$config) 中的 `mode: 'csr'` 将 `csr` 设置默认渲染模式。
 
 ### 通过 core 模块提供的 render 方法降级
+
 [ssr-core-react](https://github.com/ykfe/ssr/blob/dev/packages/core-react/src/render.ts) 和 [ssr-core-vue](https://github.com/ykfe/ssr/blob/dev/packages/core-vue3/src/index.ts) (vue3)模块均支持该方式
-在应用执行出错 `catch` 到 `error` 的时候降级为客户端渲染。也可根据具体的业务逻辑，在适当的时候通过该方式降级 `csr` 模式
+
+在应用执行出错 `catch` 到 `error` 的时候降级为客户端渲染。也可根据具体的业务逻辑，由开发者自行决定在适当的时候通过该方式降级 `csr` 模式。
 
 下面可以看到 `ssr-core-react` 模块的例子
 
-```
+```js
 import { render } from 'ssr-core-react'
 
 try {
@@ -63,5 +72,30 @@ try {
   return htmlStr
 }
 ```
-当 `server`出现问题的时候，这样的容灾做法是比较好的。更好的做法是网关层面，配置容灾，将请求打到 `cdn` 上。
 
+当 `server` 出现问题的时候，这样的容灾做法是比较好的。更好的做法是网关层面，配置容灾，将请求打到 `cdn` 上。
+
+## 实现机制
+
+在 `ssr` 框架中实现渲染降级这个功能的原理是十分简单的。如果你已经使用本框架进行了项目开发，那么你应该会发现我们没有传统的 `index.html` 文件，也没有任何模版引擎。我们的 `html` 页面布局完全是通过 `JSX` 或是 `Vue SFC` 来渲染出来的。
+
+在看完上述的 `服务端渲染` 应用和 `客户端渲染` 应用的区别后，我们可以发现在降级为客户端渲染后，我们无需在服务端渲染页面组件以及数据的获取。而仅仅渲染一个空的 `html` 骨架即可。`React` 场景通过代码来表示如下
+
+```js
+const layoutFetchData = (!isCsr && layoutFetch) ? await layoutFetch(ctx) : null
+const fetchData = (!isCsr && routeItem.fetch) ? await routeItem.fetch(ctx) : null
+
+return (
+  <Layout ctx={ctx} config={config} staticList={staticList} viteReactScript={viteReactScript}>
+    {isCsr ? <></> : <Component />}
+  </Layout>
+)
+```
+
+可以非常轻易的看出实现原理。同样在 `Vue` 场景我们通过 `slot` 实现了类似的功能
+
+## 注意事项
+
+通过前端框架来渲染 `html` 标签并不是这些框架所推荐的。我们可以看到代码中使用了诸如 `dangerouslySetInnerHTML` 这样的写法，来提醒我们不要这么做。因为这样很容易被恶意脚本注入导致 [xss](https://developer.mozilla.org/zh-CN/docs/Glossary/Cross-site_scripting)。所以我们必须严格把控这一部分的渲染内容，绝不能出现用户可以控制的部分。
+
+在注入页面数据时，我们会使用 [serialize-javascript](https://www.npmjs.com/package/serialize-javascript) 来将 `window.__INITIAL_DATA__` 序列化。但是在 `html` 头部的其他部分内容注入，特别是 `script` 标签相关内容需要开发者密切注意。
diff --git a/docs/web/markdown/why.md b/docs/web/markdown/why.md
@@ -49,9 +49,9 @@
 | 类型友好，全面拥抱 TS                                | 🚀   |
 | 支持无缝接入 [antd](https://github.com/ant-design/ant-design) [vant](https://vant-contrib.gitee.io/vant/#/) 无需修改任何配置                             | 🚀   |
 | 支持使用 less 作为 css 预处理器                                                | 🚀   |
-| 实现 React/Vue SSR 场景下的[优秀代码分割方案](https://zhuanlan.zhihu.com/p/343743374) 首屏性能做到极致                  |    🚀  |
-| React 场景下使用 useContext + useReducer 实现极简的[数据管理](#React跨组件通信)方案，摒弃传统的 redux/dva 等数据管理方案                         |    🚀  |
-| Vue3 场景提供 [Provide/Inject](#provideinject代替vuex) 代替 Vuex 进行跨组件通信                     |    🚀  |
+| 实现 React/Vue SSR 场景下的 [优秀代码分割方案](https://zhuanlan.zhihu.com/p/343743374) 首屏性能做到极致                  |    🚀  |
+| React 场景下使用 useContext + useReducer 实现极简的[数据管理](./features$communication#React%20场景)方案，摒弃传统的 `redux/dva` 等数据管理方案                         |    🚀  |
+| Vue3 场景提供 [Provide/Inject](./features$communication#Vue%20场景解决方案) 代替 Vuex 进行跨组件通信                     |    🚀  |
 | 支持在阿里云 [云平台](https://zhuanlan.zhihu.com/p/139210473)创建使用          | 🚀     |
 | ssr deploy 一键部署到[阿里云](https://www.aliyun.com/)平台           | 🚀   |
 | ssr deploy --tencent 无需修改任何配置一键部署到[腾讯云](https://cloud.tencent.com/)平台                                   | 🚀                                |