尧图网页设计 
Huly 服务端中间件包 hcengineering/middleware 演进解析从事务排序到访客权限的事务处理流水线【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform导读hcengineering/middleware是 Huly 服务端事务处理流水线的核心包负责对进入工作区的每一项事务Transaction进行排序、鉴权、标识符生成与广播前处理。本文以 foundations/server/packages/middleware/CHANGELOG.md 的版本演进为主线结合包内源码与测试逐层剖析TxOrderingMiddleware、IdentifierMiddleware、GuestPermissionsMiddleware、FindSecurityMiddleware等关键中间件的设计动机、实现原理与调用关系帮助你理解 Huly 服务端如何在高并发写路径上保证一致性、安全性与实时性。一、包定位服务端事务流水线的中间层在 Huly 的服务端架构中客户端发起的每一次数据变更都会被包装为事务Tx随后流经一串中间件Middleware构成的管道最终落库并广播给订阅了相关查询的会话。hcengineering/middleware就是这条管道的核心实现集合。从 foundations/server/packages/middleware/package.json 可以看到它的依赖关系它基于hcengineering/core事务与领域模型、hcengineering/server-core中间件基类BaseMiddleware、Middleware、PipelineContext构建并依赖hcengineering/contact、hcengineering/platform、hcengineering/query、hcengineering/rank等包许可证为 EPL-2.0通过hcengineering/platform-rig统一构建。包的导出清单见 foundations/server/packages/middleware/src/index.ts它一次性导出了 30 余个模块覆盖了事务处理的完整环节能力分类导出模块职责事务落库applyTx、domainTx、domainFind、lowLevel、dbAdapter、dbAdapterHelper将事务写入对应领域domain存储中间件组件txOrdering、identifier、guestPermissions、findSecurity、spaceSecurity、spacePermissions事务排序、标识符生成、权限校验、查询安全过滤实时订阅liveQuery、broadcast、txPush、queue活动查询维护与变更广播查询增强lookup、queryJoin、fulltext、modified关联查询、子查询合并、全文检索模型与元数据model、configuration、pluginConfig、versioning、rank、identity、userStatus模型解析、插件配置、版本管理、身份信息二、从 CHANGELOG 看版本演进一条清晰的加固路径hcengineering/middleware于2025-10-09以 0.7.0 首次发布随后在约一个半月内快速迭代到 0.7.22。尽管 CHANGELOG.md 中多数条目是简短的 Bump、Update deps 等例行更新但其中四条 Patches 直接刻画了本包的核心能力演进版本时间变更说明对应源码0.7.02025-10-09Initial release首次发布—0.7.22025-10-10Add TxOrderingMiddleware 新依赖txOrdering.ts0.7.52025-10-13Fix ordering middleware排序中间件修复同上0.7.102025-10-21Add identifier middleware标识符中间件identifier.ts0.7.162025-10-30Fix identifier middleware同上0.7.172025-10-30allow guests to update their identities允许访客更新自身身份guestPermissions.ts0.7.182025-11-06Add tMatch permission middleware权限匹配中间件同上0.7.192025-11-07Fix permission middleware同上0.7.20 / 0.7.212025-11-19/22Fix exception in findAll查询异常修复findSecurity.ts0.7.222025-11-26Bump—可以看到这个包的演进主线非常清晰先解决并发一致性TxOrdering再补齐业务标识Identifier随后重点加固访客权限模型GuestPermissions最后稳定查询链路FindSecurity。下文将沿着这条主线逐层展开。三、TxOrderingMiddleware为同一文档串行化事务0.7.2 引入3.1 解决什么问题在客户端并行提交多个更新同一文档的事务时事务可能乱序到达服务端——例如modifiedOn101的事务反而比modifiedOn102的事务更晚到达。若此时并发处理中间件链下游会反复触发不必要的getCurrentDoc重读并在广播阶段造成客户端状态错乱。3.2 实现原理从 txOrdering.ts 的实现看其核心是TxOrderingMiddleware extends BaseMiddleware内部维护一个按文档维度的等待队列按文档分组在tx()方法中先通过getTargetDocId(tx)提取每笔事务的目标文档对 CUD 类事务即objectId将同一文档的事务归入一组txOrdering.ts排队等待为每个文档记录一条TxOrderEntry含txIds、modifiedOn、completionPromise同一文档的新批次事务先await前一批的completionPromise保证同文档事务严格串行而不同文档之间完全并行txOrdering.ts确定性释放在provideTx()完成后于finally块中completionResolve()唤醒后续等待者并清理已完成的队列条目——即使处理过程抛异常等待者也不会被卡死txOrdering.ts广播直通由于事务在tx()阶段已保证有序handleBroadcast()直接透传无需重复排序。3.3 测试验证foundations/server/packages/middleware/src/tests/txOrdering.test.ts 为该中间件提供了 8 个测试用例覆盖乱序到达仍顺序处理同时发起[tx2, tx1, tx3]modifiedOn 分别为 102、101、103断言三笔事务最终都被处理executionOrder与new Set([101,102,103])相等多文档并行文档 A、B 各自的两笔事务同时提交互不阻塞异常释放让下游中间件在首笔事务抛错后断言后续事务仍能正常执行、不会挂起批量与已有序场景10 笔同文档事务、已按序到达的事务均能正确完成。四、IdentifierMiddleware事务内自动生成业务标识符0.7.10 引入4.1 解决什么问题许多业务对象需要可读性强的自然标识如PRJ-000123这类带前缀的编号而不是随机的十六进制 ID。如果这类逻辑散落在各业务插件中容易重复实现且难以统一管理。IdentifierMiddleware将创建/更新文档时按需补齐标识符下沉到事务管道中统一处理。4.2 实现原理从 identifier.ts 看其tx()方法遍历每一笔事务仅对目标事务TxCreateDoc、TxMixin以及携带_class变更的TxUpdateDoc见isTargetTx执行标识符补齐创建路径setIdentifiers通过hierarchy.getAllAttributes(objectClass)扫描类属性凡是类型为core.class.TypeIdentifier且当前值为空的事务属性调用generateIdentifier生成新值并写回tx.attributesidentifier.ts更新路径setIdentifiersInUpdate当TxUpdateDoc通过operations._class变更对象类时比较新旧类的属性集合只为新增的TypeIdentifier属性生成标识identifier.ts序列生成generateIdentifier查询core.class.CustomSequence序列文档用TxFactory构造一笔$inc: { sequence: 1 }的自增更新事务provideTx落库后拼出{prefix}-{sequence}形式的标识符identifier.ts。值得注意自增更新使用createTxUpdateDoc(..., true)的内部事务标记且序列的查询与自增在同一中间件内完成从实现上看正是借助事务管道自身来保证序列的单调性。五、GuestPermissionsMiddleware访客权限的新旧模型衔接0.7.17 ~ 0.7.19访客权限是 CHANGELOG 中改动最密集的区域0.7.17 允许访客更新自身身份、0.7.18 新增权限匹配中间件、0.7.19 修复对应源码是 guestPermissions.ts。5.1 判定流程tx()入口先按账户角色分流guestPermissions.ts普通 User / Owner直接放行同时检查是否需要失效权限缓存DocGuest / ReadOnlyGuest一律抛出ForbiddenPlatformErrorGuest逐笔调用processTx做精细化判定。对每笔 CUD 事务processTx又分两条路径guestPermissions.tsSpace 类事务isDerived(objectClass, core.class.Space)走isForbiddenSpaceTx——禁止移除 Space创建 Space 需满足访问级别 mixin更新 Space 时若涉及members、private、archived、owners、autoJoin或$push/$pull等敏感操作则一律禁止guestPermissions.ts普通文档事务走isForbiddenTx。5.2 新旧权限模型的双轨判定isForbiddenTx体现了 CHANGELOG 0.7.18 tMatch permission middleware 带来的新模型guestPermissions.ts新模型优先covered class从ModulePermissionGroup配置文档加载各角色允许的权限集再通过ClassPermission映射到具体类只要事务目标类命中该角色的已覆盖类集合即视为允许忽略TxAccessLevelmixin 的判定getCoveredClass借助hierarchy.isDerived做父子类匹配旧模型回退uncovered class未覆盖的类回退到TxAccessLevelmixinhasMixinAccessLevel——createAccessLevel/removeAccessLevel/updateAccessLevel是否为Guest级别身份特例对标记了isIdentity的属性或Person类允许访客更新自己的身份比对socialIds或personUuid这正是 0.7.17 变更的落点guestPermissions.ts自有文档特例访客可以更新/删除自己createdBy创建的文档isGuestMutationOnOwnDocisCreatedByAccount缓存与失效权限映射结果缓存于permissionsCache当有事务修改ModulePermissionGroup文档时置空缓存、下次惰性重建guestPermissions.ts。5.3 测试验证foundations/server/packages/middleware/src/tests/guestPermissions.test.ts 系统地验证了上述规则包括User/Owner 直通、DocGuest/ReadOnlyGuest 一律拒绝、covered class 在任意空间可创建即使缺少TxAccessLevel、disabledPermissions失效、uncovered class 回退TxAccessLevel、访客可改/删自有文档但不可改他人文档、以及配置更新后的缓存失效。六、FindSecurityMiddleware 与查询链路稳定0.7.20 / 0.7.21CHANGELOG 中 0.7.20 与 0.7.21 连续两次 Fix exception in findAll对应的查询侧组件是 findSecurity.ts。该中间件拦截findAll调用显式剥离FindOptions中不被下游安全层接受的字段limit、sort、lookup、projection、associations、total、showArchived再透传给provideFindAllfindSecurity.ts避免异常字段导致查询抛出异常。查询链路的另一侧是 liveQuery.tsLiveQueryMiddleware在构造时基于hcengineering/query的LiveQuery创建活动查询客户端newCastClient其findAll/findOne最终都汇入本管道的findAll并用hierarchy.updateLookupMixin处理后返回——这也是 liveQuery.race.test.ts 所覆盖的并发场景。findAll的稳定性因此直接关系到所有实时查询的正确性两次针对性修复也印证了查询链路在整个流水线中的核心地位。七、如何查看与验证阅读入口index.ts 是所有中间件组件的统一出口建议从它开始按模块名顺藤摸瓜运行测试包内使用 Jest见 package.json 的test脚本测试目录 foundations/server/packages/middleware/src/tests 中的txOrdering.test.ts、guestPermissions.test.ts、liveQuery.race.test.ts、queryJoiner.spec.ts覆盖了本文涉及的核心行为结合变更历史CHANGELOG.md 与 CHANGELOG.json 记录了每个能力引入与修复的时间点可作为代码研读的索引。结语hcengineering/middleware的版本演进展示了 Huly 服务端写路径的加固逻辑先用TxOrderingMiddleware以文档粒度串行化并发事务、从根上消除乱序竞态再用IdentifierMiddleware把业务编号生成收拢进管道随后用GuestPermissionsMiddleware在新旧两套权限模型之间建立优先级与回退规则最后以FindSecurityMiddleware稳定查询链路。理解这套中间件组合也就理解了 Huly 服务端有序、安全、实时三条底线分别由谁守护。【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Huly 服务端中间件包 @hcengineering/middleware 演进解析：从事务排序到访客权限的事务处理流水线
Huly 服务端中间件包 hcengineering/middleware 演进解析从事务排序到访客权限的事务处理流水线【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform导读hcengineering/middleware是 Huly 服务端事务处理流水线的核心包负责对进入工作区的每一项事务Transaction进行排序、鉴权、标识符生成与广播前处理。本文以 foundations/server/packages/middleware/CHANGELOG.md 的版本演进为主线结合包内源码与测试逐层剖析TxOrderingMiddleware、IdentifierMiddleware、GuestPermissionsMiddleware、FindSecurityMiddleware等关键中间件的设计动机、实现原理与调用关系帮助你理解 Huly 服务端如何在高并发写路径上保证一致性、安全性与实时性。一、包定位服务端事务流水线的中间层在 Huly 的服务端架构中客户端发起的每一次数据变更都会被包装为事务Tx随后流经一串中间件Middleware构成的管道最终落库并广播给订阅了相关查询的会话。hcengineering/middleware就是这条管道的核心实现集合。从 foundations/server/packages/middleware/package.json 可以看到它的依赖关系它基于hcengineering/core事务与领域模型、hcengineering/server-core中间件基类BaseMiddleware、Middleware、PipelineContext构建并依赖hcengineering/contact、hcengineering/platform、hcengineering/query、hcengineering/rank等包许可证为 EPL-2.0通过hcengineering/platform-rig统一构建。包的导出清单见 foundations/server/packages/middleware/src/index.ts它一次性导出了 30 余个模块覆盖了事务处理的完整环节能力分类导出模块职责事务落库applyTx、domainTx、domainFind、lowLevel、dbAdapter、dbAdapterHelper将事务写入对应领域domain存储中间件组件txOrdering、identifier、guestPermissions、findSecurity、spaceSecurity、spacePermissions事务排序、标识符生成、权限校验、查询安全过滤实时订阅liveQuery、broadcast、txPush、queue活动查询维护与变更广播查询增强lookup、queryJoin、fulltext、modified关联查询、子查询合并、全文检索模型与元数据model、configuration、pluginConfig、versioning、rank、identity、userStatus模型解析、插件配置、版本管理、身份信息二、从 CHANGELOG 看版本演进一条清晰的加固路径hcengineering/middleware于2025-10-09以 0.7.0 首次发布随后在约一个半月内快速迭代到 0.7.22。尽管 CHANGELOG.md 中多数条目是简短的 Bump、Update deps 等例行更新但其中四条 Patches 直接刻画了本包的核心能力演进版本时间变更说明对应源码0.7.02025-10-09Initial release首次发布—0.7.22025-10-10Add TxOrderingMiddleware 新依赖txOrdering.ts0.7.52025-10-13Fix ordering middleware排序中间件修复同上0.7.102025-10-21Add identifier middleware标识符中间件identifier.ts0.7.162025-10-30Fix identifier middleware同上0.7.172025-10-30allow guests to update their identities允许访客更新自身身份guestPermissions.ts0.7.182025-11-06Add tMatch permission middleware权限匹配中间件同上0.7.192025-11-07Fix permission middleware同上0.7.20 / 0.7.212025-11-19/22Fix exception in findAll查询异常修复findSecurity.ts0.7.222025-11-26Bump—可以看到这个包的演进主线非常清晰先解决并发一致性TxOrdering再补齐业务标识Identifier随后重点加固访客权限模型GuestPermissions最后稳定查询链路FindSecurity。下文将沿着这条主线逐层展开。三、TxOrderingMiddleware为同一文档串行化事务0.7.2 引入3.1 解决什么问题在客户端并行提交多个更新同一文档的事务时事务可能乱序到达服务端——例如modifiedOn101的事务反而比modifiedOn102的事务更晚到达。若此时并发处理中间件链下游会反复触发不必要的getCurrentDoc重读并在广播阶段造成客户端状态错乱。3.2 实现原理从 txOrdering.ts 的实现看其核心是TxOrderingMiddleware extends BaseMiddleware内部维护一个按文档维度的等待队列按文档分组在tx()方法中先通过getTargetDocId(tx)提取每笔事务的目标文档对 CUD 类事务即objectId将同一文档的事务归入一组txOrdering.ts排队等待为每个文档记录一条TxOrderEntry含txIds、modifiedOn、completionPromise同一文档的新批次事务先await前一批的completionPromise保证同文档事务严格串行而不同文档之间完全并行txOrdering.ts确定性释放在provideTx()完成后于finally块中completionResolve()唤醒后续等待者并清理已完成的队列条目——即使处理过程抛异常等待者也不会被卡死txOrdering.ts广播直通由于事务在tx()阶段已保证有序handleBroadcast()直接透传无需重复排序。3.3 测试验证foundations/server/packages/middleware/src/tests/txOrdering.test.ts 为该中间件提供了 8 个测试用例覆盖乱序到达仍顺序处理同时发起[tx2, tx1, tx3]modifiedOn 分别为 102、101、103断言三笔事务最终都被处理executionOrder与new Set([101,102,103])相等多文档并行文档 A、B 各自的两笔事务同时提交互不阻塞异常释放让下游中间件在首笔事务抛错后断言后续事务仍能正常执行、不会挂起批量与已有序场景10 笔同文档事务、已按序到达的事务均能正确完成。四、IdentifierMiddleware事务内自动生成业务标识符0.7.10 引入4.1 解决什么问题许多业务对象需要可读性强的自然标识如PRJ-000123这类带前缀的编号而不是随机的十六进制 ID。如果这类逻辑散落在各业务插件中容易重复实现且难以统一管理。IdentifierMiddleware将创建/更新文档时按需补齐标识符下沉到事务管道中统一处理。4.2 实现原理从 identifier.ts 看其tx()方法遍历每一笔事务仅对目标事务TxCreateDoc、TxMixin以及携带_class变更的TxUpdateDoc见isTargetTx执行标识符补齐创建路径setIdentifiers通过hierarchy.getAllAttributes(objectClass)扫描类属性凡是类型为core.class.TypeIdentifier且当前值为空的事务属性调用generateIdentifier生成新值并写回tx.attributesidentifier.ts更新路径setIdentifiersInUpdate当TxUpdateDoc通过operations._class变更对象类时比较新旧类的属性集合只为新增的TypeIdentifier属性生成标识identifier.ts序列生成generateIdentifier查询core.class.CustomSequence序列文档用TxFactory构造一笔$inc: { sequence: 1 }的自增更新事务provideTx落库后拼出{prefix}-{sequence}形式的标识符identifier.ts。值得注意自增更新使用createTxUpdateDoc(..., true)的内部事务标记且序列的查询与自增在同一中间件内完成从实现上看正是借助事务管道自身来保证序列的单调性。五、GuestPermissionsMiddleware访客权限的新旧模型衔接0.7.17 ~ 0.7.19访客权限是 CHANGELOG 中改动最密集的区域0.7.17 允许访客更新自身身份、0.7.18 新增权限匹配中间件、0.7.19 修复对应源码是 guestPermissions.ts。5.1 判定流程tx()入口先按账户角色分流guestPermissions.ts普通 User / Owner直接放行同时检查是否需要失效权限缓存DocGuest / ReadOnlyGuest一律抛出ForbiddenPlatformErrorGuest逐笔调用processTx做精细化判定。对每笔 CUD 事务processTx又分两条路径guestPermissions.tsSpace 类事务isDerived(objectClass, core.class.Space)走isForbiddenSpaceTx——禁止移除 Space创建 Space 需满足访问级别 mixin更新 Space 时若涉及members、private、archived、owners、autoJoin或$push/$pull等敏感操作则一律禁止guestPermissions.ts普通文档事务走isForbiddenTx。5.2 新旧权限模型的双轨判定isForbiddenTx体现了 CHANGELOG 0.7.18 tMatch permission middleware 带来的新模型guestPermissions.ts新模型优先covered class从ModulePermissionGroup配置文档加载各角色允许的权限集再通过ClassPermission映射到具体类只要事务目标类命中该角色的已覆盖类集合即视为允许忽略TxAccessLevelmixin 的判定getCoveredClass借助hierarchy.isDerived做父子类匹配旧模型回退uncovered class未覆盖的类回退到TxAccessLevelmixinhasMixinAccessLevel——createAccessLevel/removeAccessLevel/updateAccessLevel是否为Guest级别身份特例对标记了isIdentity的属性或Person类允许访客更新自己的身份比对socialIds或personUuid这正是 0.7.17 变更的落点guestPermissions.ts自有文档特例访客可以更新/删除自己createdBy创建的文档isGuestMutationOnOwnDocisCreatedByAccount缓存与失效权限映射结果缓存于permissionsCache当有事务修改ModulePermissionGroup文档时置空缓存、下次惰性重建guestPermissions.ts。5.3 测试验证foundations/server/packages/middleware/src/tests/guestPermissions.test.ts 系统地验证了上述规则包括User/Owner 直通、DocGuest/ReadOnlyGuest 一律拒绝、covered class 在任意空间可创建即使缺少TxAccessLevel、disabledPermissions失效、uncovered class 回退TxAccessLevel、访客可改/删自有文档但不可改他人文档、以及配置更新后的缓存失效。六、FindSecurityMiddleware 与查询链路稳定0.7.20 / 0.7.21CHANGELOG 中 0.7.20 与 0.7.21 连续两次 Fix exception in findAll对应的查询侧组件是 findSecurity.ts。该中间件拦截findAll调用显式剥离FindOptions中不被下游安全层接受的字段limit、sort、lookup、projection、associations、total、showArchived再透传给provideFindAllfindSecurity.ts避免异常字段导致查询抛出异常。查询链路的另一侧是 liveQuery.tsLiveQueryMiddleware在构造时基于hcengineering/query的LiveQuery创建活动查询客户端newCastClient其findAll/findOne最终都汇入本管道的findAll并用hierarchy.updateLookupMixin处理后返回——这也是 liveQuery.race.test.ts 所覆盖的并发场景。findAll的稳定性因此直接关系到所有实时查询的正确性两次针对性修复也印证了查询链路在整个流水线中的核心地位。七、如何查看与验证阅读入口index.ts 是所有中间件组件的统一出口建议从它开始按模块名顺藤摸瓜运行测试包内使用 Jest见 package.json 的test脚本测试目录 foundations/server/packages/middleware/src/tests 中的txOrdering.test.ts、guestPermissions.test.ts、liveQuery.race.test.ts、queryJoiner.spec.ts覆盖了本文涉及的核心行为结合变更历史CHANGELOG.md 与 CHANGELOG.json 记录了每个能力引入与修复的时间点可作为代码研读的索引。结语hcengineering/middleware的版本演进展示了 Huly 服务端写路径的加固逻辑先用TxOrderingMiddleware以文档粒度串行化并发事务、从根上消除乱序竞态再用IdentifierMiddleware把业务编号生成收拢进管道随后用GuestPermissionsMiddleware在新旧两套权限模型之间建立优先级与回退规则最后以FindSecurityMiddleware稳定查询链路。理解这套中间件组合也就理解了 Huly 服务端有序、安全、实时三条底线分别由谁守护。【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考