# 高级定制 本指南涵盖非标准 LSP 扩展,以及需要改变 LspCpp 对已存在方法的解析方式的情况。若协议本身不是 LSP,请使用[自定义协议框架](custom-protocol.md)中描述的更低层 JSON-RPC 层。 在以下场景使用这些 API: - 添加自定义请求或通知,如 `workspace/index` 或 `$/myServer/progress`。 - 支持特定编辑器或语言服务器客户端使用的厂商扩展。 - 以不同于 LspCpp 内置结构体的方式解析标准 LSP 方法。 - 从服务器向客户端发送自定义请求或通知。 ## 解析与 handler 如何配合 LspCpp 对每条入站消息有两块独立逻辑: 1. `MessageJsonHandler` 中的 JSON 解析器,将 method 名和 JSON body 转为类型化的 `LspMessage`。 2. `RemoteEndPoint` 中的 handler,接收该类型化 C++ 消息。 对于自定义 method,`server.on(...)` 通常两者都做:注册 handler,且若 method 未知则自动注册匹配的 JSON 解析器。 对于 `ProtocolJsonHandler` 已知的 method,仅注册自定义 handler **不足以**改变解析。你还必须在消息到达前覆盖解析器。 ## 定义自定义请求 定义 params 和 result 结构体,做 reflection,然后使用 `DEFINE_REQUEST_RESPONSE_TYPE`。 ```cpp #include "LibLsp/LspCpp.h" #include "LibLsp/JsonRpc/RequestInMessage.h" #include #include struct WorkspaceIndexParams { std::string rootUri; bool rebuild = false; MAKE_SWAP_METHOD(WorkspaceIndexParams, rootUri, rebuild); }; MAKE_REFLECT_STRUCT(WorkspaceIndexParams, rootUri, rebuild); struct WorkspaceIndexResult { bool accepted = false; std::vector indexedFiles; MAKE_SWAP_METHOD(WorkspaceIndexResult, accepted, indexedFiles); }; MAKE_REFLECT_STRUCT(WorkspaceIndexResult, accepted, indexedFiles); DEFINE_REQUEST_RESPONSE_TYPE( WorkspaceIndexRequest, WorkspaceIndexParams, WorkspaceIndexResult, "workspace/index" ); ``` 像内置请求一样处理: ```cpp server.on( [](WorkspaceIndexRequest::request const& req) -> lsp::ResponseOrError { WorkspaceIndexRequest::response rsp; rsp.id = req.id; rsp.result.accepted = true; rsp.result.indexedFiles = { req.params.rootUri }; return rsp; }); ``` 注册该 handler 时,`RemoteEndPoint` 发现 `workspace/index` 尚无解析器,会自动安装 `WorkspaceIndexRequest::request::ReflectReader`。 ## 定义自定义通知 通知使用 `DEFINE_NOTIFICATION_TYPE`。 ```cpp #include "LibLsp/LspCpp.h" #include "LibLsp/JsonRpc/NotificationInMessage.h" #include struct IndexProgressParams { std::string rootUri; int percent = 0; MAKE_SWAP_METHOD(IndexProgressParams, rootUri, percent); }; MAKE_REFLECT_STRUCT(IndexProgressParams, rootUri, percent); DEFINE_NOTIFICATION_TYPE(Notify_IndexProgress, IndexProgressParams, "$/indexProgress"); ``` 注册入站通知 handler: ```cpp server.on( [](Notify_IndexProgress::notify const& n) { // n.params.rootUri 和 n.params.percent 可用。 }); ``` 向客户端发送同一通知: ```cpp Notify_IndexProgress::notify n; n.params.rootUri = "file:///workspace"; n.params.percent = 50; server.endpoint().send(n); ``` ## 向客户端发送自定义请求 服务器到客户端的请求使用同一请求类型。用 `createRequest()` 创建请求 id,填充 params,然后调用 `send()`。 ```cpp auto req = server.endpoint().createRequest(); req.params.rootUri = "file:///workspace"; req.params.rebuild = true; auto future = server.endpoint().send(req); future.wait(); auto result = future.get(); if (result.IsError()) { // result.error 包含 JSON-RPC 错误。 } else { // result.response.result 包含 WorkspaceIndexResult。 } ``` 当某 method 尚无响应解析器时,`send()` 会自动为自定义请求类型注册响应解析器。 ## 覆盖内置请求解析器 当 method 名已存在于 LspCpp 但你需要不同的参数类型时,使用 `overrideRequestParser()`。 例如,将 `initialize` 解析为自定义请求类型: ```cpp struct CustomInitializeParams { optional rootUri; optional initializationOptions; optional clientName; MAKE_SWAP_METHOD(CustomInitializeParams, rootUri, initializationOptions, clientName); }; MAKE_REFLECT_STRUCT(CustomInitializeParams, rootUri, initializationOptions, clientName); DEFINE_REQUEST_RESPONSE_TYPE( CustomInitialize, CustomInitializeParams, InitializeResult, "initialize" ); server.overrideRequestParser(); server.on( [](CustomInitialize::request const& req) { CustomInitialize::response rsp; rsp.id = req.id; rsp.result.capabilities.hoverProvider = true; return rsp; }); ``` 解析器与 handler 必须就具体 C++ 类型达成一致。若解析器返回 `CustomInitialize::request`,该 method 的 handler 也应接受 `CustomInitialize::request const&`。 ## 用自定义逻辑覆盖解析器 若 reflection 不够,可安装手动解析器: ```cpp server.overrideRequestParser( CustomInitialize::request::kMethodInfo, [](Reader& visitor) -> std::unique_ptr { return CustomInitialize::request::ReflectReader(visitor); }); ``` 当你需要规范化旧客户端、容忍厂商特定 JSON,或将多种 wire 形态路由到同一 C++ 请求类型时,这种形式很有用。 ## 覆盖通知或响应解析器 `LanguageSession` 对请求暴露 `overrideRequestParser()`。对通知和响应,在启动 session 前直接使用底层 `ProtocolJsonHandler`。 ```cpp server.protocolJsonHandler()->SetNotificationJsonHandler( Notify_IndexProgress::notify::kMethodInfo, [](Reader& visitor) { return Notify_IndexProgress::notify::ReflectReader(visitor); }); ``` 响应: ```cpp server.protocolJsonHandler()->SetResponseJsonHandler( WorkspaceIndexRequest::request::kMethodInfo, [](Reader& visitor) { if (visitor.HasMember("error")) { return Rsp_Error::ReflectReader(visitor); } return WorkspaceIndexRequest::response::ReflectReader(visitor); }); ``` 在 `start()`、`startStdio()` 或发送对应请求之前完成上述设置。 ## 不改变解析,仅替换处理逻辑 若只想对内置 method 使用不同行为,保留内置解析器并为内置类型注册 handler: ```cpp server.on( [](td_hover::request const& req) { td_hover::response rsp; rsp.id = req.id; // 用服务器要返回的 hover 内容填充 rsp.result。 return rsp; }); ``` 此场景无需覆盖解析器。 ## 顺序规则 - 在注册 handler 之前定义自定义消息类型。 - 在 `start()` 之前,或在需要自定义响应解析器的请求发送之前,注册解析器覆盖。 - 每个 method 名保持一种解析器和一种 handler 类型。用不兼容的 C++ 类型复用同一 method 字符串可能导致 dispatch 时无效转换。 - 扩展优先使用新 method 名。仅在必须支持非标准客户端 JSON 时才覆盖标准 LSP method。 ## 常见模式 ### 厂商扩展请求 使用新 method 名如 `myServer/analyzeProject` 和自定义请求类型。注册 handler 即可。 ### 标准 method 带额外 params 使用相同 method 名,定义替换请求类型,调用 `overrideRequestParser()`,再为 `YourRequest::request` 注册 handler。 ### 自定义服务器进度 使用自定义通知如 `$/indexProgress`,在索引线程中调用 `server.endpoint().send(notification)`。若 handler 与后台工作并发运行,需保护共享状态。 ## 相关文档 - [编写语言服务器](writing-a-language-server.md) - [协议类型](../developer/protocol-types.md) .