英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

示例店面

Mailchimp 开放商务 是一个以 API 为先、无头的商务平台，使用 Node.js、React 和 GraphQL 构建。它可以很好地与 npm、Docker 和 Kubernetes 协同工作。

此示例店面旨在作为参考，展示如何使用 Reaction Commerce GraphQL API 实现基于 Web 的店面。您可以将此项目 fork 作为起点，或使用您偏好的客户端技术创建自己的自定义体验。虽然我们认为示例店面功能足够强大，可在生产环境中使用，但目前可能缺少您的商店所需要的某些功能。

功能

Mailchimp 开放商务自带一套强大的核心商务能力。由于我们代码库中的任何内容都可以扩展、覆盖或作为 package 安装，您也可以自定义平台上的任何内容。

此示例店面使用 Next.js、React、GraphQL 和 Apollo Client 构建

• 无头电商示例店面，使用 Next.js、React、GraphQL 和 Apollo Client 构建
• Reaction GraphQL API 集成
• 服务端渲染
• 使用 Stripe 支付，并包含强用户认证 (Strong Customer Authentication)。
• 与 Segment 或任何其他提供商进行分析
• 可重用、可定制、可主题化的电商 React 组件，来自 示例店面组件库，使用 Styled Components
• 使用 ES6 编写，ES6 配置
• 使用 Docker 容器化

入门

请遵循 快速入门指南，安装并运行运行店面所需的所有服务：

注意：店面前端有重定向功能，因此如果你打开 http://localhost:4000/graphql，会被重定向到 GraphQL Playground。

配置

设置 Stripe

首次运行店面前端和 Reaction 时，你需要配置 Stripe 支付处理和运输选项，以测试完整的订单结账流程。在注册 Stripe API 密钥后，请按照以下步骤操作：

1. 将公共 Stripe API 密钥 (STRIPE_PUBLIC_API_KEY) 添加到 .env 文件中。
2. 打开 Reaction 管理后台应用，访问 http://localhost:4080。以管理员用户身份登录。
3. 打开 支付：通过勾选框启用 Stripe。添加 Stripe 的密钥和公共密钥。
4. 打开 运输：通过勾选框启用统一运费。至少启用一种统一运费类型，通过点击表格中的选项并勾选框。

设置分析事件追踪

阅读以下文档，了解如何 设置 Segment 或自定义分析追踪器

文档

• Example Storefront 完整文档
• Example Storefront 组件库仓库，文档
• Reaction 文档：使用 Jest 测试

开发

Reaction 平台使用 Docker 运行店面前端，因此你需要使用 Docker 命令查看日志、在容器内运行命令等。要专门针对店面前端运行命令，请确保切换到 reaction-platform 仓库中的 example-storefront 目录：

cd example-storefront

在开发模式下构建并运行，同时输出日志

创建一个符号链接以使用开发 Docker 镜像：

ln -s docker-compose.dev.yml docker-compose.override.yml

如果是第一次运行或 .env.example 中的环境变量已更改，请执行以下命令以更新环境变量。

./bin/setup

通过执行以下操作启动店面：

docker-compose up -d && docker-compose logs -f

在开发环境中针对生产 API 运行

将 .env 文件中的 INTERNAL_GRAPHQL_URL 改为生产 API 的 URL。URL 应该以 /graphql 结尾，例如：https://my-website.com/graphql。保存 .env 文件并使用以下方式重新启动应用程序：

docker-compose run --rm --service-ports web yarn start

在容器中运行命令

docker-compose run --rm web [command]

在 Docker 容器中运行任何命令，然后删除容器。使用此方法来运行任何工具操作。记住，你的项目目录将被挂载，通常一切都会正常工作。有关更多示例，请参见下面的 Yarn 部分。

在容器中运行测试

在本地运行测试

docker-compose run --rm web yarn test

在本地运行测试而不使用缓存（如果更改没有显示出来，这可能会有帮助）

docker-compose run --rm web yarn test --no-cache

运行 Snyk 安全测试（这将以与 CI 相同的方式运行测试）

docker-compose run --rm web sh -c "cp package.json ../ && cp .snyk ../ && cd .. && snyk auth && snyk test"

运行 ESLint

docker-compose run --rm web eslint src

使用 Chrome 开发者工具调试服务器

您可以使用 Google Chrome 开发者工具调试在 Docker 内运行的 Node.js 应用服务器中的代码。

• 运行 docker-compose run --rm --publish 9229:9229 --publish 4000:4000 -e NODE_ENV=development web node --inspect=0.0.0.0:9229 ./src/server.js
• 打开 Chrome 并访问 chrome://inspect。在 远程目标 (Remote Target) 下找到进程并点击 检查 (inspect)。

Yarn 命令

Yarn 和 NPM 应在 Docker 容器内运行。我们已采取措施确保 node_modules 被放置在可缓存的位置。如果您在本地运行 Yarn，node_modules 将直接写入项目目录，并优先于 Docker 构建中的 node_modules。
Yarn 添加

docker-compose run --rm web yarn add --dev [package]

安装 Yarn

⚠️ 每次修改 yarn.lock 或 Dockerfile 后，都要重新构建镜像并启动新的容器！

docker-compose run --rm web yarn install
docker-compose down --rmi local
docker-compose up -d --build

在店面测试组件库

有时我们需要在店面上下文中测试示例店面组件库的组件。不幸的是，在我们的Docker容器中没有简单的方法来做到这一点，所以我们需要在docker之外运行storefront。

