之前实现 ZenScript 的 LSP 的时候只是简单实现了一个 server，没有对协议相关的功能进行更深入的了解。最近四个月前因为工作原因开始重新关注起这方面的内容，于是开始对协议的相关内容进行整理清库存。

本文基于 Language Server Protocol 3.16 编写，与当前的 LSP 版本可能不完全一致，阅读时需要注意。

什么 LSP，哪有 LSP，哦，是我啊

报文划分

LSP 的报文划分为 Header 和 Content 两个部分。二者之间通过 \r\n 隔开，很有微软的风格。

Header

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;
}