145 lines
3.4 KiB
Markdown
145 lines
3.4 KiB
Markdown
# 架构决策记录
|
||
|
||
## ADR-001: 使用 C++23 Modules 构建 LSP 服务器
|
||
|
||
**日期**: 2026-02-02
|
||
**状态**: 已采纳
|
||
|
||
### 决策
|
||
|
||
LSP 服务器核心使用 C++23 Modules (`.cppm` 文件) 而非传统头文件 (`.h/.hpp`)。
|
||
|
||
### 理由
|
||
|
||
- **编译性能**：Module 只需编译一次，后续增量编译更快
|
||
- **符号隔离**：避免头文件中的宏污染和符号冲突
|
||
- **依赖清晰**：显式 import 声明依赖关系更清晰
|
||
- **现代化**：跟进 C++ 现代化趋势
|
||
|
||
### 影响
|
||
|
||
- 需要 Clang 20+ 或 GCC 15+ 编译器
|
||
- CMake 需要 4.2+ 版本以支持 CXX_MODULE
|
||
- 第三方库需要通过 Bridge 模块封装
|
||
|
||
---
|
||
|
||
## ADR-002: 选择 Tree-sitter 作为解析器
|
||
|
||
**日期**: 2026-02-02
|
||
**状态**: 已采纳
|
||
|
||
### 决策
|
||
|
||
使用 Tree-sitter 作为 TSL 语法解析器，而非手写递归下降解析器或 ANTLR。
|
||
|
||
### 理由
|
||
|
||
- **增量解析**：Tree-sitter 原生支持增量更新，适合 IDE 场景
|
||
- **错误恢复**：能在语法错误时继续解析，提供最大可用性
|
||
- **高性能**：C 实现，解析速度快
|
||
- **生态**：被 GitHub、Neovim 等广泛使用，经过生产验证
|
||
|
||
### 影响
|
||
|
||
- 需要编写 Tree-sitter 语法文件 (`grammar.js`)
|
||
- 生成的 C 代码需要集成到构建系统
|
||
- 语法树结构受 Tree-sitter 约束
|
||
|
||
---
|
||
|
||
## ADR-003: 使用 Glaze 进行 JSON 序列化
|
||
|
||
**日期**: 2026-02-02
|
||
**状态**: 已采纳
|
||
|
||
### 决策
|
||
|
||
使用 Glaze 库处理 LSP 协议的 JSON 序列化，而非 nlohmann/json 或 rapidjson。
|
||
|
||
### 理由
|
||
|
||
- **零拷贝**：Glaze 支持零拷贝解析，性能最优
|
||
- **编译时反射**：使用 C++20 概念实现编译时序列化，无运行时开销
|
||
- **类型安全**：编译期检查 JSON 结构与 C++ 类型的匹配
|
||
- **简洁**：代码量少，维护成本低
|
||
|
||
### 影响
|
||
|
||
- 需要为 LSP 类型定义 `glz::meta` 或使用结构化绑定
|
||
- 依赖 C++20 特性
|
||
|
||
---
|
||
|
||
## ADR-004: 采用 Taskflow 实现异步处理
|
||
|
||
**日期**: 2026-02-02
|
||
**状态**: 已采纳
|
||
|
||
### 决策
|
||
|
||
使用 Taskflow 库实现请求的异步并行处理，而非 std::async 或自建线程池。
|
||
|
||
### 理由
|
||
|
||
- **任务图**：支持复杂的任务依赖关系
|
||
- **性能**：高效的工作窃取调度器
|
||
- **易用**：API 简洁，与 C++20 配合良好
|
||
- **成熟**：经过 HPC 场景验证
|
||
|
||
### 影响
|
||
|
||
- 需要正确管理任务生命周期
|
||
- 共享状态需要同步保护
|
||
|
||
---
|
||
|
||
## ADR-005: VSCode 扩展与 LSP 服务器分离
|
||
|
||
**日期**: 2026-02-02
|
||
**状态**: 已采纳
|
||
|
||
### 决策
|
||
|
||
VSCode 扩展作为纯客户端，通过 stdio 与独立的 LSP 服务器进程通信。
|
||
|
||
### 理由
|
||
|
||
- **标准协议**：遵循 LSP 标准，可复用于其他编辑器
|
||
- **独立开发**：C++ 和 TypeScript 代码库独立演进
|
||
- **调试方便**：服务器可独立启动调试
|
||
- **稳定性**：服务器崩溃不影响 VSCode 主进程
|
||
|
||
### 影响
|
||
|
||
- 需要处理进程管理和生命周期
|
||
- stdio 通信增加序列化开销
|
||
- 需要分发服务器二进制文件
|
||
|
||
---
|
||
|
||
## ADR-006: 使用 Conan 管理 C++ 依赖
|
||
|
||
**日期**: 2026-02-02
|
||
**状态**: 已采纳
|
||
|
||
### 决策
|
||
|
||
使用 Conan 2.x 作为 C++ 依赖管理工具。
|
||
|
||
### 理由
|
||
|
||
- **跨平台**：统一管理 Linux 和 Windows 依赖
|
||
- **二进制缓存**：避免重复编译第三方库
|
||
- **版本锁定**：精确控制依赖版本
|
||
- **CMake 集成**：生成 CMake 工具链文件
|
||
|
||
### 影响
|
||
|
||
- 开发者需要安装 Conan
|
||
- 需要维护 Conan profile 和配方
|
||
|
||
---
|
||
|
||
**最后更新**：2026-02-02
|