之前实现 ZenScript 的 LSP 的时候只是简单实现了一个 server，没有对协议相关的功能进行更深入的了解。最近四个月前因为工作原因开始重新关注起这方面的内容，于是开始对协议的相关内容进行整理清库存。
本文基于 Language Server Protocol 3.16 编写，与当前的 LSP 版本可能不完全一致，阅读时需要注意。
什么 LSP，哪有 LSP，哦，是我啊
ToC
- 报文划分
HeaderContent
- JSONRPC
MessageRequestMessageResponseMessageNotificationMessage- 实现相关（
Implementation dependent）消息 - 取消请求（
$/cancelRequest） - 进度通知（
$/progress） - 错误代码
报文划分
LSP 的报文划分为 Header 和 Content 两个部分。二者之间通过 \r\n 隔开，很有微软的风格。
Header 的组织方式和 Http 很像，也是通过 : （冒号空格）的方式隔开。Header 之间也是通过 \r\n 分割的。
目前支持的 Header 有两个：Content-Length 和 Content-Type。其中前者为必选，后者默认为 application/vscode-jsonrpc; charset=utf-8。
Content
LSP 中的 Content 通过 jsonrpc 的方式组织。
JSONRPC
Message
这里定义了 Message 作为所有消息的共有内容。
interface Message {
// 表示 jsonrpc 的版本，在 LSP 中使用 2.0
jsonrpc: "2.0";
}
RequestMessage
Request 是客户端向服务端发送的，结构如下：
interface RequestMessage extends Message {
/**
* 标识请求的 ID
*/
id: integer | string;
/**
* 请求的方法
*/
method: string;
/**
* 请求的参数
*/
params?: array | object;
}
ResponseMessage
对应客户端请求的 Request 的就是服务端返回的 Response 了。结构如下：
// 请求的返回，有成功和失败两种情况
type ResponseMessage = ResponseSuccessMessage | ResponseErrorMessage;
// 两种情况都需要包含对应的请求 ID
interface ResponseBaseMessage extends Message {
/**
* 返回对应的请求 ID
*/
id: integer | string | null;
}
// 请求成功时，返回中携带 result 字段
interface ResponseSuccessMessage extends ResponseBaseMessage {
/**
* 请求成功后的结果
*/
result: string | number | boolean | object | null;
}
// 请求失败时，返回中携带错误详情
interface ResponseErrorMessage extends ResponseBaseMessage {
/**
* 请求失败时的错误详情
*/
error: ResponseError;
}
// 错误详情
interface ResponseError {
/**
* 错误代码
*/
code: integer;
/**
* 错误的解释信息
*/
message: string;
/**
* 错误的可选附加信息
*/
data?: string | number | boolean | array | object | null;
}
NotificationMessage
除请求和相应之外，jsonrpc 还定义了一种消息类型：通知。通知的工作方式和 event 类似，没有返回（Response）。定义如下：
interface NotificationMessage extends Message {
/**
* 待触发的 method
*/
method: string;
/**
* 通知的参数
*/
params?: array | object;
}
实现相关（Implementation dependent）消息
对以 $/ 字符串开头的 method 字段，其表示对应的消息是实现相关的，服务端或客户端可能没有实现此类方法。
当收到一个未实现的实现相关通知时，服务端或客户端可以直接忽略该通知；当收到一个未实现的实现相关请求（**Request**）时，其必须返回 MethodNotFound 错误（-32601）。
取消请求（$/cancelRequest）
取消请求可以用于正在进行的请求中，通过指定请求的 id 尝试取消对应 id 的请求操作。定义如下：
interface CancelParams {
/**
* The request id to cancel.
*/
id: integer | string;
}
为了和 jsonrpc 契合，已经取消的请求也必须产生对应的返回（Response）。当被取消的请求返回产生错误时，可以选用 ErrorCodes.RequestCancelled。
进度通知（$/progress）
since 3.15.0
LSP 提供了一种抽象的进度报告方式以对进度进行汇报。进度的标识通过 ProgressToken 表示，使得进度可以通过 Notification 的形式报告。结构定义如下：
type ProgressToken = integer | string;
interface ProgressParams<T> {
/**
* 标识进度的 token
*/
token: ProgressToken;
/**
* 实际的进度数据
*/
value: T;
}
错误代码
jsonrpc 定义了一些错误代码用于表示其内部错误，同时保留了一部分区间作为 reserved error code；LSP 也定义了一些错误代码，总体定义如下：
// 一些错误代码
export namespace ErrorCodes {
// 由 JSON RPC 定义
export const ParseError: integer = -32700;
export const InvalidRequest: integer = -32600;
export const MethodNotFound: integer = -32601;
export const InvalidParams: integer = -32602;
export const InternalError: integer = -32603;
/**
* JSON RPC 保留错误代码的开始
*
* LSP 的错误代码不应该被定义在这个区间之内
* 除了为了兼容而定义的 `ServerNotInitialized` 和 `UnknownErrorCode`
*
* @since 3.16.0
*/
export const jsonrpcReservedErrorRangeStart: integer = -32099;
/** @deprecated use jsonrpcReservedErrorRangeStart */
export const serverErrorStart: integer = jsonrpcReservedErrorRangeStart;
/**
* 错误代码：表示 LSP 服务器在收到 `initialized` Notification
* 之前收到了其他请求或 `Notification`
*/
export const ServerNotInitialized: integer = -32002;
export const UnknownErrorCode: integer = -32001;
/**
* JSON RPC 保留错误代码的结束
*
* @since 3.16.0
*/
export const jsonrpcReservedErrorRangeEnd = -32000;
/** @deprecated use jsonrpcReservedErrorRangeEnd */
export const serverErrorEnd: integer = jsonrpcReservedErrorRangeEnd;
/**
* LSP 保留错误代码的开始
*
* @since 3.16.0
*/
export const lspReservedErrorRangeStart: integer = -32899;
export const ContentModified: integer = -32801;
export const RequestCancelled: integer = -32800;
/**
* LSP 保留错误代码的结束
*
* @since 3.16.0
*/
export const lspReservedErrorRangeEnd: integer = -32800;
}