后端电商【免费下载链接】reactionProject has been discontinued ////// Mailchimp Open Commerce is an API-first, headless commerce platform built using Node.js, React, GraphQL. Deployed via Docker and Kubernetes.项目地址https://gitcode.com/gh_mirrors/re/reaction点击查看免费下载reactioncommerce/api-plugin-files是 Mailchimp Open CommerceReaction API中的文件管理插件负责商品、标签、店铺等场景下媒体文件的上传、图片多尺寸派生、GridFS 持久化与后台异步处理。本文以该插件 CHANGELOG.md 中 2.0.0 与 1.1.0 两个版本的变更记录为主线结合仓库内源码实现深入解析版本演进背后的工程决策帮助读者理解该插件临时存储 → 后台 Worker → GridFS 多尺寸存储 → GraphQL 元数据管理的完整链路以及 Node 18 JSON import assertion、opaque ID 兼容处理、sharp 图像库升级等具体改造点。插件定位与整体架构从 src/index.js 的register(app)可以看出该插件通过app.registerPlugin注册主要声明了以下能力集合collectionsMediaRecords对应 MongoDB 集合cfs.Media.filerecord并针对metadata.productId、metadata.variantId、metadata.priority、original.remoteURL、original.tempStoreId建立了向后兼容的索引索引命名与旧的 aldeed:schema-index Meteor 包一致GraphQL一组媒体记录的 mutations 与 resolver后台任务saveImage/local与saveImage/remote两类清理任务purgeAfterDays: 7启动钩子startup阶段完成文件集合与 Worker 的初始化。核心的启动逻辑在 startup.js它在启动时调用setUpFileCollections装配下载管理器、媒体文件集合、远程 URL Worker 与临时文件 Worker并把collections.Media暴露给 resolver同时在 Express 上挂载两个路由/assets/files → downloadManager.connectHandler文件下载 /assets/uploads → tempStore.connectHandler浏览器分块上传整个媒体上传流水线可以概括为三个阶段临时存储浏览器通过/assets/uploads将文件分块上传到TempFileStore后台 Worker 转储TempFileStoreWorker监听上传完成的临时文件将其合并后写入永久 GridFS storesRemoteUrlWorker则负责将original.remoteURL指向的远程图片拉取入库元数据管理客户端通过 GraphQL mutation 创建/归档/删除/调整MediaRecord元数据文件实体则由Media集合统一管理。2.0.0 主要变更Node 18 升级与 JSON import assertionCHANGELOG 的 2.0.0 Major Changes 记录了一条关键改动——PR [#6740] 将 Node 版本升级到 18并引入了assert { type: json }语法。这在源码中有直接对应import pkg from ../package.json assert { type: json }; import policies from ./policies.json assert { type: json };参见 src/index.js。这是 ECMAScript ModulesESM规范中 JSON 模块导入的标准写法用于显式声明导入的 JSON 资源取代此前 CommonJS 环境下依赖createRequire才能读取 JSON 的做法。值得一提的是项目中仍保留了兼容手段——setUpFileCollections.js 顶部通过createRequire(import.meta.url)加载file-collections与file-collections-sa-gridfs等 CJS 依赖说明该插件在 ESM 改造中采用新代码用 import assertion、存量 CJS 依赖用 createRequire的渐进式策略。同时package.json 中type: module与engines: { node: 14.18.1 }并存engines声明了运行下限而 CHANGELOG 明确 2.0.0 起以 Node 18 为目标版本完成验证。对于部署方这意味着升级到 2.0.0 后应确保 Node 运行时支持 JSON import assertionNode 18 默认启用无需 flag。2.0.0 次要变更解码前先校验 opaque ID普通 ID 直接透传2.0.0 的 Minor Changes 记录了一项对 GraphQL 入参处理的重要优化——PR [#6744]checks for encodedId before calling decode. Normal-id pass through。此前 resolver 层对mediaRecordId、shopId等入参一律执行 opaque ID 解码即使客户端传入的已经是内部普通 ID也会被误解码导致错误。2.0.0 之后resolver 统一改为先判断、再解码、否则透传的模式。以 resolvers/Mutation/deleteMediaRecord.js 为例const mediaRecord await context.mutations.deleteMediaRecord(context, { mediaRecordId: isOpaqueId(opaqueMediaRecordId) ? decodeMediaRecordOpaqueId(opaqueMediaRecordId) : opaqueMediaRecordId, shopId: isOpaqueId(opaqueShopId) ? decodeShopOpaqueId(opaqueShopId) : opaqueShopId });相同的模式还应用于 archiveMediaRecord.js 与 updateMediaRecordPriority.js。ID 命名空间定义集中在 src/xforms/id.js覆盖三个命名空间命名空间用途reaction/mediaRecordMediaRecord 的 opaque ID 编解码reaction/productproductId / variantId 的 opaque ID 编解码reaction/shopshopId 的 opaque ID 编解码createMediaRecordresolver 还额外对mediaRecordInput.metadata.productId、variantId分别做 opaque 判断与解码见 resolvers/Mutation/createMediaRecord.js防止客户端混用两种 ID 格式导致查询不到记录。这一改动对 GraphQL 客户端尤其是直接透传数据库内部 ID 的管理后台是明显的兼容性修复。1.1.0 变更sharp 图像处理库 0.29 → 0.301.1.0 的变更PR [#6706]是升级图像处理依赖sharp从 0.29 到 0.30。sharp 是媒体文件流水线中真正的图片处理引擎它承担了setUpFileCollections中所有图片的尺寸缩放、裁剪与格式转换工作。在 setUpFileCollections.js 中插件为每张图片定义了 5 种派生规格规格名尺寸 (px)适配方式输出格式MIMEimage1600inside等比缩放jpgimage/jpeglarge1000inside等比缩放jpgimage/jpegmedium600inside等比缩放jpgimage/jpegsmall235cover正方形裁剪pngimage/pngthumbnail100cover正方形裁剪pngimage/png每种规格通过buildGFS生成独立的GridFSStore实例setUpFileCollections.js其transformWrite使用 sharp 的.resize({ fit, withoutEnlargement: true }).toFormat(...)构建变换流同时更新文件记录的 type 与 extension。需要特别说明的是withoutEnlargement: true保证小图不会被放大cover模式下的small/thumbnail会裁剪为正方形并输出 PNG与inside模式的 JPG 形成不同的内容策略。升级到 sharp 0.30 的意义在于0.30 是基于 libvips 8.12 的重构版本在图像解码、内存管理与元数据处理上均有改进同时保持 API 兼容。对插件使用者而言升级后图片处理行为基本无感但部署镜像中的原生依赖需要随之更新本插件在 package.json 中声明sharp: ^0.30.7。版本联动三个核心依赖同步升级2.0.0 的 Patch Changes 记录了三个底层依赖的联动升级它们共同构成文件能力的基石reactioncommerce/file-collections0.10.0提供FileRecord、MongoFileCollection、TempFileStore、RemoteUrlWorker、TempFileStoreWorker、FileDownloadManager等核心类reactioncommerce/file-collections-sa-gridfs0.2.0提供 GridFS 存储实现GridFSStorereactioncommerce/api-utils2.0.0提供encodeOpaqueId/decodeOpaqueIdForNamespace/isOpaqueId等 ID 工具函数与 Schema 加载工具。在 setUpFileCollections.js 中可以看到这些包的配合方式TempFileStore仅接受type以image/开头的上传请求setUpFileCollections.jsMongoFileCollection(Media)将多个规格的 GridFS stores 与临时存储组合成一个集合FileDownloadManager为/assets/files提供下载服务并设置了长达一年的Cache-Control: public, max-age31536000缓存头setUpFileCollections.js。后台任务saveImage/local 与 saveImage/remote媒体从临时/远程到永久存储的转换全部走后台任务队列这也是backgroundJobs中注册saveImage/*清理任务的背景。任务创建util/createSaveImageJob.js 根据isRemote决定任务类型为saveImage/remote或saveImage/local并设置priority: normal、最多重试 5 次、每次等待 5 秒且采用指数退避backoff: exponential的重试策略。当RemoteUrlWorker与TempFileStoreWorker发现新的文件记录时会分别通过onNewRemoteFileRecord/onNewTempFileRecord回调触发该任务setUpFileCollections.js。任务执行两个 Worker 分别定义在 jobs/saveRemoteImages.js 与 jobs/saveTempImages.js统一采用 3 秒轮询间隔、10 分钟超时workTimeout成功调用job.done、失败调用job.fail并携带错误信息。需要留意的一个实现细节是setUpFileCollections.js 中两个 Worker 的启动被if (config.NODE_ENV ! test)包裹注释明确指出 Worker 依赖.watchAPI需要 MongoDB replica set 与合适的 read/write concern而 Jest 集成测试使用的内存 Mongo 服务器不满足该条件因此在测试环境下会跳过 Worker 启动。这是部署到生产环境时值得关注的运维前提——单节点 MongoDB 无法支撑该能力。面向客户端的 GraphQL 能力插件对外暴露了 4 个 mutation定义见 schemas/schema.graphqlMutation作用createMediaRecord文件已上传到临时存储后创建对应的 MediaRecord 元数据archiveMediaRecord归档媒体记录仅改metadata.workflow为archived不删除文件数据deleteMediaRecord删除媒体记录同时通过Media.remove删除背后文件数据updateMediaRecordPriority更新metadata.priority用于商品/变体媒体在目录中的排序各 mutation 的入参与响应类型MediaRecordInput、MediaRecordInfoInput、MediaRecordMetadataInput及对应的 Payload 类型都在 schema 中完整定义。实现层的几个要点权限校验每个 mutation 都调用context.validatePermissions权限策略在 policies.json 中声明——reaction:groups:media-managers组的用户拥有对reaction:legacy:mediaRecords资源的create:media权限以及对reaction:legacy:mediaRecords:*的delete:media/update:media权限数据校验MediaRecord使用 simpl-schema 定义simpleSchemas.js其中original包含name、size、type、updatedAt、uploadedAt以及可选的remoteURL与tempStoreId事件广播插入、更新、删除后分别通过appEvents.emit(afterMediaInsert | afterMediaUpdate | afterMediaRemove)发布事件便于其他插件订阅联动。跨插件协作文件能力如何被其他模块复用files插件的媒体能力并不孤立。在 apps/reaction/plugins.json 中可以看到它作为 Reaction API 应用的内置插件被注册。其他插件可以直接依赖collections.Media与collections.MediaRecords——例如 packages/api-plugin-tags/src/mutations/setTagHeroMedia.js 在为标签设置 Hero 媒体时会直接向MediaRecords插入文档并依据FileRecord.downloadEndpointPrefix即/assets/files拼出处理完成后的图片 URLheroMediaUrl ${FileRecord.downloadEndpointPrefix}/${Media.name}/${insertedId}/large/${fileRecord.original.name};这一 URL 拼接约定与插件中定义的 5 种图片规格直接对应——即/assets/files/Media/{mediaRecordId}/large/原文件名可访问large规格派生图。同时该实现也提示读者如果文件插件未注册依赖它的模块会抛出 Cannot add media if the files plugin isnt registered 错误见同一文件第 28 行体现了插件化架构中模块间的显式依赖关系。版本演进总结与升级要点综合 CHANGELOG 与源码可将 api-plugin-files 近两个版本的演进归纳如下版本变更类型核心内容2.0.0MajorNode 18 升级引入assert { type: json }JSON 模块导入2.0.0Minoropaque ID 解码前先校验普通 ID 直接透传提升 GraphQL 入参兼容性2.0.0Patchfile-collections0.10.0、file-collections-sa-gridfs0.2.0、api-utils2.0.0联动升级1.1.0Minor图像处理库 sharp 从 0.29 升级到 0.30对正在使用该插件或计划在 Reaction API 中接入媒体能力的开发者以下几点值得在升级与部署时重点核对运行时版本2.0.0 起面向 Node 18请确保运行环境满足 JSON import assertion 的支持要求ID 格式2.0.0 之后客户端可以混用 opaque ID 与普通内部 ID但如果仍基于旧版 API 开发建议统一使用 opaque ID 并保证与xforms/id.js中命名空间一致存储架构媒体转储依赖 MongoDB replica set 的 change stream.watch单节点部署无法启用 Worker原生依赖sharp 0.30 涉及 libvips 原生库更新Docker 镜像需同步重建而非仅更新 npm 包存储规格所有上传图片都会派生 5 种规格并存入独立的 GridFS stores前缀cfs_gridfs.chunkSize 为 1MB需评估存储与流量成本。通过 CHANGELOG.md 与 README.md项目采用 GPL-3.0 协议与 Developer Certificate of Origin 贡献规范配合本仓库中 src/setUpFileCollections.js 等核心实现开发者可以在不引入额外依赖的情况下完整复现这套临时上传 后台派生 GridFS 持久化 GraphQL 元数据管理的电商媒体文件方案。赞分享后端电商【免费下载链接】reactionProject has been discontinued ////// Mailchimp Open Commerce is an API-first, headless commerce platform built using Node.js, React, GraphQL. Deployed via Docker and Kubernetes.项目地址https://gitcode.com/gh_mirrors/re/reaction点击查看免费下载相关推荐Reaction api-plugin-payments 2.0.0 升级解读Node 18 迁移、JSON Import Assertion 与 Opaque ID 解码优化Reaction api plugin payments 2.0.0 升级解读Node 18 迁移、JSON Import Assertion 与 Opaqu后端电商Reaction api-plugin-taxes 2.0.0 升级解析Node 18 兼容、JSON import assertions 与 opaque ID 解码优化Reaction api plugin taxes 2.0.0 升级解析Node 18 兼容、JSON import assertions 与 opaque后端电商Reaction API 地址校验插件 v2.0.0 变更深度解读Node 18 升级与 Opaque ID 解码防护Reaction API 地址校验插件 v2.0.0 变更深度解读Node 18 升级与 Opaque ID 解码防护 本文围绕 reactioncomme后端电商上一篇decimen-optical-transfer 的 vendored 解码器decimen-codec WASM 构建的许可证构成与运行时身份下一篇Civitai 付费模型加载Paid Model Loading决策档案解析从开放问题到已定方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考