尧图网站建设 
开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载导读workspace/didChangeConfiguration是 LSPLanguage Server Protocol中由客户端编辑器/IDE主动向语言服务器发送的通知notification用于告知服务器用户的配置设置已经发生变化。本文基于 language-server-protocol 仓库中 3.17 版规范 的权威定义系统讲解该通知的协议格式、客户端能力声明、参数结构并与 3.6.0 引入的workspace/configuration拉取模型pull model进行对比。读完本文你将掌握如何在客户端正确触发配置变更通知、如何在服务器端注册与响应以及如何用拉取模型替代传统的推送模型来获取最新配置。一、通知概览客户端到服务器的单向配置信号workspace/didChangeConfiguration是一条从客户端发往服务器的通知notification方向为client → server规范中用标记其作用正如官方文档所述A notification sent from the client to the server to signal the change of configuration settings.即当用户在客户端修改了设置settings后客户端通过该通知把变更后的完整配置内容推送给服务器服务器收到后可以据此更新自己的行为例如调整格式化选项、补全偏好、诊断开关等。与请求request不同通知不需要服务器返回响应因此它是一条单向、无应答的消息。在 specification.md 中该通知与workspace/configuration请求、workspace/didChangeWatchedFiles等一起归属于 workspace 功能域。二、消息格式方法名与参数结构2.1 方法名method该通知使用的方法名为workspace/didChangeConfiguration2.2 参数类型DidChangeConfigurationParams通知的参数类型为DidChangeConfigurationParams在 didChangeConfiguration.md 中定义如下interface DidChangeConfigurationParams { /** * The actual changed settings */ settings: LSPAny; }settings实际发生变更后的完整配置内容类型为LSPAny。LSPAny是 LSP 3.17 引入的通用类型表示任意 LSP 数据类型可以容纳对象object、数组、字符串、数字、布尔值甚至null。由于它是整个协议中通用的任意值载体在 metaModel.json 中大量用于data?: LSPAny等字段例如代码补全、CodeLens、悬停等请求的透传数据因此settings字段对配置的具体结构不做任何限制——完全由客户端与服务端双方自行约定。一个典型的 JSON-RPC 消息体形如{ jsonrpc: 2.0, method: workspace/didChangeConfiguration, params: { settings: { editor: { tabSize: 4, insertSpaces: true }, languageServer: { lint: { enabled: true, severity: warning } } } } }注意settings携带的是变更后的完整配置快照而不是变更了哪些字段的增量信息。协议本身不保证配置的具体 schema服务器需要具备对任意结构配置的容错能力。三、客户端能力声明DidChangeConfigurationClientCapabilities与所有 LSP 功能一样客户端是否支持该通知需要在initialize阶段的ClientCapabilities中显式声明。规范中该能力的属性路径为workspace.didChangeConfiguration其属性类型为DidChangeConfigurationClientCapabilitiesexport interface DidChangeConfigurationClientCapabilities { /** * Did change configuration notification supports dynamic registration. * * since 3.6.0 to support the new pull model. */ dynamicRegistration?: boolean; }能力字段说明字段类型必选含义dynamicRegistrationboolean否该通知是否支持动态注册dynamic registration即服务器是否可以在运行时通过client/registerCapability请求动态注册/注销对该通知的兴趣。该字段自3.6.0起引入目的是配合新的配置拉取模型详见下文第五节。在 metaModel.json 的结构化元数据中DidChangeConfigurationClientCapabilities同样被建模为仅包含可选布尔字段dynamicRegistration的类型与 Markdown 规范保持完全一致。一个完整的初始化握手示例客户端声明其支持该通知{ jsonrpc: 2.0, id: 1, method: initialize, params: { capabilities: { workspace: { didChangeConfiguration: { dynamicRegistration: true } } } } }四、动态注册DidChangeConfigurationRegistrationOptions在dynamicRegistration为true的前提下服务器可以通过client/registerCapability在运行时动态注册对该通知的监听。从 metaModel.json 可以看到注册选项类型DidChangeConfigurationRegistrationOptions{ name: DidChangeConfigurationRegistrationOptions, properties: [ { name: section, type: { kind: or, items: [ { kind: base, name: string }, { kind: array, element: { kind: base, name: string } } ] }, optional: true } ] }即注册选项包含一个可选的section字段类型为string | string[]用于指定服务器关心的配置节section。这允许服务器只对特定配置节的变化做出反应而不是盲目接收全部配置。五、推送模型 vs 拉取模型与workspace/configuration的关系理解workspace/didChangeConfiguration的关键在于它隶属于 LSP 配置机制中的推送模型push model而 3.6.0 之后协议又提供了**拉取模型pull model**作为替代。规范在 configuration.md 中对此有明确说明This pull model replaces the old push model were the client signaled configuration change via an event.两者的对比如下维度推送模型workspace/didChangeConfiguration拉取模型workspace/configuration方向客户端 → 服务器通知无响应服务器 → 客户端请求有响应触发时机客户端配置变化时主动推送服务器按需批量获取携带内容settings: LSPAny完整配置快照ConfigurationItem[]列表可一次请求多项引入版本1.0 起推送模型的传统机制3.6.0在拉取模型中服务器通过workspace/configuration请求向客户端批量获取配置响应结果为LSPAny[]返回顺序与请求中的ConfigurationItem顺序一一对应。每个ConfigurationItem包含export interface ConfigurationItem { /** * The scope to get the configuration section for. */ scopeUri?: URI; /** * The configuration section asked for. */ section?: string; }section要获取的配置节如cpp.formatterOptions由服务器自行定义不必与客户端内部的配置存储结构一致——例如服务器请求cpp.formatterOptions而客户端可能以 XML 或其他布局存储配置转换工作由客户端负责。scopeUri配置的作用域资源 URI。若提供客户端应返回限定到该资源的作用域配置若客户端无法为给定作用域提供配置则响应数组中对应位置必须为null。为什么推送模型仍然需要保留规范明确指出拉取模型取代了旧的推送模型。但服务器如果在拉取模型下缓存了workspace/configuration的结果仍然需要一种方式获知配置变了、缓存已失效。为此规范给出的做法是——仍然注册一个空empty的配置变更通知connection.client.register(DidChangeConfigurationNotification.type, undefined);这段代码出自 configuration.md的含义是服务器以空注册选项注册workspace/didChangeConfiguration通知undefined表示不关心具体section客户端在配置发生任何变化时都会发送该通知服务器收到通知后虽然不使用通知中的settings数据因为拉取模型下应再次发起workspace/configuration请求获取权威配置但借此获知配置已变化从而失效本地缓存并重新拉取。这正是dynamicRegistration字段注释中 since 3.6.0 to support the new pull model 的用意动态注册机制使得拉取模型下的服务器可以按需订阅配置变化事件而不必在初始化时静态声明。六、服务器端典型处理流程综合推送与拉取两种模型一个现代 LSP 服务器处理配置变更的推荐流程如下初始化阶段读取客户端在initialize中声明的workspace.didChangeConfiguration能力。注册阶段若能力可用服务器调用client/registerCapability以空选项或指定section注册DidChangeConfigurationNotification。通知处理阶段收到workspace/didChangeConfiguration时在纯推送模型下直接解析params.settings更新服务器内部状态在拉取模型下忽略settings内容将其仅视为缓存失效信号随后发起workspace/configuration请求按需重新拉取所需配置节。作用域处理结合scopeUri语义对不同资源返回不同配置例如按文件路径返回 EditorConfig 等作用域配置未提供的项以null占位。七、版本演进与元数据佐证该通知自协议早期版本即存在属配置推送机制的基础消息dynamicRegistration字段自3.6.0起为支持拉取模型而引入在 3.18 版本的 didChangeConfiguration.md 中DidChangeConfigurationParams.settings的注释更新为 The actual changed settings.3.17 版为 The actual changed settings协议内容保持一致结构化元数据 metaModel.json 中完整建模了DidChangeConfigurationParams含settings: LSPAny、DidChangeConfigurationClientCapabilities含可选dynamicRegistration以及DidChangeConfigurationRegistrationOptions含可选section: string | string[]三类类型是机器可读的规范等价物可用于代码生成、协议校验与工具链开发。八、实战要点小结方向不可逆workspace/didChangeConfiguration只允许客户端发往服务器服务器不可反向发送。settings 是快照而非增量客户端发送的是变更后的完整配置服务器不应假设其与上一次发送内容存在可比较的增量关系。LSPAny 意味着零约束settings的具体 schema 完全由客户端与服务端协商服务器应对未知字段保持宽容。推送与拉取可共存即使使用拉取模型获取配置也建议保留一个空注册的didChangeConfiguration通知作为配置已变化的失效信号避免本地缓存过期。能力声明必不可少客户端必须在initialize的workspace.didChangeConfiguration中声明能力服务器才能合法地依赖该通知支持动态注册的客户端应同时上报dynamicRegistration: true。赞分享开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载相关推荐深入解析 Biome 的 Markdown 格式化setext 标题与跨行 HTML 的边界处理example-59 用例剖析深入解析 Biome 的 Markdown 格式化setext 标题与跨行 HTML 的边界处理example 59 用例剖析 导读 本文以 Biome开发工具Language Server Protocol 文件删除事件workspace/didDeleteFiles 通知详解Language Server Protocol 文件删除事件workspace/didDeleteFiles 通知详解 导读 workspace/didDe开发工具Language Server Protocol 文件创建事件通知workspace/didCreateFiles 消息规范与实现解析Language Server Protocol 文件创建事件通知workspace/didCreateFiles 消息规范与实现解析 导读 workspac开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Language Server Protocol 配置变更通知 `workspace/didChangeConfiguration` 全解析
开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载导读workspace/didChangeConfiguration是 LSPLanguage Server Protocol中由客户端编辑器/IDE主动向语言服务器发送的通知notification用于告知服务器用户的配置设置已经发生变化。本文基于 language-server-protocol 仓库中 3.17 版规范 的权威定义系统讲解该通知的协议格式、客户端能力声明、参数结构并与 3.6.0 引入的workspace/configuration拉取模型pull model进行对比。读完本文你将掌握如何在客户端正确触发配置变更通知、如何在服务器端注册与响应以及如何用拉取模型替代传统的推送模型来获取最新配置。一、通知概览客户端到服务器的单向配置信号workspace/didChangeConfiguration是一条从客户端发往服务器的通知notification方向为client → server规范中用标记其作用正如官方文档所述A notification sent from the client to the server to signal the change of configuration settings.即当用户在客户端修改了设置settings后客户端通过该通知把变更后的完整配置内容推送给服务器服务器收到后可以据此更新自己的行为例如调整格式化选项、补全偏好、诊断开关等。与请求request不同通知不需要服务器返回响应因此它是一条单向、无应答的消息。在 specification.md 中该通知与workspace/configuration请求、workspace/didChangeWatchedFiles等一起归属于 workspace 功能域。二、消息格式方法名与参数结构2.1 方法名method该通知使用的方法名为workspace/didChangeConfiguration2.2 参数类型DidChangeConfigurationParams通知的参数类型为DidChangeConfigurationParams在 didChangeConfiguration.md 中定义如下interface DidChangeConfigurationParams { /** * The actual changed settings */ settings: LSPAny; }settings实际发生变更后的完整配置内容类型为LSPAny。LSPAny是 LSP 3.17 引入的通用类型表示任意 LSP 数据类型可以容纳对象object、数组、字符串、数字、布尔值甚至null。由于它是整个协议中通用的任意值载体在 metaModel.json 中大量用于data?: LSPAny等字段例如代码补全、CodeLens、悬停等请求的透传数据因此settings字段对配置的具体结构不做任何限制——完全由客户端与服务端双方自行约定。一个典型的 JSON-RPC 消息体形如{ jsonrpc: 2.0, method: workspace/didChangeConfiguration, params: { settings: { editor: { tabSize: 4, insertSpaces: true }, languageServer: { lint: { enabled: true, severity: warning } } } } }注意settings携带的是变更后的完整配置快照而不是变更了哪些字段的增量信息。协议本身不保证配置的具体 schema服务器需要具备对任意结构配置的容错能力。三、客户端能力声明DidChangeConfigurationClientCapabilities与所有 LSP 功能一样客户端是否支持该通知需要在initialize阶段的ClientCapabilities中显式声明。规范中该能力的属性路径为workspace.didChangeConfiguration其属性类型为DidChangeConfigurationClientCapabilitiesexport interface DidChangeConfigurationClientCapabilities { /** * Did change configuration notification supports dynamic registration. * * since 3.6.0 to support the new pull model. */ dynamicRegistration?: boolean; }能力字段说明字段类型必选含义dynamicRegistrationboolean否该通知是否支持动态注册dynamic registration即服务器是否可以在运行时通过client/registerCapability请求动态注册/注销对该通知的兴趣。该字段自3.6.0起引入目的是配合新的配置拉取模型详见下文第五节。在 metaModel.json 的结构化元数据中DidChangeConfigurationClientCapabilities同样被建模为仅包含可选布尔字段dynamicRegistration的类型与 Markdown 规范保持完全一致。一个完整的初始化握手示例客户端声明其支持该通知{ jsonrpc: 2.0, id: 1, method: initialize, params: { capabilities: { workspace: { didChangeConfiguration: { dynamicRegistration: true } } } } }四、动态注册DidChangeConfigurationRegistrationOptions在dynamicRegistration为true的前提下服务器可以通过client/registerCapability在运行时动态注册对该通知的监听。从 metaModel.json 可以看到注册选项类型DidChangeConfigurationRegistrationOptions{ name: DidChangeConfigurationRegistrationOptions, properties: [ { name: section, type: { kind: or, items: [ { kind: base, name: string }, { kind: array, element: { kind: base, name: string } } ] }, optional: true } ] }即注册选项包含一个可选的section字段类型为string | string[]用于指定服务器关心的配置节section。这允许服务器只对特定配置节的变化做出反应而不是盲目接收全部配置。五、推送模型 vs 拉取模型与workspace/configuration的关系理解workspace/didChangeConfiguration的关键在于它隶属于 LSP 配置机制中的推送模型push model而 3.6.0 之后协议又提供了**拉取模型pull model**作为替代。规范在 configuration.md 中对此有明确说明This pull model replaces the old push model were the client signaled configuration change via an event.两者的对比如下维度推送模型workspace/didChangeConfiguration拉取模型workspace/configuration方向客户端 → 服务器通知无响应服务器 → 客户端请求有响应触发时机客户端配置变化时主动推送服务器按需批量获取携带内容settings: LSPAny完整配置快照ConfigurationItem[]列表可一次请求多项引入版本1.0 起推送模型的传统机制3.6.0在拉取模型中服务器通过workspace/configuration请求向客户端批量获取配置响应结果为LSPAny[]返回顺序与请求中的ConfigurationItem顺序一一对应。每个ConfigurationItem包含export interface ConfigurationItem { /** * The scope to get the configuration section for. */ scopeUri?: URI; /** * The configuration section asked for. */ section?: string; }section要获取的配置节如cpp.formatterOptions由服务器自行定义不必与客户端内部的配置存储结构一致——例如服务器请求cpp.formatterOptions而客户端可能以 XML 或其他布局存储配置转换工作由客户端负责。scopeUri配置的作用域资源 URI。若提供客户端应返回限定到该资源的作用域配置若客户端无法为给定作用域提供配置则响应数组中对应位置必须为null。为什么推送模型仍然需要保留规范明确指出拉取模型取代了旧的推送模型。但服务器如果在拉取模型下缓存了workspace/configuration的结果仍然需要一种方式获知配置变了、缓存已失效。为此规范给出的做法是——仍然注册一个空empty的配置变更通知connection.client.register(DidChangeConfigurationNotification.type, undefined);这段代码出自 configuration.md的含义是服务器以空注册选项注册workspace/didChangeConfiguration通知undefined表示不关心具体section客户端在配置发生任何变化时都会发送该通知服务器收到通知后虽然不使用通知中的settings数据因为拉取模型下应再次发起workspace/configuration请求获取权威配置但借此获知配置已变化从而失效本地缓存并重新拉取。这正是dynamicRegistration字段注释中 since 3.6.0 to support the new pull model 的用意动态注册机制使得拉取模型下的服务器可以按需订阅配置变化事件而不必在初始化时静态声明。六、服务器端典型处理流程综合推送与拉取两种模型一个现代 LSP 服务器处理配置变更的推荐流程如下初始化阶段读取客户端在initialize中声明的workspace.didChangeConfiguration能力。注册阶段若能力可用服务器调用client/registerCapability以空选项或指定section注册DidChangeConfigurationNotification。通知处理阶段收到workspace/didChangeConfiguration时在纯推送模型下直接解析params.settings更新服务器内部状态在拉取模型下忽略settings内容将其仅视为缓存失效信号随后发起workspace/configuration请求按需重新拉取所需配置节。作用域处理结合scopeUri语义对不同资源返回不同配置例如按文件路径返回 EditorConfig 等作用域配置未提供的项以null占位。七、版本演进与元数据佐证该通知自协议早期版本即存在属配置推送机制的基础消息dynamicRegistration字段自3.6.0起为支持拉取模型而引入在 3.18 版本的 didChangeConfiguration.md 中DidChangeConfigurationParams.settings的注释更新为 The actual changed settings.3.17 版为 The actual changed settings协议内容保持一致结构化元数据 metaModel.json 中完整建模了DidChangeConfigurationParams含settings: LSPAny、DidChangeConfigurationClientCapabilities含可选dynamicRegistration以及DidChangeConfigurationRegistrationOptions含可选section: string | string[]三类类型是机器可读的规范等价物可用于代码生成、协议校验与工具链开发。八、实战要点小结方向不可逆workspace/didChangeConfiguration只允许客户端发往服务器服务器不可反向发送。settings 是快照而非增量客户端发送的是变更后的完整配置服务器不应假设其与上一次发送内容存在可比较的增量关系。LSPAny 意味着零约束settings的具体 schema 完全由客户端与服务端协商服务器应对未知字段保持宽容。推送与拉取可共存即使使用拉取模型获取配置也建议保留一个空注册的didChangeConfiguration通知作为配置已变化的失效信号避免本地缓存过期。能力声明必不可少客户端必须在initialize的workspace.didChangeConfiguration中声明能力服务器才能合法地依赖该通知支持动态注册的客户端应同时上报dynamicRegistration: true。赞分享开发工具【免费下载链接】language-server-protocolDefines a common protocol for language servers.项目地址https://gitcode.com/gh_mirrors/la/language-server-protocol点击查看免费下载相关推荐深入解析 Biome 的 Markdown 格式化setext 标题与跨行 HTML 的边界处理example-59 用例剖析深入解析 Biome 的 Markdown 格式化setext 标题与跨行 HTML 的边界处理example 59 用例剖析 导读 本文以 Biome开发工具Language Server Protocol 文件删除事件workspace/didDeleteFiles 通知详解Language Server Protocol 文件删除事件workspace/didDeleteFiles 通知详解 导读 workspace/didDe开发工具Language Server Protocol 文件创建事件通知workspace/didCreateFiles 消息规范与实现解析Language Server Protocol 文件创建事件通知workspace/didCreateFiles 消息规范与实现解析 导读 workspac开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考