# 编写语言服务器 本指南介绍使用 LspCpp 实现 LSP 服务器的主要 API 模式。 ## 两层 API LspCpp 提供两种搭建服务器的方式: | API | 头文件 | 适用场景 | |-----|--------|----------| | **`LanguageSession`** | `LibLsp/LspCpp.h` | 推荐用于新代码。`RemoteEndPoint` 的薄封装。 | | **`RemoteEndPoint`** | `LibLsp/JsonRpc/RemoteEndPoint.h` | 更底层控制;旧示例中使用。 | 两者使用相同的 handler 注册模型。`LanguageSession` 是便于使用的入口: ```cpp lsp::LanguageServer server; // LanguageSession 的别名 ``` ## 注册 handler 通过 `on()`(LanguageSession)或 `registerHandler()`(RemoteEndPoint)注册 handler。编译器根据 handler 参数类型推断 LSP 方法。 ### 请求 handler ```cpp server.on([](td_initialize::request const& req) -> lsp::ResponseOrError { td_initialize::response rsp; rsp.id = req.id; rsp.result.capabilities.hoverProvider = true; return rsp; }); ``` 返回 `lsp::ResponseOrError` 可发送成功响应或 JSON-RPC 错误。也可以直接返回响应类型;库在多数情况下会自动包装。 设置 `rsp.id = req.id`,以便客户端关联响应。 ### 支持取消的请求 handler 长时间运行的请求可接受 `CancelMonitor`: ```cpp server.on([](td_definition::request const& req, CancelMonitor const& monitor) -> lsp::ResponseOrError { if (monitor && monitor()) { Rsp_Error err; err.error.code = lsErrorCodes::RequestCancelled; err.error.message = "cancelled"; return err; } td_definition::response rsp; rsp.id = req.id; // ... return rsp; }); ``` ### 异步 request handler 耗时请求可返回 `lsp::future` 或 `lsp::future>`。库会在后台等待 future 完成后再发送响应,避免阻塞消息处理线程: ```cpp server.on([](td_hover::request const& req) -> lsp::future { auto promise = std::make_shared>(); auto future = promise->get_future(); std::thread([promise, id = req.id]() { td_hover::response rsp; rsp.id = id; // ... promise->set_value(std::move(rsp)); }).detach(); return future; }); ``` 可取消的异步 handler 同样支持第二个 `CancelMonitor const&` 参数。 ### 用 RequestError 返回错误 除显式返回 `lsp::ResponseOrError` 或 `Rsp_Error` 外,也可以直接抛出 `lsp::RequestError`,库会将其转换为 JSON-RPC 错误响应: ```cpp #include "LibLsp/JsonRpc/RequestError.h" server.on([](td_initialize::request const&) -> td_initialize::response { throw lsp::RequestError(lsErrorCodes::InvalidParams, "invalid initialize params"); }); ``` `ResponseOrError` 仍是显式、非异常式的替代方案。 ### 通知 handler 通知没有响应。注册方式相同: ```cpp server.on([](Notify_Exit::notify const&) { // handle exit }); server.on([](Notify_TextDocumentDidOpen::notify const& n) { // textDocument/didOpen }); ``` ## LSP 生命周期 规范的服务器遵循以下顺序: ``` Client Server |---- initialize -----------> | |<--- InitializeResult ------| |---- initialized ---------> | (notification, no response) |---- ... requests ... ----> | |---- shutdown ------------> | |<--- null ------------------| |---- exit -----------------> | | | stop() ``` 至少实现: ```cpp server.on([](td_initialize::request const& req) { /* return capabilities */ }); server.on([](td_shutdown::request const& req) { td_shutdown::response rsp; rsp.id = req.id; return rsp; }); server.on([&](Notify_Exit::notify const&) { exit_requested.notify(std::make_unique(true)); }); ``` 在 `initialize` 完成之前,服务器应拒绝其他请求(LspCpp 会强制协议解析;你的 handler 不应在初始化完成前假设文档已打开)。 ## 声明能力 能力在 `initialize` 响应中返回: ```cpp server.on([](td_initialize::request const& req) { td_initialize::response rsp; rsp.id = req.id; lsTextDocumentSyncOptions sync; sync.openClose = true; sync.change = lsTextDocumentSyncKind::Full; rsp.result.capabilities.textDocumentSync = std::make_pair(optional(), optional(sync)); lsCompletionOptions completion; completion.triggerCharacters = std::vector { "." }; rsp.result.capabilities.completionProvider = completion; rsp.result.capabilities.hoverProvider = true; WorkDoneProgressOptions definition_options; rsp.result.capabilities.definitionProvider = std::make_pair(optional(true), optional(definition_options)); return rsp; }); ``` 只声明你实际实现的功能。客户端据此决定发送哪些请求。 若干服务器 capability 字段对应 LSP 的 union 类型。在本代码库中,这些字段表示为 `std::pair, optional<...>>`;第一个槽位通常是简单的 boolean/kind 形式,第二个槽位是详细 options 对象。 ## 发送出站消息 使用 `server.endpoint()` 向客户端发送通知或请求: ```cpp // 记录到客户端输出面板 Notify_LogMessage::notify log; log.params.type = lsMessageType::Log; log.params.message = "indexing complete"; session.endpoint().send(log); // 发布诊断 Notify_TextDocumentPublishDiagnostics::notify diag; diag.params.uri.raw_uri_ = "file:///path/to/file.lang"; diag.params.diagnostics = { /* lsDiagnostic entries */ }; session.endpoint().send(diag); ``` ## 跟踪打开的文档 LspCpp 提供 `WorkingFiles`,用于维护与 LSP 文档事件同步的内存缓冲区: ```cpp #include "LibLsp/lsp/working_files.h" WorkingFiles files; server.on([&](Notify_TextDocumentDidOpen::notify const& n) { files.OnOpen(n.params.textDocument); }); server.on([&](Notify_TextDocumentDidChange::notify const& n) { files.OnChange(n.params); }); server.on([&](Notify_TextDocumentDidClose::notify const& n) { files.OnClose(n.params.textDocument); }); ``` `WorkingFile` 存储缓冲区内容和预计算的行偏移,用于将 LSP 位置转换为字节偏移。 ## 日志 向 `LanguageSession` 传入自定义 `Log` 实现,便于开发时诊断: ```cpp lsp::StderrLog log; lsp::LanguageSession server(log); ``` 生产环境若不需要 stderr 输出,使用 `NullLog`(默认)。 ## 可选 clangd 风格辅助 API(按需启用) 以下头文件均为增量添加;现有 `LanguageSession`、`RemoteEndPoint`、`WorkingFiles` 与 `ProtocolJsonHandler` 的默认行为不变。 ### 请求取消(`LibLsp/JsonRpc/RequestCancellation.h`) 为长时间运行的任务安装可取消作用域,并从当前 `Context` 轮询取消状态: ```cpp #include "LibLsp/JsonRpc/RequestCancellation.h" server.on([](td_definition::request const& req) -> lsp::ResponseOrError { if (auto monitor = lsp::getCancelledMonitor(req.id)) { if (lsp::isCancellationRequested(*monitor)) { throw lsp::makeRequestCancelledError(); } } // ... }); ``` `LibLsp/lsp/BindLspHandler.h` 中的 `BindLspHandlerWithMonitor` 与 `BindLspAsyncHandlerWithMonitor` 会直接传入 `CancelMonitor`。异步 binder 保留 handler 的精确 `lsp::future` 返回类型,包括 `lsp::future>`。 ### 错误辅助(`LibLsp/JsonRpc/Error.h`) 用于 `RequestCancelled (-32800)`、`ContentModified (-32801)` 等 LSP 专用错误码: ```cpp #include "LibLsp/JsonRpc/Error.h" throw lsp::makeRequestCancelledError(); throw lsp::makeContentModifiedError("buffer changed"); return lsp::makeRequestCancelledResponse(req.id); ``` **参数格式错误**仍应使用 `RequestError(lsErrorCodes::InvalidParams, ...)`。取消与内容变更辅助函数不能替代 `InvalidParams` 处理。 ### 请求上下文(`LibLsp/lsp/request_context.h`) 为 handler 代码提供可选的环境 offset 编码与路径映射: ```cpp #include "LibLsp/lsp/request_context.h" lsp::WithContext scope(lsp::withOffsetEncodingContext(lsp::OffsetEncoding::Utf8)); int offset = lsp::GetOffsetForPositionInContext(position, buffer); ``` 未安装上下文时,默认仍为 UTF-16。 ## 自定义请求解析 当需要对某方法做非标准参数处理时,可覆盖内置 JSON 解析器。解析器必须返回与该 method 的 handler 接受的相同具体请求类型: ```cpp server.overrideRequestParser( td_initialize::request::kMethodInfo, [](Reader& visitor) { return td_initialize::request::ReflectReader(visitor); }); ``` 或使用模板快捷方式: ```cpp server.overrideRequestParser(); ``` 自定义请求/通知类型、厂商扩展以及替换内置消息形态,见[高级定制](advanced-customization.md)。 ## 查找 LSP 类型头文件 请求和通知类型遵循命名约定: | 模式 | 示例 | LSP 方法 | |------|------|----------| | `td_::request` | `td_definition::request` | `textDocument/definition` | | `td_::response` | `td_definition::response` | (响应结构体) | | `Notify_::notify` | `Notify_Exit::notify` | `exit` | 头文件按领域组织在 `include/LibLsp/lsp/` 下: - `general/` — initialize、shutdown、exit - `textDocument/` — completion、hover、rename 等 - `workspace/` — symbols、configuration、applyEdit 这些类型的生成与扩展方式见[协议类型](../developer/protocol-types.md)。 ## 仓库中的示例 | 示例 | 说明 | |------|------| | `MinimalStdIOServerExample.cpp` | 最小 stdio 服务器(无 Boost) | | `StdIOServerExample.cpp` | 带能力、definition handler、取消的 stdio 服务器 | | `ProcessClientExample.cpp` | 用 `lsp::Process` 启动 server 并通过 stdio 通信的轻量客户端 | | `TcpServerExample.cpp` | 可配置端口的 TCP 服务器 | | `WebsocketExample.cpp` | WebSocket 服务器 | | `StdIOClientExample.cpp` | 基于 Boost.Process 的 stdio 客户端 JSON-RPC | 使用 `-DLSPCPP_BUILD_EXAMPLES=ON` 构建全部示例(需要 Boost;`ProcessClientExample` 仅依赖库内 `lsp::Process`)。 ## 启动 server 进程的客户端 实现 LSP 客户端时,通常由客户端拉起 language server 子进程并通过 stdio 通信。可使用 `lsp::Process`(`LibLsp/JsonRpc/Process.h`): ```cpp #include "LibLsp/JsonRpc/Process.h" lsp::Process process = lsp::Process::start("/path/to/language-server", {"--stdio"}); RemoteEndPoint point(json_handler, endpoint, log); point.startProcessingMessages(process.input(), process.output()); // 发送 initialize、处理响应... Notify_Exit::notify exit_notify; point.send(exit_notify); point.stop(); process.wait(); ``` 完整示例见 `examples/ProcessClientExample.cpp`。CTest 在开启示例时会运行: ```bash ProcessClientExample --execPath StdIOServerExample ``` .