# 自定义协议框架 LspCpp 不仅限于 Language Server Protocol 服务器。LSP 层构建在可复用的 JSON-RPC 消息框架之上,因此你可以定义自己的协议 method,并使用相同的传输、帧格式、分发、取消与类型化序列化基础设施。 在以下场景使用此模式: - 两个 C++ 进程之间的私有 JSON-RPC 协议。 - 非标准 LSP 的类编辑器插件协议。 - 带类型化请求/响应消息的测试 harness、守护进程或工具服务器。 - 在 stdio、TCP、WebSocket 或自定义流上使用 LSP 兼容帧格式,但不使用 LSP method 名。 ## 可复用的层 项目有两个实用层: | 层 | 主要类型 | 适用场景 | |----|----------|----------| | LSP 便利层 | `lsp::LanguageSession`、`lsp::ProtocolJsonHandler` | 构建常规 LSP 服务器或扩展 LSP。 | | 通用 JSON-RPC 层 | `MessageJsonHandler`、`GenericEndpoint`、`RemoteEndPoint` | 定义自己的协议 method 和消息类型。 | `LanguageSession` 会创建 `ProtocolJsonHandler`,预注册大量 LSP method。若要干净的自定义协议,请自行用普通 `MessageJsonHandler` 构造 `RemoteEndPoint`。 ## 最小自定义协议服务器 本示例定义名为 `tool/echo` 的请求和名为 `tool/exit` 的通知。不依赖任何 LSP 请求或 capability 类型。 ```cpp #include "LibLsp/JsonRpc/Condition.h" #include "LibLsp/JsonRpc/Endpoint.h" #include "LibLsp/JsonRpc/NotificationInMessage.h" #include "LibLsp/JsonRpc/RemoteEndPoint.h" #include "LibLsp/JsonRpc/RequestInMessage.h" #include "LibLsp/JsonRpc/stream.h" #include #include struct EchoParams { std::string text; MAKE_SWAP_METHOD(EchoParams, text); }; MAKE_REFLECT_STRUCT(EchoParams, text); struct EchoResult { std::string text; MAKE_SWAP_METHOD(EchoResult, text); }; MAKE_REFLECT_STRUCT(EchoResult, text); DEFINE_REQUEST_RESPONSE_TYPE(Echo, EchoParams, EchoResult, "tool/echo"); struct ExitParams { bool requested = true; MAKE_SWAP_METHOD(ExitParams, requested); }; MAKE_REFLECT_STRUCT(ExitParams, requested); DEFINE_NOTIFICATION_TYPE(Notify_ToolExit, ExitParams, "tool/exit"); int main() { lsp::NullLog log; auto json_handler = std::make_shared(); auto local_endpoint = std::make_shared(log); RemoteEndPoint endpoint(json_handler, local_endpoint, log); Condition exit_requested; endpoint.registerHandler( [](Echo::request const& req) { Echo::response rsp; rsp.id = req.id; rsp.result.text = req.params.text; return rsp; }); endpoint.registerHandler( [&](Notify_ToolExit::notify const&) { exit_requested.notify(std::make_unique(true)); }); endpoint.startProcessingMessages(lsp::make_stdin_stream(), lsp::make_stdout_stream()); exit_requested.wait(); endpoint.stop(); } ``` `registerHandler()` 会同时安装消息 handler 和未知自定义 method 的 JSON 解析器。简单自定义请求和通知类型无需手动填充 `MessageJsonHandler`。 ## 线格式 默认 `JSONStreamStyle::Standard` 传输使用 LSP 风格的 `Content-Length` 帧格式,但 JSON-RPC 载荷可以是你的协议: ```text Content-Length: 72 {"jsonrpc":"2.0","id":1,"method":"tool/echo","params":{"text":"hello"}} ``` 响应使用 `DEFINE_REQUEST_RESPONSE_TYPE` 中声明的 result 类型: ```text Content-Length: 52 {"jsonrpc":"2.0","id":1,"result":{"text":"hello"}} ``` ## 发送自定义消息 出站消息同样通过 `RemoteEndPoint` 发送: ```cpp auto req = endpoint.createRequest(); req.params.text = "ping"; auto future = endpoint.send(req); future.wait(); auto result = future.get(); if (!result.IsError()) { auto echoed = result.response.result.text; } ``` 通知不需要 request id: ```cpp Notify_ToolExit::notify notify; endpoint.send(notify); ``` ## 使用不同传输 通用层可使用与 LSP 层相同的传输: - stdio:`endpoint.startProcessingMessages(lsp::make_stdin_stream(), lsp::make_stdout_stream())` - 自定义流:传入自己的 `std::shared_ptr` 和 `std::shared_ptr` - TCP:基于 `lsp::TcpServer` 构建,在 `server.point` 上注册 handler - WebSocket:当 `LSPCPP_BUILD_WEBSOCKETS=ON` 时使用现有 WebSocket 服务器支持 消息类型不必是 LSP 类型。只需 JSON-RPC 信封和帧格式与双方预期一致。 ## 何时改用 `LanguageSession` 当你的协议仍以 LSP 为主时使用 `lsp::LanguageSession`: - 需要标准 LSP method,如 `initialize`、`shutdown`、`textDocument/hover` 或 diagnostics。 - 需要内置 LSP 请求和通知解析器。 - 为编辑器编写语言服务器。 当你想要与 LSP 无关的协议时,使用普通 `MessageJsonHandler` 的 `RemoteEndPoint`。 ## 设计指南 - 选择稳定的 method 名,例如 `tool/echo`、`daemon/build` 或 `$/progress`。 - 保持请求 params 和响应 result 小而明确。 - 若客户端与服务器可能独立升级,在初始化请求中对自定义协议做版本化。 - 将 `Content-Length` 帧格式视为传输契约的一部分;双方必须发送完整 JSON-RPC 帧。 - 若后续添加标准 LSP 支持,切换到 `lsp::ProtocolJsonHandler` 或 `lsp::LanguageSession`,并将自定义 method 与 LSP method 并存。 ## 相关文档 - [高级定制](advanced-customization.md) - [传输方式](transport.md) - [协议类型](../developer/protocol-types.md) .