开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载导读workspace/willCreateFiles是 Language Server ProtocolLSP3.16 起引入的文件操作file operations能力之一它允许语言服务器在客户端真正创建文件之前介入处理服务器收到该请求后可以返回一份WorkspaceEdit由客户端在创建文件前应用到工作区从而实现对新建文件这一动作的前置联动例如同步更新导入语句、生成配套资源。本文以本仓库 LSP 3.19 规范 为骨架结合 3.19 metaModel 与 initialize 能力协商章节 的源码级定义完整讲解该请求的语义、能力协商、参数结构、响应约定以及配套的didCreateFiles通知并给出可直接套用的 TypeScript 接口与 JSON-RPC 示例帮助语言服务器开发者快速实现创建文件前置处理能力。一、背景LSP 文件操作消息族文件操作消息族是 LSP 3.16 引入的一组消息用于让客户端在用户操作或应用 WorkspaceEdit触发文件创建、重命名、删除时及时通知服务器。本仓库 3.19 目录下与之对应的规范文档包括前置请求will 系列均为 client-to-server 请求可返回WorkspaceEditwillCreateFiles、willRenameFiles、willDeleteFiles事后通知did 系列均为 client-to-server 通知didCreateFiles、didRenameFiles、didDeleteFilesworkspace/willCreateFiles属于其中创建文件分支的前置请求语义上与其他 will 系列请求对称在文件真正被创建之前由客户端发送给服务器。二、请求语义为什么需要创建前拦截根据 willCreateFiles 规范原文The will create files request is sent from the client to the server before files are actually created as long as the creation is triggered from within the client either by a user action or by applying a workspace edit.要点如下触发时机客户端在真正创建文件之前发送该请求且前提是创建动作由客户端内部触发——要么是用户操作如在资源管理器里新建文件要么是应用一份 WorkspaceEdit。返回可应用请求可以返回一份WorkspaceEdit客户端会在创建文件之前将其应用到工作区。内容不可改写由于这份WorkspaceEdit在文件创建前应用而目标文件此时尚不存在因此它不能操作待创建文件的内容——只能对工作区中已存在的资源做修改例如向现有文件插入导入语句、更新索引文件等。可靠性约束客户端可能丢弃计算结果——如果计算这份编辑耗时过长或者服务器在该请求上持续失败。这是为了保持创建操作快速且可靠keep creates fast and reliable。这一前置拦截 事后通知的设计让服务器在文件尚未落盘时就能提前修正依赖它的其他文件避免出现文件已创建但引用未更新的窗口期。三、能力协商Client Capability 与 Server Capabilityworkspace/willCreateFiles的启用依赖初始化阶段initialize的能力协商。规范中定义了两侧能力Client Capability客户端声明支持属性名可选workspace.fileOperations.willCreate属性类型boolean该能力表示客户端支持发送workspace/willCreateFiles请求。完整的客户端能力类型FileOperationClientCapabilities在 initialize.md 中有完整定义export interface FileOperationClientCapabilities { /** * Whether the client supports dynamic registration for * file requests/notifications. */ dynamicRegistration?: boolean; /** * The client has support for sending didCreateFiles notifications. */ didCreate?: boolean; /** * The client has support for sending willCreateFiles requests. */ willCreate?: boolean; /** * The client has support for sending didRenameFiles notifications. */ didRename?: boolean; /** * The client has support for sending willRenameFiles requests. */ willRename?: boolean; /** * The client has support for sending didDeleteFiles notifications. */ didDelete?: boolean; /** * The client has support for sending willDeleteFiles requests. */ willDelete?: boolean; }Server Capability服务器声明支持属性名可选workspace.fileOperations.willCreate属性类型FileOperationRegistrationOptions对应地服务器的FileOperationOptions在 initialize.md 中定义为export interface FileOperationOptions { /** * The server is interested in receiving didCreateFiles notifications. */ didCreate?: FileOperationRegistrationOptions; /** * The server is interested in receiving willCreateFiles requests. */ willCreate?: FileOperationRegistrationOptions; /** * The server is interested in receiving didRenameFiles notifications. */ didRename?: FileOperationRegistrationOptions; /** * The server is interested in receiving willRenameFiles requests. */ willRename?: FileOperationRegistrationOptions; /** * The server is interested in receiving didDeleteFiles file notifications. */ didDelete?: FileOperationRegistrationOptions; /** * The server is interested in receiving willDeleteFiles file requests. */ willDelete?: FileOperationRegistrationOptions; }在 metaModel.json 中workspace/willCreateFiles消息定义第 655-684 行也明确标注了两侧能力属性名均为workspace.fileOperations.willCreatemessageDirection为clientToServersince为3.16.0{ method: workspace/willCreateFiles, typeName: WillCreateFilesRequest, result: { kind: or, items: [ { kind: reference, name: WorkspaceEdit }, { kind: base, name: null } ]}, messageDirection: clientToServer, clientCapability: workspace.fileOperations.willCreate, serverCapability: workspace.fileOperations.willCreate, params: { kind: reference, name: CreateFilesParams }, registrationOptions: { kind: reference, name: FileOperationRegistrationOptions }, since: 3.16.0 }Registration Options本请求在规范中明确标注为none即没有额外的注册选项——注册过滤条件全部由FileOperationRegistrationOptions承担。四、核心类型拆解FileOperationRegistrationOptions 及其过滤体系服务器声明workspace.fileOperations.willCreate能力时值类型为FileOperationRegistrationOptions它用于描述服务器对哪些文件操作感兴趣。其完整类型体系定义在 willCreateFiles 规范文档 中共四层1. FileOperationRegistrationOptions顶层/** * The options to register for file operations. * * since 3.16.0 */ interface FileOperationRegistrationOptions { /** * The actual filters. */ filters: FileOperationFilter[]; }服务器通过一组过滤器filters声明自己关心的文件操作范围。2. FileOperationFilter过滤器/** * A filter to describe in which file operation requests or notifications * the server is interested in. * * since 3.16.0 */ export interface FileOperationFilter { /** * A URI scheme, like file or untitled. */ scheme?: string; /** * The actual file operation pattern. */ pattern: FileOperationPattern; }scheme可选URI scheme例如file或untitled。不设置时默认匹配全部 schemepattern必填实际的文件操作模式。3. FileOperationPattern模式/** * A pattern to describe in which file operation requests or notifications * the server is interested in. * * since 3.16.0 */ interface FileOperationPattern { /** * The glob pattern to match. ... */ glob: string; /** * Whether to match files or folders with this pattern. * * Matches both if undefined. */ matches?: FileOperationPatternKind; /** * Additional options used during matching. */ options?: FileOperationPatternOptions; }glob必填glob 匹配模式语法细节见下文matches可选限定只匹配文件file或只匹配文件夹folder不设置时两者都匹配options可选匹配期间的附加选项。4. FileOperationPatternKind匹配对象类型export namespace FileOperationPatternKind { /** * The pattern matches a file only. */ export const file: file file; /** * The pattern matches a folder only. */ export const folder: folder folder; } export type FileOperationPatternKind file | folder;5. FileOperationPatternOptions匹配选项/** * Matching options for the file operation pattern. * * since 3.16.0 */ export interface FileOperationPatternOptions { /** * The pattern should be matched ignoring casing. */ ignoreCase?: boolean; }目前该类型仅有一个可选属性ignoreCase置为true时匹配忽略大小写。6. glob 语法速查规范对glob字段支持的语法给出了明确的六种形式语法含义示例*匹配路径段内零个或多个字符src/*.js?匹配路径段内一个字符src/?.ts**匹配任意数量的路径段含零个**/*.go{}将子模式组合为 OR 表达式**/*.{ts,js}匹配所有 TypeScript 和 JavaScript 文件[]声明路径段内要匹配的字符范围example.[0-9]匹配example.0、example.1……[!...]否定路径段内的字符范围example.[!0-9]匹配example.a、example.b但不匹配example.0这些类型同样完整出现在 metaModel.json 的类型定义区如FileOperationPattern位于第 10215 行起FileOperationFilter位于第 7325 行起可供各语言绑定自动生成类型代码。五、请求参数CreateFilesParams 与 FileCreateworkspace/willCreateFiles的请求参数类型为CreateFilesParams定义如下/** * The parameters sent in notifications/requests for user-initiated creation * of files. * * since 3.16.0 */ export interface CreateFilesParams { /** * An array of all files/folders created in this operation. */ files: FileCreate[]; }其中单个条目FileCreate定义如下/** * Represents information on a file/folder create. * * since 3.16.0 */ export interface FileCreate { /** * A file:// URI for the location of the file/folder being created. */ uri: string; }注意两点files是一个数组因为一次用户操作可能同时创建多个文件/文件夹每个条目只携带一个urifile://scheme 的绝对 URI不含任何内容——这正呼应了前文该请求不能操作待创建文件内容的语义约束。参数中未包含文件内容服务器即使想写内容也没有载体只能通过返回的WorkspaceEdit修改工作区中已有的文件。六、响应约定WorkspaceEdit | null 与错误处理Response的契约在 willCreateFiles 规范文档 中定义resultWorkspaceEdit|null返回WorkspaceEdit客户端在创建文件之前将其应用到工作区只能影响已存在的资源返回null服务器对该次创建无需任何前置修改。error当willCreateFiles请求处理过程中发生异常时设置 error code 与 message。也就是说服务器对该请求的正常答案要么是一份要应用的编辑要么是 null表示不做干预出现异常时才走 error 分支。WorkspaceEdit的完整结构changes/documentChanges两个字段可参见 metaModel.json 中 WorkspaceEdit 定义 以及 types/workspaceEdit.md。七、客户端丢弃结果的机制快速与可靠优先规范原文特别强调客户端可能会丢弃计算结果如果计算这份编辑耗时过长computing the edit took too long服务器在该请求上持续失败a server constantly fails on this request。这是保持创建快速可靠keep creates fast and reliable的兜底策略文件创建属于高频且对延迟敏感的操作客户端不会无限期等待服务器响应。因此服务器实现willCreateFiles时应当处理逻辑保持轻量、快速避免在请求内做重量级全量索引等耗时操作对失败要有快速返回能力宁可返回null也不要长时间阻塞不要把关键业务逻辑强依赖在该请求的返回值上因为客户端可能在任何时候丢弃结果。八、完整实战示例场景假设一个 Go 语言服务器当用户在客户端新建一个.go文件时服务器希望在创建前把该文件加入工程索引清单修改已有的go.mod或索引文件并联动更新同目录的doc.go文档引用。能力协商initialize 响应{ capabilities: { workspace: { fileOperations: { willCreate: { filters: [ { pattern: { glob: **/*.go, matches: file } } ] } } } } }该配置声明服务器只对**/*.go文件的创建感兴趣matches: file限定为文件而非文件夹其他路径下的文件创建不会触发willCreateFiles。请求client → server{ jsonrpc: 2.0, id: 1, method: workspace/willCreateFiles, params: { files: [ { uri: file:///home/user/project/src/server/handler.go } ] } }响应server → client{ jsonrpc: 2.0, id: 1, result: { documentChanges: [ { textDocument: { uri: file:///home/user/project/go.mod, version: 42 }, edits: [ { range: { start: { line: 3, character: 0 }, end: { line: 3, character: 0 } }, newText: // managed by language server\n } ] } ] } }这份WorkspaceEdit只修改已存在的go.mod绝不携带handler.go的内容——这与规范不能操作待创建文件内容的约束一致。客户端会在真正创建handler.go之前应用该编辑。如果服务器判断无需任何前置修改直接返回result: null即可。九、配套通知didCreateFiles创建完成后的配套通知是workspace/didCreateFiles定义在 didCreateFiles.md触发时机客户端内部发生文件创建后客户端向服务器发送通知方法workspace/didCreateFiles参数与请求相同复用CreateFilesParamsfiles: FileCreate[]能力协商客户端能力workspace.fileOperations.didCreateboolean服务器能力workspace.fileOperations.didCreateFileOperationRegistrationOptions。它属于通知:arrow_right:没有响应。典型用法是服务器在文件真正创建后更新自己的内存索引、触发重新解析等。需要注意willCreate与didCreate是两个独立的能力开关服务器可以只注册其中一个。十、与 will 系列其他请求的关联同属 will 系列的前置请求还有willRenameFiles方法workspace/willRenameFiles参数RenameFilesParamsfiles: FileRename[]每个条目含oldUri与newUri重命名文件夹时只包含文件夹本身不包含其子项willDeleteFiles方法workspace/willDeleteFiles参数DeleteFilesParamsfiles: FileDelete[]。三者语义完全对称均在文件操作真正发生前发送、均可返回WorkspaceEdit、均有客户端可能丢弃结果的可靠性约束、都使用FileOperationRegistrationOptions作为服务器能力值类型。而本主题的willCreateFiles是其中参数结构最简单的一个——每个条目仅一个uri字段这也体现了创建操作在文件操作族中的基础性。十一、参考资料索引规范原文workspace/willCreateFiles.md配套通知workspace/didCreateFiles.md兄弟请求workspace/willRenameFiles.md、workspace/willDeleteFiles.md能力协商定义general/initialize.mdFileOperationClientCapabilities与 general/initialize.mdFileOperationOptions机器可读定义metaModel/metaModel.jsonworkspace/willCreateFiles消息、第 3489 行起CreateFilesParams、第 10215 行起FileOperationPattern、第 11688 行起FileOperationOptions、第 12154 行起FileOperationClientCapabilities相关类型types/workspaceEdit.md以上 3.19 目录下的定义同时存在于 3.17 与 3.18 目录文件操作消息族自 3.16 引入后保持稳定如需对照早期版本可查看 3.17 willCreateFiles 与 3.18 willCreateFiles。赞分享开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载相关推荐LSP 3.19 文件操作协议详解workspace/willDeleteFiles 删除拦截请求实战指南LSP 3.19 文件操作协议详解workspace/willDeleteFiles 删除拦截请求实战指南 workspace/willDeleteFiles开发工具Language Server Protocol 3.18 文件操作协议详解workspace/willCreateFiles 请求的机制与实现Language Server Protocol 3.18 文件操作协议详解workspace/willCreateFiles 请求的机制与实现 导读 本文基开发工具LSP workspace/willRenameFiles 请求详解在文件重命名前拦截并注入 WorkspaceEdit 的协议机制LSP workspace/willRenameFiles 请求详解在文件重命名前拦截并注入 WorkspaceEdit 的协议机制 导读 workspace开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考