Документация для авторов плагинов
Если вы интегрируете gopls в редактор, создавая плагин для редактора, существует довольно много семантики общения между редактором и gopls, которые не определены в спецификации LSP.
Мы пытаемся документировать эти детали, а также любую другую информацию, которая была полезна другим авторам плагинов, здесь.
Если вы сами реализуете плагин и у вас есть вопросы, на которые не отвечает эта страница, пожалуйста, свяжитесь с нами, чтобы задать их, а затем также добавьте свои наработки обратно на эту страницу.
Поддерживаемые возможности
В основном вы должны обращаться к Списку возможностей, чтобы узнать, поддерживает ли gopls ту или иную функцию.
Для получения действительно авторитетного ответа следует проверить результат запроса initialize, где gopls перечисляет свою поддержку в ServerCapabilities.
Позиции и диапазоны
Многие запросы LSP передают информацию о позиции или диапазоне. Это описано в спецификации LSP:
Позиция внутри документа (см. определение Position ниже) выражается как смещение по строке и символу, начиная с нуля. Смещения основаны на строковом представлении в UTF-16. Таким образом, строка вида a𐐀b имеет смещение символа a равным 0, смещение символа 𐐀 равно 1, а смещение символа b равно 3, поскольку 𐐀 представлен двумя кодовыми единицами в UTF-16.
Это означает, что интеграторы должны будут вычислять смещения столбцов, основанные на UTF-16. Используйте protocol.Mapper для всех преобразований.
Правки
Чтобы доставлять изменения от gopls в редактор, LSP поддерживает массивы TextEdit в ответах.
Спецификация точно указывает, как должны применяться эти правки:
Все диапазоны текстовых правок относятся к позициям в исходном документе. Диапазоны текстовых правок никогда не должны пересекаться, то есть ни одна часть исходного документа не должна быть изменена более чем одной правкой. Однако возможно, что несколько правок имеют одну и ту же начальную позицию: несколько вставок или любое количество вставок, за которыми следует одна правка удаления или замены. Если несколько вставок имеют одну и ту же позицию, порядок в массиве определяет порядок строк, вставляемых в результирующий текст.
Все []TextEdit отсортированы таким образом, что применение массива дельт, полученных в обратном порядке, достигает желаемого результата, который соответствует спецификации.
Ошибки
Различные коды ошибок описаны в спецификации LSP. В настоящее время всё ещё определяется, что означает возврат ошибки методом; являются ли ошибки исключительно низкоуровневыми проблемами LSP/транспорта или могут ли другие условия вызывать возврат ошибок? См. часть этого обсуждения на #31526.
Выбранный метод пока influenced влияет на точное обращение в популярных сейчас интеграциях редакторов. Вероятно, он изменится, и в идеале должен стать более согласованным между запросами.
textDocument/codeAction: Возвращать ошибку, если произошла ошибка при вычислении действий кода.textDocument/completion: Логгировать ошибки, возвращать пустой список результатов.textDocument/definition: Возвращать ошибку, если произошла ошибка при вычислении определения для позиции.textDocument/typeDefinition: Возвращать ошибку, если произошла ошибка при вычислении определения типа для позиции.textDocument/formatting: Возвращать ошибку, если произошла ошибка форматирования файла.textDocument/highlight: Логгировать ошибки, возвращать пустой результат.textDocument/hover: Возвращать пустой результат.textDocument/documentLink: Логгировать ошибки, возвращать nil результат.textDocument/publishDiagnostics: Логгировать ошибки, если они возникли при вычислении диагностик.textDocument/references: Логгировать ошибки, возвращать пустой результат.textDocument/rename: Возвращать ошибку, если произошла ошибка при вычислении переименований.textDocument/signatureHelp: Логгировать ошибки, возвращать nil результат.textDocument/documentSymbols: Возвращать ошибку, если произошла ошибка при вычислении символов документа.
Отслеживание файлов
Довольно обычное явление — изменение файлов, влияющих на работу gopls, вне редактора, с которым он ассоциирован.
Например, файлы, необходимые для корректной проверки типов, могут изменяться при переключении веток в git или обновляться генератором кода.
Прямое отслеживание файлов внутри gopls сопряжено с множеством неудобств, но спецификация LSP предоставляет методы, позволяющие gopls запрашивать у клиента уведомления об изменениях файловой системы, а именно workspace/didChangeWatchedFiles.
Эта функциональность в настоящее время добавляется в gopls участником сообщества и отслеживается в #31553
Исходные файлы этой документации можно найти в golang.org/x/tools/gopls/doc.
