hcengineering/core 核心包演进解读从 CHANGELOG 看 Huly 平台的权限、事务与限流架构【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platformfoundations/core/packages/core/CHANGELOG.md记录了 Huly 平台All-in-One Project Management Platform见根目录 README.md最底层核心包hcengineering/core的历次发布。该包定义了整个平台的数据模型、事务Tx协议、权限模型与存储抽象是 Huly 众多插件tracker、chunter、document 等共同依赖的地基。阅读本文你将理解 CHANGELOG 中每一条补丁背后的源码实现掌握 workspace 权限、事务访问级别、密码老化、自定义属性 ID 等机制在 classes.ts、tx.ts、utils.ts 中的落地方式并了解如何借助 clone.test.ts 等测试用例验证这些能力。一、包定位为什么核心包演进牵一发而动全身hcengineering/core位于 foundations/core/packages/core版本号 0.7.26见 package.json许可协议为 EPL-2.0。它对外提供数据模型基类Doc、Class、Ref、Space、Account等核心类型定义于 classes.ts事务协议Tx、TxCreateDoc、TxUpdateDoc、TxApplyIf等事务类型定义于 tx.ts存储抽象Storage、TxStorage及内存实现memdb见 storage.ts、memdb.ts客户端连接Client、WithTx等接口见 client.ts类型系统与查询Hierarchyhierarchy.ts、DocumentQuery与操作符operator.ts、query.ts。从依赖关系看它依赖hcengineering/platform、hcengineering/analytics、hcengineering/measurements等更基础的能力包同时被server-core、account-client以及各业务模型models 目录广泛引用。因此 CHANGELOG 中任何一条补丁——哪怕是调整接口或更新依赖——都可能影响整个平台的行为这也是核心包演进值得逐条解读的原因。二、CHANGELOG 全量速览原文按时间倒序列出从 2026-02-22 的 0.7.26 回溯到 2021-08-04 的 0.7.0 的全部发布。下表整理了近期版本与补丁摘要便于对照后文展开版本发布时间Patches 摘要0.7.262026-02-22新增 workspace permission 枚举修复对象克隆0.7.232025-11-26新增密码老化password aging0.7.222025-11-06权限Permission新增txMatch字段0.7.212025-10-30扩展TxAccessLevel0.7.202025-10-30新增 workspace 用量信息0.7.192025-10-29连接建立时在 traces 中挂起suspend异常0.7.182025-10-27属性支持 RankLexoRank 排序0.7.102025-10-21为自定义属性增量 ID 新增TypeIdentifier0.7.82025-10-15调整接口adjusted interfaces0.7.72025-10-14更新依赖0.7.62025-10-11升级到最新 platform rig0.7.52025-10-09Hierarchy 改进0.7.42025-10-08修复时间限流器time rate limiter问题0.7.0多次2021-08事务排序、workspace 服务端支持、服务端连接修复、memdb/hierarchy文档等下面按权限与访问控制数据与类型系统基础工具与可靠性三条主线展开解读。三、权限与访问控制WorkspacePermission、txMatch 与 TxAccessLevel3.1 Workspace permission 枚举0.7.260.7.26 的第一条补丁是Add workspace permission enum。虽然枚举定义最终落在与核心包相邻的hcengineering/account-client见 foundations/core/packages/account-client/src/client.ts但核心包 CHANGELOG 之所以记录它是因为 workspace 级权限已成为平台账号体系的基础能力。对应的客户端方法揭示了它的用法batchAssignWorkspacePermission: (params: { accountIds: AccountUuid[], permission: string }) Promisevoid batchRevokeWorkspacePermission: (params: { accountIds: AccountUuid[], permission: string }) Promisevoid hasWorkspacePermission: (params: { accountId: AccountUuid, permission: string }) Promiseboolean getWorkspacePermissions: (params: { accountId: AccountUuid, permission: string }) PromiseWorkspaceUuid[]从源码结构可以推断workspace 权限以字符串枚举的形式存在permission: string支持批量授予/批量撤销、按账号查询是否拥有某权限以及按权限枚举账号可见的 workspace 列表。它与传统的基于Space/Role的细粒度权限见下文的Permission、Role互补workspace 权限是更粗粒度的、由账号服务集中管理的开关适合控制能否访问某个工作区这类全局能力。3.2 Permission.txMatch把权限判定下沉到事务匹配0.7.220.7.22 的补丁Add txMatch to permission在 classes.ts 的Permission接口中新增了可选字段export interface Permission extends Doc { label: IntlString txClass?: RefClassTx forbid?: boolean objectClass?: RefClassDoc scope?: space | workspace txMatch?: DocumentQueryTx description?: IntlString icon?: Asset }逐字段解释其语义label权限在界面上的显示文案txClass该权限约束的事务类型如只约束TxCreateDocforbid标记为禁止型权限默认是允许型objectClass权限作用的目标对象类scope作用域是空间级space还是工作区级workspacetxMatch0.7.22 新增——一个针对Tx的DocumentQueryTx用于对事务做条件匹配icon权限的图标资源。txMatch的价值在于把权限判定从按对象类一刀切升级为按事务内容精确匹配。例如可以构造一条查询限定仅当TxCreateDoc的objectSpace属于某集合时才允许执行从而在不新增权限类型的前提下表达更精细的策略。它与txClass、objectClass一起构成了一个可组合的权限判定条件集。围绕权限体系同一文件还定义了AttributePermission针对单个属性含attribute: RefAnyAttribute、ClassPermission针对目标类含targetClass、ModulePermissionGroup按应用模块分组、绑定AccountRole以及Role/RolesAssignmentclasses.ts——后者说明空间内通过角色-权限列表的方式为成员分配权限。3.3 扩展 TxAccessLevel0.7.210.7.21 的extend TxAccessLevel指向 classes.ts 中的 mixin 接口export interface TxAccessLevel extends ClassDoc { createAccessLevel?: AccountRole removeAccessLevel?: AccountRole updateAccessLevel?: AccountRole isIdentity?: boolean }它把谁可以增删改某类文档绑定到AccountRole账号角色。AccountRole枚举classes.ts定义了从低到高的角色谱系export enum AccountRole { ReadOnlyGuest READONLYGUEST, DocGuest DocGuest, Guest GUEST, User USER, Maintainer MAINTAINER, Owner OWNER, Admin ADMIN }并通过roleOrderclasses.ts给出角色间的相对权重ReadOnlyGuest5 … Admin100供系统比较当前角色是否达到某操作的准入级别。TxAccessLevel作为ClassDoc的 mixin 被注册进核心组件见 component.ts这意味着任意模型类都可以混入该能力声明各自的创建/删除/更新准入角色同时isIdentity用于标记身份类文档。3.4 密码老化与 workspace 用量信息0.7.23 / 0.7.200.7.23 的Add password aging在WorkspaceInfo上新增字段classes.tsexport interface WorkspaceInfo { uuid: WorkspaceUuid dataId?: WorkspaceDataId name: string url: string region?: string branding?: string createdOn: number createdBy?: PersonUuid billingAccount?: PersonUuid allowReadOnlyGuest?: boolean allowGuestSignUp?: boolean passwordAgingRule?: number | null // in days pendingConfiguration?: WorkspaceConfiguration | null }passwordAgingRule的单位是天数语义是要求用户每隔 N 天轮换密码null表示不启用强制过期。它放在 workspace 维度而非账号维度说明密码策略是按工作区配置的。0.7.20 的add workspace usage info则体现在WorkspaceInfoWithStatus与UsageStatusclasses.tsexport interface UsageStatus { usage: Recordstring, number startTime: Timestamp updateTime: Timestamp limitsExceededSince?: Timestamp }usage是指标名 → 用量的字典limitsExceededSince记录了用量首次超过套餐限额的时间点可供计费与告警系统判断超限时长。同一接口族还包含BackupStatus备份数据量、blob 量、最近备份时间等与WorkspaceMode状态机从pending、migrating到archiving-done、delete-done见 classes.ts 附近共同构成 workspace 生命周期管理的数据基础。四、数据与类型系统TypeIdentifier、Rank 与 Hierarchy4.1 TypeIdentifier自定义属性的增量 ID0.7.100.7.10 的Add TypeIdentifier for custom attribute incremental IDs对应 classes.tsexport interface TypeIdentifier extends Typestring { of: RefCustomSequence }它继承Typestring字符串类型额外携带of: RefCustomSequence指向一个自定义序列。CustomSequenceclasses.ts是带prefix的序列export interface Sequence extends Doc { attachedTo: RefClassDoc sequence: number } export interface CustomSequence extends Sequence { prefix: string }组合理解当一个自定义属性需要递增且带前缀的标识如工单号REQ-0001时用TypeIdentifier声明该属性并指定其递增序列来源平台根据CustomSequence.prefix与当前sequence值生成下一个 ID。这样不需要为每个业务模型手写计数逻辑且 ID 在平台层面全局统一。TypeIdentifier已注册为核心组件之一component.ts。4.2 Rank属性排序0.7.180.7.18 的Rank for attributes引入了Rank类型。在 classes.ts 中/** * String representation of LexoRank type */ export type Rank string注释明确其底层是LexoRank字符串表示。LexoRank 的核心思想是在两个相邻排序位之间总是存在一个中间字符串因此可以在不重排整表的情况下插入新元素。在 classes.ts 处Doc基类或相关接口出现了可选的rank?: Rank字段并配套定义了TypeRank类型classes.ts。典型应用场景是看板列、任务列表的手动拖拽排序——用户把卡片拖到任意位置只需为该元素计算一个新的 Rank 字符串而不必批量更新其后所有元素的序号。4.3 Hierarchy 改进0.7.50.7.5 的Hierarchy improvements涉及 hierarchy.ts 中的Hierarchy类类定义见 hierarchy.ts。从源码结构可以推断Hierarchy维护模型类 → 父类/mixin/属性的继承图谱负责回答某类是否派生自某类某属性由哪个类声明等问题是类型系统与序列化_class判定、mixin 展开的核心支撑。该版本的改进主要围绕继承关系的解析正确性其重要性与 2021 年 8 月首次补充hierarchy.ts文档一脉相承——后者正是 0.7.0 系列补丁 Addhierarchy.tsdocs 的内容。五、事务机制Tx、TxProcessor 与事务排序5.1 事务模型回顾CHANGELOG 在 0.7.0 时代记录了Transaction ordering事务排序与Server support for workspacesworkspace 服务端支持。理解这两条补丁需要先看 tx.ts 的事务骨架export interface Tx extends Doc { objectSpace: RefSpace meta?: Recordstring, string | number | boolean }Tx是所有事务的基类objectSpace指明事务操作的目标空间meta存放不落库的元信息。派生类型包括TxCUD带objectId/objectClass/attachedTo等 CUD 上下文tx.tsTxCreateDoc创建文档携带attributes: DataTtx.tsTxApplyIf条件事务——只有match全部命中且notMatch全部不命中时才执行tx列表且同一scope同时只允许一个操作执行tx.tsTxWorkspaceEvent/TxDomainEvent服务端广播事件升级计划、索引更新、安全变更等见 tx.ts。TxProcessortx.ts是一个抽象类其tx()方法按_class分发到txCreateDoc/txUpdateDoc/txRemoveDoc/txMixinTxApplyIf注明在服务端处理。TxFactorytx.ts负责按账号与派生标志生成事务createTxCreateDoc()会填充_id、space普通事务空间core.space.Tx或派生事务空间core.space.DerivedTx、时间戳与操作人。5.2 事务排序与对象克隆的关联0.7.0 / 0.7.26Transaction ordering 保障同一对象上的事务按顺序应用——这在多客户端并发写、离线同步回放场景下至关重要。而事务回放依赖文档重建TxProcessor.createDoc2Doc()tx.ts正是把TxCreateDoc还原为文档对象的入口其默认对tx.attributes执行clone(tx.attributes)。这就直接联系到 0.7.26 的第二条补丁Fix object cloneclone实现位于 clone.ts签名如下export function clone ( obj: any, as?: (doc: any, m: any) any, needAs?: (value: any) any | undefined, depth?: number ): any行为要点与 clone.test.ts 的用例一一对应undefined、函数、null、原始类型按原样返回测试第 20-23 行断言clone(123) 123Date重新new Date(obj.getTime())拷贝保证副本是独立实例测试第 27-31 行数组与对象深度递归嵌套对象/数组/日期均创建新实例断言cloned ! arr且cloned[2] ! arr[2]测试第 34-56 行支持depth参数限制克隆深度depth 0时直接返回原对象depth 1只克隆第一层测试第 61-64 行验证深度行为as/needAs回调允许在克隆过程中做类型转换是objvalue、mixin 应用等场景的扩展钩子。由于createDoc2Doc在每次事务回放时都会克隆属性数据clone的边界情况原型属性遍历、深层嵌套、深度截断会直接影响内存数据库memdb与同步客户端重建文档的正确性——这正是 0.7.26 把修复对象克隆与新增权限枚举并列发布的原因核心包的任意底层修复都值得全量发布。六、基础工具与可靠性限流器、trace 与 memdb6.1 修复时间限流器问题0.7.40.7.4 的Fix issue with time rate limiter涉及 utils.ts 中的两个限流器RateLimiterutils.ts并发数限流。构造函数接收rate最大并发数exec()在processingQueue.size rate时挂起等待任务完成后从队列移除并唤醒下一个等待者add()是非阻塞变体可传errHandlerwaitProcessing()等待队列清空。TimeRateLimiterutils.ts时间窗口限流。构造函数(rate, period 1000)表示每个period毫秒内最多执行rate次exec()通过executions数组记录每个任务的开始时间与运行状态cleanupExecutions()按now - time period淘汰过期记录等待时按period / rate的间隔轮询。它修复前的问题从源码可推断清理逻辑与等待策略的边界条件例如活跃任务与历史记录计数不一致、唤醒不及时容易在低频高并发下造成限流失效或死等测试见 limiter-edge-cases.test.ts覆盖RateLimiter(1)、TimeRateLimiter(2, 1000)等边界构造与混合操作场景。这类限流器在平台中用于控制对外部服务邮件、通知、外部 API的调用速率。6.2 连接异常在 traces 中挂起0.7.190.7.19 的Suspend exceptions from connect in traces是可靠性改进客户端/服务端建立连接connect阶段抛出的异常不再污染 trace 输出而是被挂起/抑制避免把预期中的连接失败重试误报为错误告警。这与核心包的Status体系status.ts配合——Status是平台错误与状态的统一载体连接阶段的状态转换更适合以可预期的方式处理。6.3 memdb 与存储抽象2021 年 8 月 0.7.0 系列补丁中包含Addmemdbdocs、Add missed docs、Add documentation与Fix server connection。memdbmemdb.ts是纯内存的TxStorage实现它按事务回放更新文档如 memdb.ts 所示通过TxProcessor.createDoc2Doc(tx)生成文档并入库同时维护Tx序列。它是客户端缓存的基石——Huly 前端把服务端事务流同步到本地memdb实现离线可用的文档读写与乐观更新。Fix server connection与 0.7.0 系列早期的fix、npmigonre、Minor changes for publish则属于发布与连接层的工程修补说明核心包在 2021 年 8 月经历了密集的发布打磨期。6.4 接口调整与依赖治理0.7.8 / 0.7.7 / 0.7.6adjusted interfaces0.7.8对公开接口做兼容性微调。从源码推断这类调整通常发生在classes.ts/tx.ts的接口定义层属于改动小但影响面广的补丁因此单独成版发布。update deps0.7.7更新依赖版本如hcengineering/platform、analytics、measurements的 workspace 依赖版本号见 package.json。Update to latest platform rig0.7.6升级构建工具链hcengineering/platform-rigworkspace 版本^0.7.21。rig是 Huly 各包共用的 TypeScript/ESLint/Prettier/Jest 工程配置集合升级它意味着统一的编译与校验规则同步更新。这些补丁共同体现了核心包的语义化版本纪律构建、依赖、文档、接口调整各自独立成版方便下游包通过版本号精确追踪影响面。七、如何验证这些能力hcengineering/core自带完整测试套件tests目录可作为理解与验证上述机制的入口克隆语义clone.test.ts 覆盖原始值、Date、数组、对象、深度参数与函数引用限流边界limiter-edge-cases.test.ts 覆盖RateLimiter/TimeRateLimiter的内存管理与边界条件查询与操作符operator.test.ts、operator-bugs.test.ts、query.test.ts 验证DocumentQuery的匹配语义事务与层级hierarchy.test.ts、collaboration.test.ts、contexts.test.ts 覆盖类型系统与协作场景内存库memdb.test.ts、minmodel.ts 用最小模型验证事务回放正确性。运行测试的方式与各包一致使用仓库统一的rush工作流common/scripts/install-run-rush.js提供安装入口包内npm test即jest --passWithNoTests --silent --coverage见 package.json即可执行。八、演进主线小结把 CHANGELOG 纵向串起来可以看到hcengineering/core的三条演进主线权限模型持续收紧从 2021 年 workspace 服务端支持到 0.7.20 用量信息、0.7.21TxAccessLevel扩展、0.7.22txMatch精确匹配、0.7.23 密码老化、0.7.26 workspace 权限枚举——平台从能访问演进到精细控制谁能做什么、多久必须换密码、用量是否超限。数据能力向增量与有序演进TypeIdentifier0.7.10与Rank0.7.18分别解决自定义属性的自增 ID 与可插入排序问题配合Hierarchy改进0.7.5使模型层更灵活。底层可靠性持续加固限流器修复0.7.4、连接异常 trace 抑制0.7.19、对象克隆修复0.7.26每一项都对应 utils.ts 或 clone.ts 中可验证的实现并有对应测试用例守护。对于希望深入 Huly 平台的开发者CHANGELOG.md 是一份高质量的源码地图每条补丁都能在 classes.ts、tx.ts、utils.ts 中找到落点值得作为阅读核心包的索引持续跟踪。【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考