Huly Core 深度指南:Huly 平台核心包库的架构、构建与二次开发实践

发布时间:2026/9/12 4:14:45

Huly Core 深度指南:Huly 平台核心包库的架构、构建与二次开发实践 Huly Core 深度指南Huly 平台核心包库的架构、构建与二次开发实践【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platformHuly Core 是从 Huly 全栈项目管理平台中抽取出来的一组核心 TypeScript 包集合承载着 Huly 生态的底层数据模型、客户端访问层、文本处理引擎与平台运行基础设施。本文以 foundations/core/README.md 为主线结合仓库中 Rush 配置 与各包源码系统讲解 Huly Core 的包组成、环境要求、基于 Rush 的安装/构建/测试/发布全流程并延伸介绍 API Client 的编程式接入方式帮助你基于这些可复用的核心包构建自定义应用或集成 Huly 能力到现有项目。Huly Core 是什么Huly Core 是 Huly 平台核心包的独立集合位于本仓库的 foundations/core 目录。它是从 Huly Platform 中抽取出的基础构件包括核心数据模型core data models、客户端库client libraries、文本处理引擎text processing engines以及平台工具集platform utilities。这些包被设计为可复用、模块化、框架无关reusable, modular, framework-agnostic其目标场景有两个在 Huly Platform 之上构建自定义应用将 Huly 功能集成进已有项目。从目录结构看foundations/core/packages 下共维护了 26 个 npm 包全部以hcengineering/作用域发布。Rush 清单 rush.json 中每个包都声明了shouldPublish: true除内部脚本包hcengineering/scripts外表明它们都是面向 npm 生态对外发布的正式产物。包清单详解Core Packages数据模型与平台运行时hcengineering/core— 核心数据模型、类型定义与平台基础抽象。该包的 入口文件 对外导出classes、hierarchy、memdb、operations、operator、query、storage、tx、backup、versioning等模块。其中 classes.ts 定义了贯穿全平台的基石类型RefT强类型文档引用、Doc所有文档的基接口包含_id、space、modifiedOn、modifiedBy等统一字段、ClassT类描述符可携带domain、extends、implements、索引配置、AttachedDoc挂载到父文档的附属文档、Space空间模型以及AccountRole、Tx、Sequence、Blob等抽象。hcengineering/platform— 平台运行时、插件系统与依赖注入。核心源码在 platform.ts 中它定义了PRIPlatform Resource Identifier机制——几乎平台中的一切都是Resource通过形如core.string.ClassLabel的字符串标识来引用翻译文本、SVG 图标等资源并提供plugin()与mergeIds()用于声明插件 ID 命名空间、Id/Plugin/IntlString/StatusCode等类型化字符串。同包还包含 i18n、metadata、event、resource、status 等基础模块。hcengineering/model— 数据模型定义与 Schema 管理。其 dsl.ts 实现了一套模型 DSL用 TypeScript 装饰器与toposort拓扑排序收集ClassTxes将类定义自动转化为一系列Tx事务作为模型元数据供服务端加载与迁移使用。Client Libraries客户端访问与同步层hcengineering/client— 客户端数据访问与同步层负责前端与后端的实时数据同步。hcengineering/client-resources— 客户端共享资源与工具。hcengineering/api-client— 面向编程式访问的 API 客户端同时支持WebSocket与REST两种协议其完整使用文档见 api-client/README.md后文有专门章节展开。hcengineering/account-client— 账号管理客户端。hcengineering/collaborator-client— 实时协作文档客户端。hcengineering/hulylake-client— HulyLake 数据仓库datalake客户端。hcengineering/analytics与hcengineering/analytics-service— 分析与埋点工具及其服务端实现。Text Processing文本处理引擎文本处理是 Huly 文档/评论体系的重要底座这组包从底层引擎到上层格式逐层分工hcengineering/text-core— 核心文本处理引擎hcengineering/text— 高层文本处理工具其 src 下包含基于 ProseMirror/TipTap 的kit、nodes、marks、markup等扩展实现hcengineering/text-html— HTML 文本的渲染与解析hcengineering/text-markdown— Markdown 支持hcengineering/text-ydoc— Yjs 文档集成为协同编辑提供 CRDT 基础。Utilities平台工具hcengineering/query— 查询语言与执行引擎hcengineering/storage与hcengineering/storage-client— 存储抽象与实现、存储客户端hcengineering/rank— 基于 LexoRank 的排序工具Rank类型定义见 classes.tshcengineering/retry— 重试逻辑与容错模式hcengineering/rpc— RPC 通信层hcengineering/token— Token 管理与认证工具在 Rush 清单中以hcengineering/server-token发布。此外foundations/core/packages 目录中还维护着 README 未单独列出、但同样对外发布的辅助包measurements、measurements-otlp可观测性指标与postgres-basePostgreSQL 基础封装均在 rush.json 的projects清单中登记。环境要求与前置条件开始构建前系统需要满足依赖要求说明Node.jsv20.11.0 或更高README 要求实际 rush.json 中声明的支持范围更宽18.20.3 19.0.0 \|\| 20.14.0 25.0.0建议以 v20 LTS 为准Rush微软的可扩展 monorepo 管理工具本仓库锁定引擎版本5.158.1包管理器使用pnpm 10.15.1Rush 的 version selector 机制会保证全局安装的任意版本在仓库内按rushVersion声明表现一致common/scripts/install-run-rush.js等脚本也会自动使用该版本。安装与构建全流程安装首先全局安装 Rushnpm install -g microsoft/rush然后在仓库根目录即 foundations/core依次执行rush install rush buildrush install会按照 rush.json 中的pnpmVersion安装本地副本的 pnpm为全部 26 个包建立统一的依赖树与符号链接rush build按拓扑依赖顺序增量构建所有包。构建与热更新常用构建命令对照rush build # 增量构建所有包利用 build cache rush rebuild # 忽略缓存全量重新构建 rush build:watch # 开发模式以 watch 模式持续构建包含 build 与 validate 阶段其中rush build:watch在开发迭代时最为常用——修改任意包的源码后依赖它的包会被自动重编译配合rushx test可以快速完成开发闭环。项目结构更新当项目结构发生变化新增包、调整依赖关系时需要重新关联并重建rush update rush buildrush update会重新解析依赖树并更新common/temp下的安装产物通常在修改 rush.json 的projects清单或各包package.json依赖后执行。故障排查构建缓存如果构建失败但代码本身没有问题常见原因是本地 build cache 损坏。此时删除缓存并全量重建rm -rf common/temp/build-cache rush rebuildRush 的构建缓存机制详见 Rush 官方 build cache 文档仓库内该缓存路径位于 common/temp 下。测试执行全部包的测试rush test若要单独运行某个包内的测试进入该包目录后执行rushx testrushx是 Rush 项目内脚本的执行入口等价于在该包上下文内运行npm test。各包根目录均配置了独立的 jest.config.js例如core、platform包都有对应的src/__tests__目录存放单元测试。包版本管理与发布Huly Core 的版本发布使用仓库级脚本bump.js完成。对单个包进行版本号递增node ./common/scripts/bump.js -p projectName其中projectName替换为要发布的包名如hcengineering/core。该脚本位于 common/scripts/bump.js属于本仓库 monorepo 的公共工具链同目录下还提供sync-versions.js、check-versions.js等版本一致性维护脚本。每个包的变更历史记录在各自的 CHANGELOG.md 中。通过 API Client 编程式接入 HulyREADME 特别指出若想以编程方式与 Huly 交互应使用 API Client。它提供覆盖全部 Huly 操作的类型化接口可用来构建集成与自定义应用。以下要点均出自该文档。两种客户端WebSocket 与 RESTWebSocket 客户端connect与 Huly 平台 API 保持长连接适合实时同步场景REST 客户端connectRest使用标准 HTTP 请求执行操作适合一次性/低频率调用。两者使用相同的连接选项import { connect } from hcengineering/api-client // 使用邮箱密码连接WebSocket const client await connect(https://huly.app, { email: johndoeexample.com, password: password, workspace: my-workspace }) // 使用完毕后关闭连接 await client.close()REST 版只需将导入改为connectRest调用方式一致import { connectRest } from hcengineering/api-client const client await connectRest(https://huly.app, { email: johndoeexample.com, password: password, workspace: my-workspace })认证方式与连接参数客户端支持两种认证方式邮箱 密码或Token。认证成功后客户端拥有与对应用户相同的资源访问权限。urlHuly 实例地址如https://huly.appworkspace目标工作区名称可在工作区 URLhttps://huly.app/workbench/workspace-name中获取token可选认证 Token与邮箱密码二选一email/password可选账号凭据。使用 Token 连接import { connect } from hcengineering/api-client const client await connect(https://huly.app, { token: ..., workspace: my-workspace })查询findOne 与 findAll两个核心检索方法均接受三个参数_class目标类结果包含其全部子类、query查询条件与options可含limit、sort、lookup、projection、total。import { SortingOrder } from hcengineering/core import contact from hcengineering/contact // 查询单个文档 const person await client.findOne(contact.class.Person, { _id: person-id }) // 批量查询 排序 限制 const persons await client.findAll( contact.class.Person, { city: New York }, { limit: 10, sort: { name: SortingOrder.Ascending } } )文档 CRUDimport contact, { AvatarType } from hcengineering/contact // 创建文档 const personId await client.createDoc(contact.class.Person, contact.space.Contacts, { name: Doe,John, city: New York, avatarType: AvatarType.COLOR }) // 更新文档 await client.updateDoc(contact.class.Person, contact.space.Contacts, personId, { city: New York }) // 删除文档 await client.removeDoc(contact.class.Person, contact.space.Contacts, personId)集合Collections操作集合用于管理AttachedDoc——即挂载到父文档上的附属文档如联系人Person下的多个联系方式Channelimport contact, { AvatarType } from hcengineering/contact // 向集合中添加附属文档 await client.addCollection( contact.class.Channel, // 附属文档类 contact.space.Contacts, // 空间 personId, // 父文档 id contact.class.Person, // 父文档类 channels, // 集合名 { provider: contact.channelProvider.Email, value: john.doeexample.com } ) // 更新集合中的附属文档 await client.updateCollection( contact.class.Channel, contact.space.Contacts, channelId, personId, contact.class.Person, channels, { city: New York } ) // 从集合中移除附属文档 await client.removeCollection( contact.class.Channel, contact.space.Contacts, channelId, personId, contact.class.Person, channels )Mixins 扩展Mixin 允许在不改变原类的情况下为已有文档动态附加属性例如给Person增加员工Employee信息import contact, { AvatarType } from hcengineering/contact // 创建 mixin await client.createMixin( personId, contact.class.Person, contact.space.Contacts, contact.mixin.Employee, { active: true, position: CEO } ) // 更新 mixin 属性 await client.updateMixin( personId, contact.class.Person, contact.space.Contacts, contact.mixin.Employee, { active: false } )从源码理解核心抽象Huly Core 的设计可以用四个关键词概括类型化 ID 字符串RefT、Plugin、IntlString、ResourceT等都是带品牌标记branded type的字符串类型在编译期提供类型安全在运行期只是普通字符串便于序列化与网络传输见 classes.ts 与 platform.ts。事务Tx驱动的数据变更所有数据修改都以Tx形式表达TxCreateDoc、TxMixin、TxApplyIf等见 tx.ts客户端与服务端通过事务流实现同步与审计。类层次与 DomainClass描述符通过extends/implements构成继承体系并通过domain字段如DOMAIN_MODEL、DOMAIN_SPACE、DOMAIN_BLOB等见 classes.ts决定数据在底层存储中的归属配合IndexKind声明索引策略。插件化资源解析plugin()与mergeIds()将每个插件声明为一段扁平命名空间运行时按 PRI 加载翻译、图标等资源实现模块解耦platform.ts。许可证与生态Huly Core 以 EPL-2.0Eclipse Public License 2.0开源。在本仓库的 monorepo 布局中foundations/core是纯核心库层与 foundations/communication、foundations/net、foundations/server 等并列上层则由 models数据模型定义、plugins业务插件、pods服务部署单元等构成完整的 Huly 平台。对于开发者而言最直接的落地路径是参照上文在 foundations/core 下完成rush install与rush build随后基于hcengineering/core的模型抽象定义自己的Class与Space通过 api-client 的 WebSocket/REST 客户端与 Huly 服务端交互再利用text-markdown、text-html等文本包处理富内容即可在 Huly 平台上搭建出具备文档、任务与实时协作能力的自定义应用。【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/9/12 4:14:45

