Retail React App

Retail React App（零售反应应用）是一组示例代码和工具，旨在让您抢先构建基于 API 的网店，并将其在 Managed Runtime（托管运行时）上托管。本架构指南描述 Retail React App 的结构和内容，并强调其灵活的开源基础。

所有 PWA Kit 项目均以相同的文件集开始。在项目开始时，这些文件通过运行脚本生成。（此过程在入门指南中有完整介绍。）

要大致了解 Retail React 应用程序的工作原理，应首先了解其文件结构。以下是新生成项目的所有文件和目录的列表，每个文件和目录都有简要说明。（描述中提到的技术将在本指南后面详细介绍。）

为了自动化日常开发任务，Retail React App 包含几个脚本。使用命令 npm run <SCRIPT_NAME> 从终端运行这些脚本。

以下是所有包含脚本的完整列表以及每个脚本的说明：

名称	说明
`analyze-build`	在生产模式下构建项目并创建两个 webpack-bundle-analyzer 报告。使用报告监控代码捆绑包的大小。
`compile-messages`	将所有本地化消息编译为 AST 格式。
`extract-messages`	自动从 React 组件中提取默认语言环境的消息。
`format`	使用 Prettier 格式化代码。
`lint`	使用 ESlint 查找不一致的代码样式。
`lint:fix`	自动修复 ESlint 错误。
`prod:build`	在生产模式中构建项目。
`push`	将代码捆绑包（生产构建工件）推送到 Managed Runtime。
`save-credentials`	在本地保存 Runtime Admin（运行时管理员）凭据（用于推送命令）。
`start`	启动 SSR 服务器。
`start:inspect`	使用 Node.js 检查器启动 SSR 服务器。
`start:pseudolocale`	使用伪语言环境启动 SSR 服务器。
`test`	使用 Jest 运行单元测试。
`test:lighthouse`	运行 Lighthouse 测试。
`test:max-file-size`	运行捆绑包大小测试。

您的项目带有两个用于质量保证的示例测试套件：使用 Jest 和 React 测试库创建的单元测试。

单元测试及其每个页面组件包含在各自的目录中。

要开始单元测试，请在终端中运行以下命令：

要了解有关测试网店的更多信息，请查看示例测试套件的源代码并浏览 Jest和 React 测试库的文档。

根据 Google 的 Lighthouse 测试套件衡量，Retail React App 从一开始就获得了出色的性能分数。使用以下脚本，我们可以在整个开发过程中轻松监控您的 Lighthouse 分数：

该脚本在您的网店运行 Lighthouse 三次，并将每个类别的中位数分数上传到 Google。然后，Google 使用这些分数来生成报告。脚本在退出之前会输出一个指向报告的链接。

要使用 Salesforce API 访问购物者数据，管理员必须完成设置 API 访问中描述的任务。

Retail React App 中的购物者数据通过构建在 commerce-sdk-isomorphic 客户端之上的类 CommerceAPI 来访问。您可以在 app/commerce-api/index.js 中自定义 CommerceAPI 类，并在 app/api.config.js 中对其进行配置。

CommerceAPI 类会自动注入每个页面的 getProps 方法中。例如，您可以如下从页面组件访问 API 包装程序：

CommerceAPI 包装程序当前为产品、促销、礼券和搜索使用 Commerce API。这些功能中的每一个拥有自己的端点组，这些端点分别记录在B2C Commerce API 参考中。

为了代表注册购物者和访客授权 API 请求，CommerceAPI 类依赖称为购物者登录和 API 访问服务 (SLAS) 的 Salesforce Commerce API。

对于购物篮和订单，CommerceAPI 类还使用 Open Commerce API (OCAPI)。

设置 API 访问中介绍设置 Salesforce Commerce API（包括 SLAS）和 OCAPI 的说明。

Chakra UI 组件库是一种新的生产就绪技术，我们乐于在 Retail React App 中予以使用。它包括 50 多个用户界面组件，所有组件都具有出色的可访问性和可用性。可以使用样式道具或使用 JavaScript 对象来定制组件以获得更高级的样式 (CSS-in-JS)。所有 Chakra 组件都带有精心设计的基本样式，这些样式能够用主题系统替代。

