Univer 协议层解析univerjs/protocol 共享类型、数据契约与服务接口指南【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univeruniverjs/protocol是 Univer 全栈架构中面向跨端通信的公共协议层集中承载了各包之间共享的 TypeScript 类型、生成的服务接口与数据契约。本文将围绕该包的定位、安装方式、核心数据契约单元、工作簿、变更集、快照、权限以及面向服务端的 RPC 接口体系展开帮助你在开发 Univer 插件、服务端接入或二次扩展时快速找到正确类型、理解前后端数据结构约定并掌握版本对齐等工程要点。包定位整个 Univer 生态的共同语言Univer 的官方文档将univerjs/protocol定义为包含跨 Univer 各包共享的协议类型shared protocol types、生成的服务接口generated service interfaces与数据契约data contracts的包。它位于 packages/protocol 目录下是整个 monorepo 中最基础的只含类型、不含实现的包之一。从其 package.json 的description可以看到同样的定位Shared protocol types, generated service interfaces, and data contracts for Univer.。它自身几乎不包含业务逻辑核心价值在于前端sheets/docs/slides 等编辑器与后端快照服务、协同服务、权限服务、SSC 公式计算服务等在跨越进程边界通信时必须依赖同一份数据结构定义才能保证序列化与反序列化的严格一致。README 的 Package Overview 表给出了该包的关键属性包名UMD globalCSSLocalesFacade entryuniverjs/protocolUniverProtocol无无无这意味着它是一个纯类型/契约包不输出任何 CSS 样式、不携带国际化文案、也不提供 Facade 外观层入口若以 UMD 方式加载全局变量名为UniverProtocol。从源码目录结构可以清晰地看到它的组织方式packages/protocol/srcts/univer/面向 Univer 编辑器域的基础数据类型workbook、doc、slide、drawing、pdf、board、range、permission、changeset、snapshot、univer-file 等ts/univerpro/Univer Pro 相关的服务接口apply、ssc、ssr、helperts/universer/服务端服务接口snapshot、authz、comb、comment、file、history、license、user、access-key 等ts/univercloud/stats/统计上报相关的记录类型other/其他辅助类型如 sheet-block顶层index.ts统一汇总导出utils.ts提供isError等工具函数。安装与版本约束按照 README 的说明安装命令如下pnpm add univerjs/protocol # 或 npm install univerjs/protocol一个重要的工程约束是请让所有univerjs/*包保持在同一版本Keep alluniverjs/*packages on the same version。这是因为协议类型会随前端命令体系、服务端契约同步演进版本错位极可能导致类型不兼容或运行时序列化失败。当前仓库中该包的版本为1.0.0-beta.2见 packages/protocol/package.json在引入时应与项目其他 Univer 包使用一致的版本号。该包运行时仅依赖grpc/grpc-jsgRPC Node.js 客户端开发依赖中包含rxjs与typescript这与其服务接口采用 Observable 流式返回的设计一脉相承详见后文服务接口章节。上手使用从导入一个类型开始README 给出的最小使用示例是导入工作簿元数据类型import type { IWorkbookMeta } from univerjs/protocol;由于该包全部为类型与枚举定义通常以import type方式引入枚举与常量则需常规导入。完整的对外导出清单定义在 packages/protocol/src/index.tsL17-L220主要包括类型导出IWorkbookMeta、IWorksheetMeta、ICellData、ISheetBlock、ISnapshot、IUnit、IChangeset、ICommand、IMutation、IRange、IDocumentMeta、ISlideMeta、IPdfMeta、IBoardMeta等枚举导出CellValueType、CellType、UniverType、ErrorCode、UnitAction、UnitRole、UnitObject、ObjectScope、CommentSolvedStatus、CommentUpdateEventType、FileSource、CmdRspCode、CombCmd、IRecordType等服务接口导出ISnapshotService、IAuthzService、ICombService、ICommentService、IFileService、IHistoryService、ILicenseService、IUserService、IAccessKeyService、ICollaborationHelperService等工具函数isError。一个非常实用的辅助函数是 src/utils.ts 中的isErrorimport { isError } from univerjs/protocol; // 判断一个响应是否为错误响应 if (isError(response.error)) { // 处理错误 }从源码注释可以看到它的设计动机服务端Universer返回的错误有时缺少code字段且 HTTP 场景下错误码可能是字符串而非数字因此它同时容忍ErrorCode.OK数字 1与字符串OK两种情况utils.ts。核心数据契约编辑器域的基础类型ts/univer/目录定义了前端与服务端都要遵守的基础数据结构是理解整个协议层的钥匙。单元Unit体系UniverType 与 IUnitUniver 将每一种可编辑的文档对象抽象为单元Unit。UniverType枚举constants/univer.ts定义了一共八种单元类型枚举值数值含义UNIVER_UNKNOWN0未知类型UNIVER_DOC1文档UNIVER_SHEET2电子表格UNIVER_SLIDE3演示文稿UNIVER_PROJECT4项目UNIVER_BASE5基础数据BaseUNIVER_BOARD6画板UNIVER_PDF7PDFUNRECOGNIZED-1未识别IUnituniver-file.ts是单元的通用外壳包含unitID、name、type并可按类型携带对应的元数据workbook、document、drawing、pdf四者其一均为可选字段。工作簿协议IWorkbookMeta / IWorksheetMeta / ICellData / ISheetBlockts/univer/workbook.ts是表格域最核心的契约文件workbook.tsIWorksheetMetaL29-L37工作表元数据包含type、id、name、rowCount、columnCount以及以Uint8Array形式存储的originalMeta原始 JSON 元数据不含单元格数据IWorkbookMetaL39-L56工作簿元数据包含unitID、rev版本号、creator、name、sheetOrder工作表顺序、sheets以 sheet id 为键的IWorksheetMeta映射、resources、blockMeta与originalMetaICellDataL65-L86单元格数据结构。其v字段承载值对象strV/numV/boolVt为CellValueType另有富文本pIDocumentMeta、样式s、公式f、公式 refIdsi、公式引用ref如A1:B2数组公式反向表示以及 Excel 新公式前缀xf如_xlfn.、_xlws.、_xludf.ISheetBlockL88-L94工作表数据分块blockid由后端生成以startRow/endRow标记行区间data为Uint8Array二进制数据。这是为超大表格按行块懒加载设计的传输单元ISheetBlockMetaL96-L100则记录了每个 sheet 的 block id 列表。CellValueTypeL20-L27枚举定义了单元格值的类型UNKNOWN、STRING、NUMBER、BOOLEAN、FORCE_STRING强制字符串以及 protobuf 风格的UNRECOGNIZED -1。与之配套的CellType枚举见 initial-sheet.ts则从 sheet 行模型角度定义了单元格类型。快照与版本ISnapshotISnapshotsnapshot.ts代表一个单元在某个rev下的完整存档export interface ISnapshot { unitID: string; type: UniverType; rev: number; workbook: IWorkbookMeta | undefined; doc: IDocumentMeta | undefined; slide: ISlideMeta | undefined; board: IBoardMeta | undefined; pdf?: IPdfMeta | undefined; }快照与服务端版本号rev强绑定是快照 增量变更集存储模型的基础打开文档时先取快照再通过变更集追平到最新版本。变更集IChangeset / IMutation / ICommand协同编辑的核心增量单位是IChangesetchangeset.tsexport interface IChangeset { unitID: string; type: UniverType; baseRev: number; // 基于哪个版本 revision: number; // 应用后的新版本 userID: string; mutations: IMutation[]; memberID: string; sid?: string; // 编辑会话 id与 reqId 配对 reqId?: number; // 会话内单调递增、从 1 开始 mutationSize?: number; // 所有 mutation 的总字节数 additionalFields?: string; // 预留字段 createTime?: number; }其中IMutation与ICommandL20-L33结构一致都只有id与data序列化后的参数两个字段源码注释明确指出它们必须与前端命令体系中的ICommandInfo/ICommand保持一致——这正是协议包要保证前后端同一份定义的典型例子。sid/reqId机制用于标识一次编辑会话中的连续操作同一会话内reqId单调递增并从 1 开始服务端据此做幂等与乱序处理。引用范围IRangeIRangerange.ts定义了表格中一个矩形区域包含startRow、endRow、startColumn、endColumn四个必填字段以及可选的unitId、sheetId用于跨单元/跨工作表定位范围。错误契约ErrorCode 与 IError错误码体系定义在 constants/errors.ts 中采用分域编号的方式组织L17-L134域数值区间代表错误通用0–9OK(1)、INTERNAL_ERROR(2)、PERMISSION_DENIED(3)、NOT_FOUND(4)、UNAUTHENTICATED(5)、INVALID_ARGUMENT(7) 等登录10–16LOGIN_FAILED、验证码不匹配/过期等业务通用100–101CURRENT_STATUS_CANNOT_OPERATE、ERROR_AGAIN用户200 段USER_NOT_FOUND(201)、USER_IS_ANONYMOUS(202)变更集5000 段CHANGESET_REVISION_CONFILICT(5001)快照6000 段SNAPSHOT_INVALID_SNAPSHOT(6001)、SNAPSHOT_HAS_BEEN_REMOVED(6002) 等应用层7000 段APPLY_REJECT(7001)、APPLY_NON_SEQUENTIAL_REVISION(7002)、APPLY_REVISION_CONFILICT(7003)、APPLY_DUPLICATED(7005) 等连接器8000 段CONNECTOR_DATA_TOO_LARGE(8001)License9000 段LICENSE_MAX_UNITS_EXCEEDED、LICENSE_DISTRO_REJECTED等其他域10000Yuumi AI、Python 运行时、邀请码、支付、兑换码、数据源等IError由code与message组成而isError工具函数则负责在兼容各种不标准返回的情况下判断响应是否出错详见前文。权限与协作协议权限枚举体系UnitAction / UnitRole / UnitObject / ObjectScopepermission.ts 定义了完整的权限模型UnitActionL17-L92可执行的操作覆盖查看View、编辑Edit、评论Comment、复制Copy、分享Share、导出Export、排序Sort、筛选Filter、数据透视PivotTable、超链接InsertHyperlink以及细粒度的行/列/单元格操作SetCellValue、SetCellStyle、InsertRow、DeleteColumn等。注意其中一部分工作表级操作MoveWorksheet、DeleteWorksheet、CreateWorksheet等已被标记为deprecated被更细粒度的MoveSheet(25)、DeleteSheet(26)、CreateSheet(30) 等取代UnitRoleL94-L99角色三档——Reader(0)、Editor(1)、Owner(2)UnitObjectL101-L124权限作用对象从Workbook、Worksheet、SelectRange到Document、Slide、Base、Board、Pdf以及文档段落、幻灯片元素、Base 表/字段/记录等细粒度对象ObjectScopeL133-L138权限范围——SomeCollaborator部分协作者、AllCollaborator全部协作者、OneSelf仅自己。配合IUnitRoleKVrolename与IUseruserID/name/avatar即可完整描述谁、在什么对象上、可以做什么的授权模型。协同消息与服务colla-msg.ts定义协同消息ICollaMsg与各类事件如加入/离开ICollaMsgJoin/ICollaMsgLeave、评论更新ICommentUpdate、光标更新IUpdateCursor、权限对象更新IUpdatePermissionObj、直播协同切换 HostILiveShareNewHost、Uniscript 运行IUniscriptRun、连接关闭IShouldCloseConn等并导出CommentSolvedStatus、CommentUpdateEventType两个枚举universer/v1/comb.ts实时协同服务ICombService提供加入/离开协同房间ICombJoinRequest/ICombLeaveRequest与增量变更INewChangesRequest/INewChangesResponse接口并导出CombCmd、CmdRspCode等命令与响应码枚举。服务接口前后端 RPC 契约README 提到的 generated service interfaces 在ts/universer/与ts/univerpro/两个目录中体现得最充分。这些接口的方法签名以ObservableT作为返回类型、以grpc/grpc-js的Metadata作为可选请求元数据明显面向 gRPC 风格的流式调用从 snapshot.ts 的接口签名可见。universer/v1服务端核心服务ISnapshotServiceuniverser/v1/snapshot.ts是最核心的服务方法覆盖单元与文档的完整生命周期单元管理CreateUnit、UpdateUnit、ListUnits、DeleteUnits支持hardDelete永久删除、RecoverUnits、ForkUnit、CopyFileMeta变更集SaveChangeset响应中的concurrent字段返回需要跟随的并发变更集、FetchMissingChangesetsfrom为开区间、to为闭区间to 0表示取到最新、GetLatestCsReqIdBySid、MGetChangesetsByRevision快照SaveSnapshot同版本已存在则忽略、UpdateSnapshot、GetSnapshot、GetLatestSnapshotRevision、EnsureSnapshot、GetUnitOnRev返回最接近指定版本的快照 需跟随的变更集分块数据SaveSheetBlock、GetSheetBlock支撑超大型表格的按块加载其他GetResources、DirectWrite以指定用户身份直接写入、GetSheetTableInfo/GetSheetTable、GetUnitMeta/MGetUnitMeta、GetSnapshotMetaWithPreCalculated获取预计算结果、ReportUnitRoutingStats。IAuthzServiceauthz.ts授权服务提供Create、UpdatePermPoint、ListPermPoint、ListRoles、Allowed/BatchAllowed以及协作者管理CreateCollaborator、ListCollaborator、PutCollaborators、DeleteCollaborator、UpdateCollaborator等接口配合IPermissionPoint、ICollaborator等类型ICommentServicecomment.ts评论服务AddComment、EditComment、ReplyComment、DeleteComment、ListComments、SolvedComment配套IThread、IReply类型IFileServicefile.ts文件服务IFileUploadRequest并导出FileSource枚举文件来源IHistoryServicehistory.ts历史记录服务CreateHistory、GetHistoryCsILicenseServicelicense.tsLicense 校验服务GetUserLicenseIAccessKeyServiceaccess-key.ts访问密钥服务IUserServiceuser.ts用户服务GetUser、ListUsers、GetSessionTicket、Migrate。univerpro/v1 与统计apply.ts单元创建/应用类接口的请求响应类型包括ICreateUnitRequest支持idempotencyKey幂等键、metaData透传、templateID、initialSheets、docContent等、ICreateUnitResponse、IForkUnitRequest/Response、IDirectWriteRequest/Response、IPreloadUnitRequest/Response、IDisposeRequest/Response、IEnsureSnapshotRequest/Response、IGetUnitRawContentRequest/Response与IWorkbookCreateMetassc.ts公式/数据计算相关接口IComputeRequest/Response、IGetValuesRequest/Response、IGetPreprocessRangesRequest/Response、ITableInfoList——SSC 是 Univer 的公式预计算服务其输出通过快照接口中的GetSnapshotMetaWithPreCalculated回流到快照元数据中ssr.ts服务端渲染相关IGetSSRRequest/Responsehelper.tsICollaborationHelperService协同辅助服务以及ICreateLatestSnapshotInBackgroundRequest/Response后台创建最新快照univercloud/stats/v1/stats.tsIRecord与IRecordType用于统计记录上报。工程化配置速览在接入或贡献该包时可参考 package.json 中的关键工程信息导出映射开发态exports直接将.与./*映射到src下对应文件发布态publishConfig则分别映射到lib/es/index.jsimport、lib/cjs/index.jsrequire与lib/types/index.d.ts类型并支持./lib/*深层路径构建脚本pnpm builduniver-cli buildbundle tsc -p tsconfig.node.json类型声明另有typecheck、testvitest、coverage等脚本运行依赖仅grpc/grpc-js说明协议层本身不引入业务运行时负担服务接口的Observable/Metadata类型即来自 rxjs 与 grpc 生态许可Apache-2.0由 DreamNum Co., Ltd. 维护。总结univerjs/protocol看似是一个只有类型定义的轻量包实则是 Univer 前后端协同的契约基石从UniverType/IUnit的单元抽象到IWorkbookMeta/ICellData/ISheetBlock的表格数据结构再到IChangeset/ISnapshot的版本与增量模型、UnitAction/UnitRole的权限模型以及ISnapshotService/IAuthzService/ICombService等一整套服务端 RPC 接口——所有跨端数据交换都在这份协议上展开。在开发中记住三点即可快速上手类型一律从univerjs/protocol统一导入保持所有univerjs/*包版本一致判断服务端响应是否出错使用isError工具而不是直接比较错误码以兼容数字/字符串两种编码涉及服务端交互快照、变更集、权限、协同时以universer/v1与univerpro/v1下的服务接口契约为准其请求/响应类型是编写前端 adapter 或后端网关的直接依据。【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Univer 协议层解析：@univerjs/protocol 共享类型、数据契约与服务接口指南
Univer 协议层解析univerjs/protocol 共享类型、数据契约与服务接口指南【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univeruniverjs/protocol是 Univer 全栈架构中面向跨端通信的公共协议层集中承载了各包之间共享的 TypeScript 类型、生成的服务接口与数据契约。本文将围绕该包的定位、安装方式、核心数据契约单元、工作簿、变更集、快照、权限以及面向服务端的 RPC 接口体系展开帮助你在开发 Univer 插件、服务端接入或二次扩展时快速找到正确类型、理解前后端数据结构约定并掌握版本对齐等工程要点。包定位整个 Univer 生态的共同语言Univer 的官方文档将univerjs/protocol定义为包含跨 Univer 各包共享的协议类型shared protocol types、生成的服务接口generated service interfaces与数据契约data contracts的包。它位于 packages/protocol 目录下是整个 monorepo 中最基础的只含类型、不含实现的包之一。从其 package.json 的description可以看到同样的定位Shared protocol types, generated service interfaces, and data contracts for Univer.。它自身几乎不包含业务逻辑核心价值在于前端sheets/docs/slides 等编辑器与后端快照服务、协同服务、权限服务、SSC 公式计算服务等在跨越进程边界通信时必须依赖同一份数据结构定义才能保证序列化与反序列化的严格一致。README 的 Package Overview 表给出了该包的关键属性包名UMD globalCSSLocalesFacade entryuniverjs/protocolUniverProtocol无无无这意味着它是一个纯类型/契约包不输出任何 CSS 样式、不携带国际化文案、也不提供 Facade 外观层入口若以 UMD 方式加载全局变量名为UniverProtocol。从源码目录结构可以清晰地看到它的组织方式packages/protocol/srcts/univer/面向 Univer 编辑器域的基础数据类型workbook、doc、slide、drawing、pdf、board、range、permission、changeset、snapshot、univer-file 等ts/univerpro/Univer Pro 相关的服务接口apply、ssc、ssr、helperts/universer/服务端服务接口snapshot、authz、comb、comment、file、history、license、user、access-key 等ts/univercloud/stats/统计上报相关的记录类型other/其他辅助类型如 sheet-block顶层index.ts统一汇总导出utils.ts提供isError等工具函数。安装与版本约束按照 README 的说明安装命令如下pnpm add univerjs/protocol # 或 npm install univerjs/protocol一个重要的工程约束是请让所有univerjs/*包保持在同一版本Keep alluniverjs/*packages on the same version。这是因为协议类型会随前端命令体系、服务端契约同步演进版本错位极可能导致类型不兼容或运行时序列化失败。当前仓库中该包的版本为1.0.0-beta.2见 packages/protocol/package.json在引入时应与项目其他 Univer 包使用一致的版本号。该包运行时仅依赖grpc/grpc-jsgRPC Node.js 客户端开发依赖中包含rxjs与typescript这与其服务接口采用 Observable 流式返回的设计一脉相承详见后文服务接口章节。上手使用从导入一个类型开始README 给出的最小使用示例是导入工作簿元数据类型import type { IWorkbookMeta } from univerjs/protocol;由于该包全部为类型与枚举定义通常以import type方式引入枚举与常量则需常规导入。完整的对外导出清单定义在 packages/protocol/src/index.tsL17-L220主要包括类型导出IWorkbookMeta、IWorksheetMeta、ICellData、ISheetBlock、ISnapshot、IUnit、IChangeset、ICommand、IMutation、IRange、IDocumentMeta、ISlideMeta、IPdfMeta、IBoardMeta等枚举导出CellValueType、CellType、UniverType、ErrorCode、UnitAction、UnitRole、UnitObject、ObjectScope、CommentSolvedStatus、CommentUpdateEventType、FileSource、CmdRspCode、CombCmd、IRecordType等服务接口导出ISnapshotService、IAuthzService、ICombService、ICommentService、IFileService、IHistoryService、ILicenseService、IUserService、IAccessKeyService、ICollaborationHelperService等工具函数isError。一个非常实用的辅助函数是 src/utils.ts 中的isErrorimport { isError } from univerjs/protocol; // 判断一个响应是否为错误响应 if (isError(response.error)) { // 处理错误 }从源码注释可以看到它的设计动机服务端Universer返回的错误有时缺少code字段且 HTTP 场景下错误码可能是字符串而非数字因此它同时容忍ErrorCode.OK数字 1与字符串OK两种情况utils.ts。核心数据契约编辑器域的基础类型ts/univer/目录定义了前端与服务端都要遵守的基础数据结构是理解整个协议层的钥匙。单元Unit体系UniverType 与 IUnitUniver 将每一种可编辑的文档对象抽象为单元Unit。UniverType枚举constants/univer.ts定义了一共八种单元类型枚举值数值含义UNIVER_UNKNOWN0未知类型UNIVER_DOC1文档UNIVER_SHEET2电子表格UNIVER_SLIDE3演示文稿UNIVER_PROJECT4项目UNIVER_BASE5基础数据BaseUNIVER_BOARD6画板UNIVER_PDF7PDFUNRECOGNIZED-1未识别IUnituniver-file.ts是单元的通用外壳包含unitID、name、type并可按类型携带对应的元数据workbook、document、drawing、pdf四者其一均为可选字段。工作簿协议IWorkbookMeta / IWorksheetMeta / ICellData / ISheetBlockts/univer/workbook.ts是表格域最核心的契约文件workbook.tsIWorksheetMetaL29-L37工作表元数据包含type、id、name、rowCount、columnCount以及以Uint8Array形式存储的originalMeta原始 JSON 元数据不含单元格数据IWorkbookMetaL39-L56工作簿元数据包含unitID、rev版本号、creator、name、sheetOrder工作表顺序、sheets以 sheet id 为键的IWorksheetMeta映射、resources、blockMeta与originalMetaICellDataL65-L86单元格数据结构。其v字段承载值对象strV/numV/boolVt为CellValueType另有富文本pIDocumentMeta、样式s、公式f、公式 refIdsi、公式引用ref如A1:B2数组公式反向表示以及 Excel 新公式前缀xf如_xlfn.、_xlws.、_xludf.ISheetBlockL88-L94工作表数据分块blockid由后端生成以startRow/endRow标记行区间data为Uint8Array二进制数据。这是为超大表格按行块懒加载设计的传输单元ISheetBlockMetaL96-L100则记录了每个 sheet 的 block id 列表。CellValueTypeL20-L27枚举定义了单元格值的类型UNKNOWN、STRING、NUMBER、BOOLEAN、FORCE_STRING强制字符串以及 protobuf 风格的UNRECOGNIZED -1。与之配套的CellType枚举见 initial-sheet.ts则从 sheet 行模型角度定义了单元格类型。快照与版本ISnapshotISnapshotsnapshot.ts代表一个单元在某个rev下的完整存档export interface ISnapshot { unitID: string; type: UniverType; rev: number; workbook: IWorkbookMeta | undefined; doc: IDocumentMeta | undefined; slide: ISlideMeta | undefined; board: IBoardMeta | undefined; pdf?: IPdfMeta | undefined; }快照与服务端版本号rev强绑定是快照 增量变更集存储模型的基础打开文档时先取快照再通过变更集追平到最新版本。变更集IChangeset / IMutation / ICommand协同编辑的核心增量单位是IChangesetchangeset.tsexport interface IChangeset { unitID: string; type: UniverType; baseRev: number; // 基于哪个版本 revision: number; // 应用后的新版本 userID: string; mutations: IMutation[]; memberID: string; sid?: string; // 编辑会话 id与 reqId 配对 reqId?: number; // 会话内单调递增、从 1 开始 mutationSize?: number; // 所有 mutation 的总字节数 additionalFields?: string; // 预留字段 createTime?: number; }其中IMutation与ICommandL20-L33结构一致都只有id与data序列化后的参数两个字段源码注释明确指出它们必须与前端命令体系中的ICommandInfo/ICommand保持一致——这正是协议包要保证前后端同一份定义的典型例子。sid/reqId机制用于标识一次编辑会话中的连续操作同一会话内reqId单调递增并从 1 开始服务端据此做幂等与乱序处理。引用范围IRangeIRangerange.ts定义了表格中一个矩形区域包含startRow、endRow、startColumn、endColumn四个必填字段以及可选的unitId、sheetId用于跨单元/跨工作表定位范围。错误契约ErrorCode 与 IError错误码体系定义在 constants/errors.ts 中采用分域编号的方式组织L17-L134域数值区间代表错误通用0–9OK(1)、INTERNAL_ERROR(2)、PERMISSION_DENIED(3)、NOT_FOUND(4)、UNAUTHENTICATED(5)、INVALID_ARGUMENT(7) 等登录10–16LOGIN_FAILED、验证码不匹配/过期等业务通用100–101CURRENT_STATUS_CANNOT_OPERATE、ERROR_AGAIN用户200 段USER_NOT_FOUND(201)、USER_IS_ANONYMOUS(202)变更集5000 段CHANGESET_REVISION_CONFILICT(5001)快照6000 段SNAPSHOT_INVALID_SNAPSHOT(6001)、SNAPSHOT_HAS_BEEN_REMOVED(6002) 等应用层7000 段APPLY_REJECT(7001)、APPLY_NON_SEQUENTIAL_REVISION(7002)、APPLY_REVISION_CONFILICT(7003)、APPLY_DUPLICATED(7005) 等连接器8000 段CONNECTOR_DATA_TOO_LARGE(8001)License9000 段LICENSE_MAX_UNITS_EXCEEDED、LICENSE_DISTRO_REJECTED等其他域10000Yuumi AI、Python 运行时、邀请码、支付、兑换码、数据源等IError由code与message组成而isError工具函数则负责在兼容各种不标准返回的情况下判断响应是否出错详见前文。权限与协作协议权限枚举体系UnitAction / UnitRole / UnitObject / ObjectScopepermission.ts 定义了完整的权限模型UnitActionL17-L92可执行的操作覆盖查看View、编辑Edit、评论Comment、复制Copy、分享Share、导出Export、排序Sort、筛选Filter、数据透视PivotTable、超链接InsertHyperlink以及细粒度的行/列/单元格操作SetCellValue、SetCellStyle、InsertRow、DeleteColumn等。注意其中一部分工作表级操作MoveWorksheet、DeleteWorksheet、CreateWorksheet等已被标记为deprecated被更细粒度的MoveSheet(25)、DeleteSheet(26)、CreateSheet(30) 等取代UnitRoleL94-L99角色三档——Reader(0)、Editor(1)、Owner(2)UnitObjectL101-L124权限作用对象从Workbook、Worksheet、SelectRange到Document、Slide、Base、Board、Pdf以及文档段落、幻灯片元素、Base 表/字段/记录等细粒度对象ObjectScopeL133-L138权限范围——SomeCollaborator部分协作者、AllCollaborator全部协作者、OneSelf仅自己。配合IUnitRoleKVrolename与IUseruserID/name/avatar即可完整描述谁、在什么对象上、可以做什么的授权模型。协同消息与服务colla-msg.ts定义协同消息ICollaMsg与各类事件如加入/离开ICollaMsgJoin/ICollaMsgLeave、评论更新ICommentUpdate、光标更新IUpdateCursor、权限对象更新IUpdatePermissionObj、直播协同切换 HostILiveShareNewHost、Uniscript 运行IUniscriptRun、连接关闭IShouldCloseConn等并导出CommentSolvedStatus、CommentUpdateEventType两个枚举universer/v1/comb.ts实时协同服务ICombService提供加入/离开协同房间ICombJoinRequest/ICombLeaveRequest与增量变更INewChangesRequest/INewChangesResponse接口并导出CombCmd、CmdRspCode等命令与响应码枚举。服务接口前后端 RPC 契约README 提到的 generated service interfaces 在ts/universer/与ts/univerpro/两个目录中体现得最充分。这些接口的方法签名以ObservableT作为返回类型、以grpc/grpc-js的Metadata作为可选请求元数据明显面向 gRPC 风格的流式调用从 snapshot.ts 的接口签名可见。universer/v1服务端核心服务ISnapshotServiceuniverser/v1/snapshot.ts是最核心的服务方法覆盖单元与文档的完整生命周期单元管理CreateUnit、UpdateUnit、ListUnits、DeleteUnits支持hardDelete永久删除、RecoverUnits、ForkUnit、CopyFileMeta变更集SaveChangeset响应中的concurrent字段返回需要跟随的并发变更集、FetchMissingChangesetsfrom为开区间、to为闭区间to 0表示取到最新、GetLatestCsReqIdBySid、MGetChangesetsByRevision快照SaveSnapshot同版本已存在则忽略、UpdateSnapshot、GetSnapshot、GetLatestSnapshotRevision、EnsureSnapshot、GetUnitOnRev返回最接近指定版本的快照 需跟随的变更集分块数据SaveSheetBlock、GetSheetBlock支撑超大型表格的按块加载其他GetResources、DirectWrite以指定用户身份直接写入、GetSheetTableInfo/GetSheetTable、GetUnitMeta/MGetUnitMeta、GetSnapshotMetaWithPreCalculated获取预计算结果、ReportUnitRoutingStats。IAuthzServiceauthz.ts授权服务提供Create、UpdatePermPoint、ListPermPoint、ListRoles、Allowed/BatchAllowed以及协作者管理CreateCollaborator、ListCollaborator、PutCollaborators、DeleteCollaborator、UpdateCollaborator等接口配合IPermissionPoint、ICollaborator等类型ICommentServicecomment.ts评论服务AddComment、EditComment、ReplyComment、DeleteComment、ListComments、SolvedComment配套IThread、IReply类型IFileServicefile.ts文件服务IFileUploadRequest并导出FileSource枚举文件来源IHistoryServicehistory.ts历史记录服务CreateHistory、GetHistoryCsILicenseServicelicense.tsLicense 校验服务GetUserLicenseIAccessKeyServiceaccess-key.ts访问密钥服务IUserServiceuser.ts用户服务GetUser、ListUsers、GetSessionTicket、Migrate。univerpro/v1 与统计apply.ts单元创建/应用类接口的请求响应类型包括ICreateUnitRequest支持idempotencyKey幂等键、metaData透传、templateID、initialSheets、docContent等、ICreateUnitResponse、IForkUnitRequest/Response、IDirectWriteRequest/Response、IPreloadUnitRequest/Response、IDisposeRequest/Response、IEnsureSnapshotRequest/Response、IGetUnitRawContentRequest/Response与IWorkbookCreateMetassc.ts公式/数据计算相关接口IComputeRequest/Response、IGetValuesRequest/Response、IGetPreprocessRangesRequest/Response、ITableInfoList——SSC 是 Univer 的公式预计算服务其输出通过快照接口中的GetSnapshotMetaWithPreCalculated回流到快照元数据中ssr.ts服务端渲染相关IGetSSRRequest/Responsehelper.tsICollaborationHelperService协同辅助服务以及ICreateLatestSnapshotInBackgroundRequest/Response后台创建最新快照univercloud/stats/v1/stats.tsIRecord与IRecordType用于统计记录上报。工程化配置速览在接入或贡献该包时可参考 package.json 中的关键工程信息导出映射开发态exports直接将.与./*映射到src下对应文件发布态publishConfig则分别映射到lib/es/index.jsimport、lib/cjs/index.jsrequire与lib/types/index.d.ts类型并支持./lib/*深层路径构建脚本pnpm builduniver-cli buildbundle tsc -p tsconfig.node.json类型声明另有typecheck、testvitest、coverage等脚本运行依赖仅grpc/grpc-js说明协议层本身不引入业务运行时负担服务接口的Observable/Metadata类型即来自 rxjs 与 grpc 生态许可Apache-2.0由 DreamNum Co., Ltd. 维护。总结univerjs/protocol看似是一个只有类型定义的轻量包实则是 Univer 前后端协同的契约基石从UniverType/IUnit的单元抽象到IWorkbookMeta/ICellData/ISheetBlock的表格数据结构再到IChangeset/ISnapshot的版本与增量模型、UnitAction/UnitRole的权限模型以及ISnapshotService/IAuthzService/ICombService等一整套服务端 RPC 接口——所有跨端数据交换都在这份协议上展开。在开发中记住三点即可快速上手类型一律从univerjs/protocol统一导入保持所有univerjs/*包版本一致判断服务端响应是否出错使用isError工具而不是直接比较错误码以兼容数字/字符串两种编码涉及服务端交互快照、变更集、权限、协同时以universer/v1与univerpro/v1下的服务接口契约为准其请求/响应类型是编写前端 adapter 或后端网关的直接依据。【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考