SpringBoot影楼管理系统开发实战与架构解析

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/12 4:14:45

Redis OOM报错排查:maxmemory与内存淘汰策略实战解析

我在线上遇到过一次特别有代表性的Redis故障:业务量一上来,客户端就开始成片地抛异常,核心报错就一句话——OOM command not allowed when used memory > maxmemory。新同学第一次看到这行英文基本都是懵的:Redis不是号称高性能…

2026/9/12 4:39:48

Python tkinter Text组件选择事件深度解析与应用

1. 深入理解tkinter的Text组件与虚拟事件机制在Python GUI开发领域&#xff0c;tkinter作为标准库中的"常青树"&#xff0c;其Text组件堪称构建文本编辑功能的瑞士军刀。而<<Selection>>这个看似简单的虚拟事件&#xff0c;实则是处理文本选择操作的关键…

2026/9/12 4:39:48

Spring Boot集成asyncTool实现高并发任务编排

1. 项目概述在当今高并发的业务场景下&#xff0c;复杂任务的异步处理与编排能力已经成为后端开发的刚需。Spring Boot作为Java生态中最流行的应用框架&#xff0c;其默认的异步处理机制在面对多级依赖任务时往往显得力不从心。这正是asyncTool这类专业任务编排框架大显身手的场…

2026/9/12 4:39:47