Chakra Theming 系统基于样式系统主题规范。您可以通过更新 app/theme 目录中的值来自定义组件的外观以适应您的品牌。

主题化可用于 app/components 大多数可重用组件，但不适用于“产品详细信息页面”或“产品列表页面”等页面。要更改这些页面的样式，请在源代码中为 app/pages 各自的页面组件编辑内联样式。

要在项目中包含自定义 SVG 图标，请将它们添加到 app/assets/svg 目录中，将它们导入 app/components/icons/index.js，然后按以下方式导出 React icon 组件：export const MyCustomIcon = icon('my-custom-icon')。

导入的 SVG 图标在构建时打包成 SVG sprite，并且 sprite 包含在服务器端呈现的 HTML 中。

PWA Kit React SDK 是支持 PWA Kit 网店的同构渲染管道的库。它包含许多为 Retail React App 提供支持的关键类、函数和组件。例如，启动整个渲染和路由过程的 app/ssr.js 中的 render() 函数是从 SDK 导入的。

SDK 抽出服务器端渲染、缓存和代理的一些实现细节，同时为您提供大量自定义其操作的机会。它还提供通用实用程序和工具，用于维护可以在客户端和服务器端呈现的单一代码集。

Salesforce 将 SDK 保持为与 Retail React App 分开的 npm 包，以便更轻松地进行改进。

PWA Kit React SDK 和整个 Retail React App 都是开源项目，可在 GitHub 上获得。我们欢迎来自 Commerce Cloud 社区的贡献！

本节中列出的开源技术是 Retail React App 最常用的技术。这些技术也最难以替代，我们选择它们不仅是因为其性能优异，还因为其出色的声誉。每一种技术都获得及时维护，而且高度可定制，文档丰富并被广泛使用。

以下是这些核心技术的简要概述，您可能已经熟悉其中的许多技术：

Babel编译您的 JavaScript 代码，使其与各种浏览器和 Node.js 环境兼容。Babel 转换高级语言语法并填充环境中缺少的任何功能。

Express 是一个流行的开源 Web 服务器框架，用 JavaScript 编写，在 Node.js 运行时环境中运行。Express.js 处理您定义为网店入口点的路由的 HTTP 请求。

Express 允许您配置常见的 Web 服务器设置，例如连接端口和返回响应的模板的位置。它还允许您在请求处理 Pipeline 中的任何位置添加额外的请求处理中间件。

PWA Kit 应用程序的所有服务器端代码都运行在 Node.js 上，Node.js 是 JavaScript 的开源运行时环境。运行时环境省略了特定于浏览器的 JavaScript API，并包含自己的 API，以跨平台的方式访问主机操作系统（例如文件系统）的功能。

Node.js 使用非阻塞或异步架构，非常适合构建高度可扩展和数据密集型的网店。

React是 Facebook 开发的一个框架，用于创建提供快速、流畅和沉浸式用户界面的单页应用程序。

在 React 应用程序中，用户界面由离散组件构建，这些组件通常排列在复杂的层次结构中。在设计良好的 React 应用程序中，每个组件只负责一项任务，而且通常该任务只是包含其他组件。

Retail React App 中的组件层次结构是为可扩展性而设计的。您可以在包含的组件基础之上构建或将它们换成新组件。

与 React 相关的软件包：

名称	说明
可加载组件	通过对较大的捆绑包进行代码拆分来提高性能。
ReactDOM	提供可在应用程序顶层使用的特定于 DOM 的方法。
ReactDOMServer	提供在服务器端预呈现 HTML 的方法 renderToString()。
React Helmet	帮助您管理对文档 `head` 标签的更改
React Router	将 URL 路径映射到 React 组件。路径可以表示为从最具体到最不具体的匹配模式。

Webpack 将您的代码整合到一个或多个捆绑包中。这些捆绑包被部署到 Managed Runtime，并最终作为水合过程的一部分加载到浏览器中。

Retail React App 从 PWA Kit React SDK 中为客户端和服务器端导入现成的 Webpack 配置。在大多数情况下，您无需更改这些配置，但如果要更改，可以在 webpack.config.js 扩展 Webpack 配置。

现在您已熟悉 Retail React App 的结构和内容，可以进行更深入的了解了！首先探索追踪代码，尤其是 app/pages 中的商务组件。