1. cd到你本地的reaction-component-library仓库。
2. Git切换到你想要链接的正确分支
3. cd到该仓库的package文件夹，运行命令yarn install，然后运行yarn build
4. 构建完成后，cd到刚刚构建好的dist新文件夹中，运行yarn link以允许库安装到店面中。这将链接@reactioncommerce/components
5. 在example-storefront仓库中，暂时将你的.yarnrc文件重命名为其他名称（例如.yarnrc-temp）
6. 运行yarn install，然后运行命令yarn link "@reactioncommerce/components"，将本地版本设置为覆盖已发布的npm版本
7. 在你的.env文件中，将INTERNAL_GRAPHQL_URL更改为http://localhost:3000/graphql，与EXTERNAL_GRAPHQL_URL相同
8. 通过运行命令export $(cat .env | xargs) && yarn dev本地启动店面
9. 你的店面现在应该运行在localhost:4000
   • 如果你看到关于无法找到peer依赖包的错误，这似乎是yarn链接的问题。你可以临时在组件库package/dist文件夹中yarn add这些包。（无论如何，这个文件夹在git中被忽略）
10. 在测试完你的更改后，通过运行命令 CTRL+C 来关闭店面
11. 在店面仓库文件夹中运行yarn unlink "@reactioncommerce/components"
12. cd到reaction-component-library仓库的package/dist文件夹，运行命令yarn unlink来解除本地组件库版本的链接
13. 撤销.yarnrc文件的重命名
14. 撤销.env文件中的URL更改

清理容器

停止并保留容器:

docker-compose stop

停止，并移除容器：

docker-compose down

停止，并删除容器、卷和构建的镜像：

docker-compose down -v --rmi local

本地构建并运行生产应用

在开发过程中，有时制作应用的生产版本并在本地运行会很有帮助。

运行此命令以构建一个包含应用生产版的Docker镜像：

docker build --network=host -t  reactioncommerce/example-storefront:X.X.X .

其中 X.X.X 表示您要使用的标签版本，例如 3.1.0

然后，要在您的计算机上启动应用程序，请确保 Reaction API 容器已经运行，然后输入：

docker run -it --name storefront -p 4000:4000 --env-file .env.prod --network reaction.localhost reactioncommerce/example-storefront:X.X.X

注意: 你可以将 4000:4000 中冒号前的数字替换为你希望应用运行的其他本地主机端口。

注意: 这不是在实际生产环境中运行应用的方式。这仅用于在本地运行生产版本以进行开发、演示或试用。

要在使用上述命令启动 Docker 容器后停止它，请使用:

docker stop reaction-storefront

贡献

发现了一个漏洞、拼写错误或文档不完善的地方？我们希望您能提交一个问题告诉我们可以改进的地方！该项目使用semantic-release，请使用他们的提交信息格式。

想要请求一个功能？使用我们的Reaction Feature Requests 仓库提交请求。

我们喜欢你的拉取请求！查看我们的 Good First Issue 和 Help Wanted 标签，寻找适合解决的好问题。

拉取请求指南

拉取请求应通过所有自动化测试、风格检查和安全检查。

自动化测试

您的代码应通过所有验收测试和单元测试。运行

docker-compose run --rm web yarn test

在本地运行测试套件。如果你正在为 Reaction 添加功能，你应该为新增的功能添加测试。如果有必要，你可以通过传递 --no-cache 标志在本地无缓存地运行测试。如果更改没有显示出来，这可能会很有帮助。

docker-compose run --rm web yarn test --no-cache

更新失败的快照（如果你对某个组件进行了更改）

docker-compose run --rm web yarn test -u

Eslint

我们要求所有提交到 Reaction 的代码都遵循 Reaction 的 ESLint 规则。你可以运行

docker-compose run --rm web eslint src

在本地对您的代码运行 ESLint。

开发者来源证书

我们在 Reaction Commerce 开源项目的所有贡献中使用开发者来源证书 (DCO)来代替贡献者许可协议。我们要求贡献者同意 DCO 的条款，并通过在对 Reaction Commerce 项目所做的每个 Git 提交消息中添加包含您的姓名和电子邮件地址的一行来签署所有提交，以表明同意该条款：

Signed-off-by: Jane Doe <jane.doe@example.com>

如果你已在 Git 配置中设置了 user.name 和 user.email，你可以使用 git commit -s 自动为你的提交签名。

我们要求你使用真实姓名（请勿使用匿名或化名）。通过为提交签名，你即证明你有权在该 Reaction Commerce 项目使用的开源许可下提交该内容。你必须使用真实姓名（不允许使用化名或匿名提交）。

我们使用 Probot DCO GitHub 应用 来检查每个提交的 DCO 签署。

如果你忘记为提交签名，DCO 机器人会提醒你，并提供如何修改提交以添加签名的详细说明。

许可协议

版权所有 2019 Reaction Commerce

根据 Apache 许可证 2.0 版本（“许可证”）获得许可；
除非遵守许可证，否则你不得使用此文件。
你可以通过以下方式获取许可证的副本

   http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，根据许可分发的软件是按“原样”提供的，
不提供任何形式的明示或暗示的保证或条件。
有关许可下权限和限制的具体语言，请参阅许可协议。

📷 原文此处有图片，请前往 GitHub 仓库查看完整内容。