用Grix把Codex变成群聊机器人:口袋里的技术专家

上个月我在外面出差&#xff0c;正好赶上团队群里有人贴了一段报错&#xff0c;问谁能看看。我盯着手机屏幕&#xff0c;脑子里已经排除了两个可能&#xff0c;但手边没有电脑&#xff0c;总不能靠语音给人家背代码。那天晚上我就决定&#xff0c;必须把手上这套 Codex 工作流搬…

2026/9/12 4:39:47

Rocky Linux部署ELK+Redis构建高可用日志收集系统

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/12 4:34:47

Java StringEntry接口设计与实现最佳实践

1. StringEntry接口的设计背景与核心诉求在软件开发中&#xff0c;数据结构的抽象与封装一直是提升代码复用性和可维护性的关键手段。StringEntry这个接口概念的提出&#xff0c;本质上是为了解决字符串类型数据在多种场景下的统一操作问题。我最近在重构一个历史遗留系统时&am…

2026/9/12 2:05:33

超人会飞不算本事:系统稳定依赖清晰规则与边界设计

开头先不绕弯子。“#斯坦李吐槽dc 所以超人是无缘无故会飞的嘛哈哈哈哈哈哈哈锤哥真是技术人才啊&#xff01;#雷神 #复联”这类调侃式短标题&#xff0c;第一波冲击力在于它把两个宇宙的角色塞进同一个吐槽箱里&#xff0c;但细想一下就能发现&#xff0c;它真正碰到的根本不是…

