在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

FuelLabs/sway

菜单

语言服务器协议

相关源文件

本文档提供了 Sway 编程语言中语言服务器协议 (LSP) 实现的技术概述。它涵盖了 LSP 系统的架构、组件和交互，该系统支持代码补全、转到定义和诊断等 IDE 功能。有关特定 IDE 集成的信息，请参阅构建系统与依赖项。

目的与实现

Sway 语言服务器实现了语言服务器协议规范，为 IDE 和文本编辑器提供智能语言功能。该服务器充当开发环境和 Sway 编译器之间的桥梁，实时分析代码以提供增强开发人员生产力的功能。

来源

服务器架构

该语言服务器采用多组件架构，旨在高效处理 LSP 请求，同时保持响应能力

来源

ServerState

这个ServerState 是语言服务器的主要状态容器。它维护

  • 与客户端 (IDE) 的连接
  • 配置设置
  • 一个会话的 LRU 缓存（每个项目一个）
  • 文档管理
  • 编译线程协调

来源

会话与 TokenMap

一个Session 包含项目特定信息，是语言服务器提供代码智能的核心能力

  • TokenMap：存储已解析和已类型化的令牌以供快速查找
  • Engines：访问类型检查器、声明引擎等
  • BuildPlanCache：缓存构建计划以避免重复计算
  • Diagnostics：编译错误和警告

这个TokenMap 是一个并发哈希映射，它将令牌标识符映射到令牌，为 LSP 请求提供高效查找。它是语言功能的主要数据结构。

来源

编译线程

服务器使用专用线程进行编译以保持响应能力

  1. 消息通过通道发送到编译线程
  2. 该线程编译项目并填充令牌映射
  3. 编译完成后，它会通知等待者

这种方法可以防止主线程在编译期间阻塞。

来源

令牌系统

令牌系统是提供语言功能的基础

标记类型

该系统使用两种主要类型的令牌

  1. ParsedAstToken：来自已解析但未类型检查的 AST 的令牌
  2. TypedAstToken：来自完全类型检查的 AST 的令牌

这些令牌代表了编译器理解的不同阶段，并提供了日益丰富的信息。

来源

TokenMap 操作

这个TokenMap 提供以下操作：

  • 查找特定位置的令牌
  • 查找文件的令牌
  • 查找名称的令牌
  • 查找相关令牌（引用）

这些操作构成了大多数语言功能的基础。

来源

AST 遍历系统

服务器遍历 AST 以在不同阶段收集令牌

遍历系统访问 AST 中的节点并为 TokenMap 收集令牌

  1. LexedTree：从词法分析中收集关键字和令牌
  2. ParsedTree：从已解析但未类型化的 AST 中收集令牌
  3. TypedTree：从包含类型信息的完全类型化 AST 中收集令牌

来源

LSP 请求处理

服务器通过实现LanguageServer trait 来处理 LSP 请求

每个 LSP 请求都遵循类似的模式

  1. 通过LanguageServer 实现接收请求
  2. 查找文档 URI 的会话
  3. 使用会话访问令牌和其他状态
  4. 使用能力模块生成响应
  5. 将响应返回给客户端

来源

关键 LSP 功能

代码补全

补全系统根据以下内容提供建议：

  • 类型信息
  • 作用域（变量、函数等）
  • 上下文（结构体字段、方法调用）

它使用令牌映射查找当前上下文的类型信息。

来源

转到定义

定义功能允许跳转到符号的声明

  1. 查找光标位置的令牌
  2. 从令牌中获取声明信息
  3. 创建包含文件和位置的位置响应

来源

文档符号

文档符号功能提供了文档的纲要

  • 函数、结构体、枚举、特征
  • 分层结构（特征中的函数，结构体中的字段）
  • 位置和类型信息

来源

诊断

诊断信息在编译期间收集并发布到客户端

  1. 收集编译器的错误和警告
  2. 它们被转换为 LSP 诊断格式
  3. 它们通过publishDiagnostics 通知发布到客户端

来源

语义令牌

语义令牌提供语法高亮信息

  1. 令牌按位置排序
  2. 它们带有类型和修饰符的标注
  3. 它们以 LSP 预期的格式编码

来源

工作区同步

服务器维护工作区文件的临时副本

这种方法允许服务器

  1. 使用项目的干净副本进行操作
  2. 进行分析修改而不影响原始文件
  3. 使临时副本与更改保持同步

来源

编译过程

编译过程是 LSP 功能的核心

当文件更改时

  1. 服务器向编译线程发送编译任务
  2. 该线程使用 Sway 编译器编译项目
  3. 它遍历 AST 以填充令牌映射
  4. 它更新诊断信息和其他状态
  5. 它通知服务器编译完成

来源

错误处理

服务器实现了全面的错误处理系统

  • LanguageServerError：服务器中的顶级错误
  • DocumentError：与文档操作相关的错误
  • DirectoryError：与文件系统操作相关的错误
  • RenameError：重命名操作特有的错误

错误会被传播和记录，并向客户端发送适当的响应。

来源

服务器生命周期

服务器遵循标准的 LSP 生命周期

  1. 初始化：根据客户端能力设置服务器
  2. 已初始化：开始提供服务
  3. 正常操作：处理请求和通知
  4. 关机：清理资源
  5. 退出：终止服务器

心跳系统监控客户端进程，如果客户端消失则自动关机。

来源

测试基础设施

服务器包含广泛的测试基础设施

  • LSP 功能的集成测试
  • 用于性能分析的基准测试
  • 用于模拟客户端请求的实用程序

这确保了语言服务器的可靠性和性能。

来源

结论

Sway 语言服务器协议实现为 IDE 支持提供了坚实的基础。其多线程架构、高效的令牌系统和全面的功能集为 Sway 程序员提供了高效的开发环境。服务器的设计强调性能、可靠性以及对 LSP 规范的遵守。