Dart SDK 中的 analysis_server：长期运行的代码分析服务与 LSP 集成指南

Dart SDK 中的 analysis_server长期运行的代码分析服务与 LSP 集成指南【免费下载链接】sdkThe Dart SDK, including the VM, JS and Wasm compilers, analysis, core libraries, and more.项目地址: https://gitcode.com/gh_mirrors/sdk1/sdkanalysis_server是 Dart SDK 中一个长期运行的进程专门负责对一个或多个持续变化的代码库进行增量式分析为编辑器、IDE 等外部工具提供分析结果。本文以 pkg/analysis_server/README.md 为主线结合 pkg/analysis_server/doc 下的实现文档与源码系统讲解 analysis_server 的定位、两种通信协议、启动流程以及 Dart 语言服务器LSP的初始化选项、工作区配置与自定义扩展方法帮助读者掌握如何在编辑器或命令行工具中对接并使用这一分析服务。analysis_server 是什么根据 pkg/analysis_server/README.md 的定义analysis_server是一个长期运行的进程为其他工具提供分析结果。它与一次性执行的命令行分析器不同被设计用于对一个或多个正在变化的代码库进行持续分析——也就是说当用户在编辑器中增删改代码时服务会持续跟踪这些变更并维护最新的分析状态而不是每次从零开始重新分析。具体来说analysis_server包实现了 Dart Analysis Server有时缩写为 DAS同时支撑 IDE 体验与dart analyze、dart fix等命令行工具见 doc/introduction.md。关键特性包括长期存活即使命令行工具不按此方式使用服务本身也被设计为长期运行的长寿命进程单客户端模型服务与启动它的单个客户端通常是编辑器通信双协议支持根据启动参数选择使用传统协议legacy protocol或 LSPLanguage Server Protocol持续增量分析针对正在修改的代码库维护最新分析结果避免重复全量分析。使用方式客户端进程 JSON 协议分析服务器不打算独立使用也没有面向人类友好的用户界面。README 明确指出The analysis server is not intended to be used stand-alone, and therefore does not have a human-friendly user interface.因此客户端通常是编辑器这类工具需要在独立进程中启动 analysis server通过JSON 协议与之通信由客户端负责发起请求、接收通知把分析结果呈现给用户。协议规范分为两部分原始协议定义在analysis_server/doc/api.html中属于 Dart 自有的 JSON-RPC 风格协议LSP 支持文档位于tool/lsp_spec/README.md遵循微软的 Language Server Protocol 规范。从源码看协议的选择发生在启动阶段。根据 doc/implementation/startup.md基于所选协议启动器会创建AnalysisServer两个具体子类之一——LspAnalysisServer或LegacyAnalysisServer并完成初始化。两种协议的使用场景如下协议典型客户端特点传统协议LegacyIntelliJ、Android StudioDart 自有的 JSON 协议详见 api.htmlLSPVS Code 及其他支持 LSP 的编辑器行业标准协议详见 lsp.md关于两种协议的服务端处理逻辑可阅读 doc/implementation/handlers.md请求处理器实现。启动流程从命令行到 AnalysisServer 实例虽然 README 未展开启动细节但结合仓库中的实现文档 doc/implementation/startup.md 可以还原完整的启动链路执行命令通过dart language_serverLSP 场景下也可写作dart language-server命令运行分析服务器进入入口函数命令调用bin/server.dart中的main函数创建 ServerStartermain的唯一职责是创建ServerStarter实例并把命令行参数传给它解析参数并创建实例启动器解析命令行参数据此创建并初始化AnalysisServer——若选择了 LSP 则创建LspAnalysisServer选择了传统协议则创建LegacyAnalysisServer开始服务服务与唯一客户端启动它的进程通过所选协议通信。这套流程对应的核心类型定义在 pkg/analysis_server/lib/starter.dart 中。需要注意LSP 场景下由客户端发出第一个请求initialize因此在客户端发送initialize请求之前没有明显的迹象表明服务器已正常工作——这与传统 JSON-RPC 不同LSP 还要求必须发送 HTTP 风格的消息头。Dart LSP 服务器的运行与编辑器集成从 SDK 2.2.0 版本对应 Flutter 1.2.1起analysis server 开始支持 LSP。本节内容主要继承并展开自 tool/lsp_spec/README.md。启动命令与环境变量使用dart language-server命令启动语言服务器并通过环境变量标识编辑器/插件及其版本环境变量含义示例DASH__IDE_NAME用户启动的 IDE 名称VS Code、AntigravityDASH__IDE_VERSION上述软件的版本号如1.85.0DASH__PLUGIN_NAME提供 Dart/Flutter 集成的插件名称Dart-CodeDASH__PLUGIN_VERSION上述插件的版本号如3.80.0这些信息会被服务端收集用于诊断与遥测可参见 doc/tutorial/instrumentation.md 中的仪表化说明。松散文件Loose Files的处理策略当没有打开的工作区文件夹或初始化选项onlyAnalyzeProjectsWithOpenFiles为true时分析将基于打开的文件来确定分析范围对每个打开的文件向上定位项目根目录并分析整个项目如果文件不属于任何项目例如其祖先目录中不存在pubspec.yaml则单独分析该文件。这保证了在没有工作区上下文时服务器仍能正确分析用户正在编辑的单个文件。LSP 初始化选项initializationOptionstool/lsp_spec/README.md列出了 Dart LSP 服务器支持的全部初始化选项客户端在initialize请求中通过initializationOptions字段传入选项类型说明onlyAnalyzeProjectsWithOpenFilesbool?为true时忽略工作区文件夹仅基于打开的文件进行分析避免打开大文件夹时触发全量分析。默认falsesuggestFromUnimportedLibrariesbool?为false时补全不包含当前文件尚未导入的符号。默认true且客户端还需支持workspace/applyEdit才会包含这些补全closingLabelsbool?已废弃改用客户端能力experimental.closingLabels{}。为true时发送dart/textDocument/publishClosingLabels通知以渲染编辑器闭合标签outlinebool?为true时发送dart/textDocument/publishOutline通知提供打开文件的 outline 信息flutterOutlinebool?为true时发送dart/textDocument/publishFlutterOutline通知提供 Flutter outline 信息allowOpenUribool为true时表示客户端会处理dart/openUri通知用浏览器打开给定的 URI注意closingLabels已被标记为废弃新实现应优先使用 LSP 客户端能力experimental.closingLabels。客户端工作区配置workspace/configuration工作区设置通过workspace/configuration在初始化期间请求并在客户端发送workspace/didChangeConfiguration时重新获取——这样设置变更无需重启服务器即可生效。完整配置项如下配置键类型说明dart.analysisExcludedFoldersListString?从分析中排除的路径数组绝对路径或相对于各工作区文件夹dart.enableSdkFormatterbool?为false时阻止注册或注销SDK 格式化器为true或未提供时注册/重新注册dart.lineLengthint?已废弃改用analysis_options.yaml中的formatter.page_width。设置格式化器换行的默认列数两者均未指定时按80列换行dart.completeFunctionCallsbool?是否用必需参数补全函数/方法。使用 TextMate 片段语法因此需要客户端支持 snippets。默认truedart.showTodosbool?是否为 TODO 注释生成诊断信息。未指定时不生成dart.renameFilesWithClassesString为always时若文件名与类名匹配snake_case重命名类时附带重命名文件的编辑为prompt时每次重命名类都提示确认否则不重命名文件。重命名通过 LSP 的ResourceOperation编辑完成需客户端处理dart.enableSnippetsbool?补全中是否包含代码片段如class、stful、switch。未指定时包含dart.updateImportsOnRenamebool?重命名文件时是否更新 import 等指令。未指定时若客户端支持willRenameFiles请求则更新dart.documentationnone/summary/full在补全等可能返回大量结果的请求中包含的 dartdoc 类型。默认fulldart.includeDependenciesInWorkspaceSymbolsbool?工作区符号结果中是否包含依赖以及 Dart/Flutter SDK 中的符号。默认truedart.inlayHintsbool?/Object?是否显示 Inlay Hints。true启用全部默认设置false全部禁用也可传对象按类型配置。默认truedart.inlayHints的对象形式支持以下子项均为{ enabled: ... }结构dotShorthandTypes是否为点简写类型显示提示parameterNames控制参数名提示enabled取值true/false/none/literal/all——none或false不显示literal仅对字面量参数显示all或true显示全部parameterTypes是否显示推断出的参数类型returnTypes是否显示推断出的返回类型typeArguments是否显示推断出的类型实参variableTypes是否显示推断出的变量声明类型。LSP 方法支持状态一览tool/lsp_spec/README.md用一张方法状态表列出了 Dart LSP 服务器对标准 LSP 方法的实现情况。核心支持情况✅ 表示已实现包括生命周期initializetrace 等选项暂未实现、initialized、shutdown支持但不做任何事、exit、$/cancelRequest文档同步textDocument/didOpen、textDocument/didChange、textDocument/didClosedidSave未实现导航与符号textDocument/definition、textDocument/declaration未实现、textDocument/typeDefinition、textDocument/implementation、textDocument/documentSymbol、textDocument/references、workspace/symbol、textDocument/prepareCallHierarchycallHierarchy/incomingCallscallHierarchy/outgoingCalls、textDocument/prepareTypeHierarchytypeHierarchy/subtypestypeHierarchy/supertypes编辑与重构textDocument/codeAction涵盖 assists、fixes、fixAll、refactors、organiseImports、sortMembers部分依赖客户端声明codeActionLiteralSupport、textDocument/codeLens、textDocument/formatting、textDocument/onTypeFormatting、textDocument/rangeFormatting、textDocument/prepareRenametextDocument/rename、workspace/applyEdit、workspace/willRenameFiles、workspace/executeCommand阅读体验textDocument/completioncompletionItem/resolve、textDocument/hover、textDocument/signatureHelp、textDocument/documentHighlight、textDocument/documentLink、textDocument/foldingRange、textDocument/selectionRange、textDocument/documentColorcolorPresentation、textDocument/semanticTokens/fullsemanticTokens/range、textDocument/inlayHint、textDocument/inlineValue、textDocument/publishDiagnostics工作区与进度workspace/didChangeWorkspaceFolders、workspace/didChangeConfiguration、workspace/configuration、window/showMessage、window/logMessage、window/workDoneProgress/create、client/registerCapability、client/unregisterCapability。值得注意的细节workspace/didChangeWatchedFiles虽在标准中定义但未被使用——服务器自己做文件监听表中注明 unused, server does own watchingtextDocument/codeAction中的修复/重构能力取决于客户端是否声明codeActionLiteralSupportcommand/resolve用于支持实验性的 Interactive Forms 特性。完整的逐方法状态请查阅 tool/lsp_spec/README.md。Dart LSP 服务器的自定义扩展方法除了标准 LSP 方法Dart LSP 服务器还提供了一系列dart/*自定义字段、方法与通知用于暴露 Dart 特有的分析能力。clientRequestTime字段所有入站消息都可携带可选的int?类型字段clientRequestTime与id、method、params并列值为客户端发起请求时的毫秒时间戳。它用于跟踪分析服务器对客户端请求的响应速度便于定位问题。常用自定义方法方法方向参数 → 返回说明dart/diagnosticServer客户端 → 服务器无 →{ port: number }启动分析器诊断服务器如未运行并返回监听端口dart/updateDiagnosticInformation客户端 → 服务器MapString, Object?→ 无向服务器提供诊断信息随诊断站点的 Collect Report 导出只应包含如保存时格式化是否开启这类简单值不得包含个人信息dart/reanalyze客户端 → 服务器无 → 无强制重新读取所有可能变更的文件、重新解析所有 URI 并重新分析当前分析根下的所有内容。客户端通常无需调用需要调用可能说明服务器存在 bugdart/textDocument/summary客户端 → 服务器DartTextDocumentSummaryParams→DocumentSummary返回给定 URI 文件的代码摘要非 Dart 文件或解析失败返回null摘要内容与格式未定义可能随时变化dart/textDocument/super客户端 → 服务器TextDocumentPositionParams→Location \| null返回指定位置类或方法的 super 定义位置dart/textDocument/imports客户端 → 服务器TextDocumentPositionParams→Location[] \| null返回暴露该位置元素的 import 指令位置dart/textDocument/augmented客户端 → 服务器TextDocumentPositionParams→Location \| null返回指定位置被 augment 的声明位置用于 Dart 3 的 augmentation 特性dart/textDocument/augmentation客户端 → 服务器TextDocumentPositionParams→Location \| null返回指定位置声明的 augmentation 位置dart/workspace/analysis/complete客户端 → 服务器无 → 无等待所有进行中的分析及可能导致分析的工作完成后再返回确保客户端已收到整个工作区的诊断通知。调用前应检查服务器 experimental capabilities 中是否有workspaceAnalysisComplete键dart/connectToDtd客户端 → 服务器{ uri: Uri }→null提供 Dart Tooling Daemon 服务器 URI使 LSP 服务器连接并向后端 DTD 客户端开放部分 LSP 功能只能由拥有 analysis server 进程的工具经 stdin/stdout调用dart/textDocument/editableArguments客户端 → 服务器TextDocumentPositionParams→EditableArguments返回文档内某位置的可编辑参数列表可配合dart/textDocument/editArgument更新参数dart/textDocument/editArgument客户端 → 服务器EditArgumentParams→Null指示编辑器编辑某个可编辑参数的值dart/workspace/migrate客户端 → 服务器DartMigrateParams→DartMigrateResult返回把 pub workspace 文件夹或非 pub 工作区包迁移到最新 Dart 版本的编辑。pub workspace 中的包只需传 workspace 根独立迁移单个包不受支持响应包含结果摘要与WorkspaceEditdart/workspace/fixes/get客户端 → 服务器DartGetWorkspaceFixesParams→DartGetWorkspaceFixesResult实验性。返回工作区所有可修复诊断的全部修复编辑类似 Fix All in Workspace 命令但把编辑返回给调用者而非要求编辑器应用自定义通知通知方向参数说明$/analyzerStatus服务器 → 客户端{ isAnalyzing: boolean }已废弃。分析开始/完成时通知客户端若客户端能力含window.workDoneProgress true则不发送改用$/progress未来 SDK 版本可能移除dart/textDocument/publishClosingLabels服务器 → 客户端{ uri, labels: { label, range }[] }文件闭合标签信息可用/更新时发送dart/textDocument/publishOutline服务器 → 客户端{ uri, outline }文件 outline 可用/更新时发送。节点含多个 rangeelement.range为声明中名称的范围range为含 dartdoc 的完整声明范围codeRange为不含 dartdoc/注解的代码范围导航到声明时使用dart/textDocument/publishFlutterOutline服务器 → 客户端{ uri, flutterOutline }Flutter outline 可用/更新时发送结构与 outline 类似并含kind、label、className、attributes等字段dart/openUri服务器 → 客户端{ uri: Uri }服务器希望客户端打开某个 URI如用户在window/showMessageRequest中点击 Learn More。仅在客户端以allowOpenUri: true传入初始化选项时发送URI 可以是 http/https 网页或 file:// 文档客户端命令Client Commands部分服务器功能依赖客户端提供已知命令。例如 Go to Augmented 等 CodeLens 需要服务器能指示客户端导航到指定Location。为此客户端必须在初始化时于客户端能力的experimental.commands字段中声明支持的命令{ // ... other client capabilities experimental: { commands: [ dart.goToLocation, ] } }dart.goToLocation命令接收单个Location参数并导航到编辑器中的对应位置。服务器在 CodeLens 或其他可返回Command的地方使用它例如 CodeLens 响应[ // CodeLens { range: { end: { character: 0, line: 2 }, start: { character: 0, line: 2 } }, // Command command: { title: Go to Augmented, command: dart.goToLocation, arguments: [ // Location { uri: file:///C:/Projects/my_app/lib/main.dart, range: { end: { character: 7, line: 2 }, start: { character: 6, line: 2 } } } ] } } ]深入阅读与调试资源若想进一步深入 analysis_server 的内部实现仓库中提供了体系化的文档实现总览doc/implementation/overview.md 按特性分类介绍服务器如何实现代码补全、导航、快速修复Quick Fix、快速辅助Quick Assist、语义高亮、重构等能力协议实现doc/implementation/lsp.md 与 doc/implementation/legacy.md 分别讲解两种协议的实现doc/implementation/handlers.md 讲解请求处理器进程与协作流程doc/process/overview.md 描述在 analysis server 代码库上工作的协作流程doc/process/running_in_vs_code.md 与 doc/process/profiling_for_vs_code.md 介绍如何在 VS Code 中运行与剖析服务器用户教程doc/tutorial/instrumentation.md仪表化与洞察页面与 doc/tutorial/session_log.md录制会话通信日志会话回放tool/log_player/README.md 提供日志回放工具用于复现客户端与服务器之间的通信过程测试服务器的测试用例位于 pkg/analysis_server/test可用于验证各 LSP 方法与自定义扩展的行为。小结analysis_server 是 Dart 生态中连接编辑器与深度静态分析的桥梁它以长期运行进程的形式持续跟踪代码变更通过传统 JSON 协议服务 IntelliJ/Android Studio通过 LSP 服务 VS Code 等现代编辑器。其 LSP 实现不仅覆盖了绝大多数标准方法还通过dart/*自定义方法提供了大纲、Flutter outline、augmentation 导航、工作区迁移等 Dart 特有能力。开发者无论是编写编辑器插件还是构建基于 Dart 的代码分析工具都可以依据 tool/lsp_spec/README.md 中的协议文档与 doc/api.html 快速完成对接。如需反馈问题或提交功能请求请遵循 pkg/analysis_server/README.md 中的指引将 issue 提交到 Dart SDK 的 issue 跟踪器。【免费下载链接】sdkThe Dart SDK, including the VM, JS and Wasm compilers, analysis, core libraries, and more.项目地址: https://gitcode.com/gh_mirrors/sdk1/sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考