2026/9/12 3:55:12

超人VS蜘蛛侠:拆解超级IP的影响力与传播方法论

把“蜘蛛侠 vs 超人”放在 CSDN 上聊&#xff0c;可能很多人第一反应是走错片场了。但如果把这两个角色看成“两个持续运营了 80 多年的文化产品”&#xff0c;你会发现&#xff0c;这场比较本质上是两个不同 IP 策略的长期结果对比&#xff1a;超人赢在定义了整个超级英雄题材…

2026/9/9 16:31:09

基于CNN的调制信号识别:MATLAB实现时频图分类实战

简介&#xff1a;本资源是一套面向通信工程与信号处理方向学习者、研究者的深度学习实践方案&#xff0c;聚焦调制信号自动检测与识别这一典型无线通信任务&#xff0c;解决传统方法依赖人工特征、低信噪比下性能下降等痛点。压缩包共12个文件&#xff08;10.73MB&#xff09;&…

2026/9/12 0:04:17

MATLAB仿生优化框架:长鼻浣熊算法多策略融合实现

简介&#xff1a;本资源是一份面向智能优化算法研究者与MATLAB初学者的仿生智能算法实践代码包&#xff0c;聚焦于长鼻浣熊优化算法&#xff08;COA&#xff09;的多策略改进与性能验证。针对传统COA易陷局部最优、收敛精度不足等问题&#xff0c;作者融合Circle映射初始化提升…

2026/9/12 0:04:17

【JAVA毕设源码分享】基于 JavaWeb 的校园一卡通管理系统的设计与实现 基于 JavaWeb 的校园卡业务管理系统(程序+文档+代码讲解+一条龙定制)

博主介绍&#xff1a;✌️码农一枚 &#xff0c;专注于大学生项目实战开发、讲解和毕业&#x1f6a2;文撰写修改等。全栈领域优质创作者&#xff0c;博客之星、掘金/华为云/阿里云/InfoQ等平台优质作者、专注于Java、小程序技术领域和毕业项目实战 ✌️技术范围&#xff1a;&am…

2026/9/12 0:04:17

【JAVA毕设源码分享】基于 Java 的图书馆借阅管理平台的搭建与实现 基于 Java 的图书馆综合管理系统(程序+文档+代码讲解+一条龙定制)

博主介绍&#xff1a;✌️码农一枚 &#xff0c;专注于大学生项目实战开发、讲解和毕业&#x1f6a2;文撰写修改等。全栈领域优质创作者&#xff0c;博客之星、掘金/华为云/阿里云/InfoQ等平台优质作者、专注于Java、小程序技术领域和毕业项目实战 ✌️技术范围&#xff1a;&am…

2026/9/10 12:32:02

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行&#xff0c;Type-C接口算是典型的“看着简单&#xff0c;做起来全坑”的东西。光引脚就24个&#xff0c;高低速信号、电源、控制线全部塞在一个小小的连接器里&#xff0c;如果PCB布局不做规划&#xff0c;打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/10 15:19:50

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/10 15:49:53

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
咨询二维码