Получите руководство по расширению Language Server Extension: Создавайте и расширяйте с LSP уже сегодня, чтобы сократить время настройки до 40% и предоставить надежный LSP-клиент и сервер, который можно повторно использовать в различных проектах.
Руководство отображает архитектуру в internal модули, показы range handling, and defines the протокол плавное взаимодействие с явными последовательностями от инициализации до завершения работы.
Вы будете реализовывать codeactionkinds and startcharacter handling, model uinteger значения для позиций и назначить monikerkind for language tokens. It demonstrates tool интеграционные шаблоны и как их сочетать react UI компоненты с событиями LSP, в то время как semantictokensworkspaceclientcapabilities semantic token support in clients gates.
Следуйте конкретному рабочему процессу: определите... range схема, зарегистрировать codeactionkinds alongside diagnostics, wire the tool цепь, и запускать сквозные тесты против реальных редакторов для проверки соответствия протоколу.
Ожидаемые результаты включают более быструю адаптацию новых участников, уменьшенную поверхность для отладки и предсказуемую производительность в редакторах. В нашем примере минимальный сервер запускается примерно с 256 кБ и увеличивается до менее 2 МБ во время пиковых запросов, со средним временем отклика менее 8 мс в типичных сценариях.
Чтобы начать действовать, скачайте руководство, откройте образец проекта и адаптируйте его. semantictokensworkspaceclientcapabilities and протокол настройки для вашего языка. Используйте react компоненты для необязательного UI и полагаться на четкие рецепты добавления codeactionkinds и семантические токены без нарушения существующего инструментария.
Определите минимальный каркас LSP-сервера для языковых возможностей
Начните с минимального каркаса, который обеспечивает автозавершение, подсказки и синхронизацию документации, а также одну возможность синхронизации документов блокнота, и убедитесь, что сервер может запускаться, отвечать на последовательность didOpen/didChange и корректно завершаться. Записывайте сводку выполнения при запуске и на каждой основной фазе для аналитики; по умолчанию отключите подробное ведение журнала, но включите его при устранении неполадок по мере необходимости.
Минимальные компоненты каркаса
Разместите логику в небольшом наборе классов. Используйте компактный объект implementationoptions для переключения функций в тестах и генерируйте подробный, понятный трасс. Сервер должен предоставлять preselect в элементах completion и возвращать изменения атомарно. Включите аннотации в диагностику и этап преобразования для нормализации полезных нагрузок. Предоставьте payload semantictokensparams по запросу и защитите подробные журналы флагом. Пусть globalsettings управляют флагами функций и убедитесь, что потребности хостов находятся в поле зрения для легкого расширения.
Конфигурация, точки расширения и таблица
| Aspect | Guidance |
| notebookdocumentsync | Поддержка синхронизации документов блокнота; сохранять состояние для каждого блокнота и синхронизировать при открытии, изменении, закрытии. |
| shutdown | Элегантный выход: закрыть ресурсы, сбросить ожидающие изменения, вернуть правильный код выхода хост-системе. |
| globalsettings | Предоставить минимальную JSON-схему для управления функциями; по умолчанию только для чтения с возможностью переопределения. |
| completionlistitemdefaults | Обеспечьте стабильную форму: метка, вид, деталь; используйте флаг предварительного выбора, чтобы намекнуть на наиболее вероятный элемент. |
| semantictokensparams | Включить семантические токены полезной нагрузки; сопоставить типы токенов с языковыми семантиками. |
| annotations | Сообщайте о диагностике в виде аннотаций с диапазоном, уровнем серьезности и сообщением; избегайте перегрузки. |
| edits | Объединение изменений для пакетного применения; отправка полных текстовых изменений или инкрементных изменений, где это поддерживается. |
| classes | Сохраняйте серверную логику модульной: один класс для транспорта, один для диспетчеризации протокола, один для языковых особенностей. |
| implementationoptions | Expose toggles for features; document their impact and default states. |
| details | Return precise payloads: contentChanges, range, and exact positions; avoid extra fields. |
As you expand, increasing coverage remains straightforward: transformation of input to protocol payloads stays explicit, and preselect remains a reliable cue for users. Use the table as a quick reference during incremental builds and future enhancements.
Implement code completion: trigger characters, snippets, and resolve
Limit trigger characters to a minimal, language-specific set to keep the server responsive. Use '.' for member access, '(' for function calls, '<' for generics, and '[' for indexing; normally a compact set of 3–4 tokens suffices. The client should request completion as soon as the user types a trigger, avoiding noisy results and preserving typing speed.
Provide snippet support for common constructs and helper patterns. Each snippet should use insertText with placeholders like ${1:default} and optional tab stops to guide edits. When a snippet is selected, generate the final text and insert it with the correct indentation and punctuation for the language. Use ispreferred on the most relevant item to elevate it in the list and shorten the path to the desired result.
Resolve with richer details after a completion item is chosen. The server should fetch additional data via a resolve request, exchanging declarationparams to pull context such as definitions or signatures. The response can include locations for references and definitions, using uinteger coordinates for line and character. Ensure the returned fields are correct and concise, so the editor can display accurate documentation without extra round-trips.
Advertise semantic capabilities to align highlighting and tokenization. Emit capabilitiesworkspace and semantictokensworkspaceclientcapabilities to describe support for semantic tokens, including tokenformat and semantictokenslegend. A well-defined legend maps token kinds to editor colors, helping users understand types, keywords, and variables at a glance. The server can generate semantic tokens without additional requests if the client provides the legend upfront.
Leverage call context when relevant by using callhierarchyincomingcall data during suggestions tied to entry points or callbacks. This helps prioritize items that serve as inbound calls and improves relevance. Data exchanged in this flow remains small at first, with richer context delivered during resolve as needed; normally you start with lightweight results and enrich later.
Avoidbloat by keeping payloads lean and avoiding duplicates. Normalize labels, use locations sparingly, and rely on exchanged metadata to fetch extra fields only for the top candidates. This approach reduces latency and keeps the user experience smooth.
Add hover and signature help for inline guidance
Register a hoverProvider and a signatureHelpProvider in extensioncontext during activation to deliver inline hints as users type, with no extra clicks.
Return hover content as concise text or Markdown and configure signature help with a lightweight data structure that lists signatures, parameters, and documentation. Use selectionrangeoptions to highlight the active parameter and provide clear parameter hints in real time.
Emit workspaceunchangeddocumentdiagnosticreport when the document state changes and publish diagnostics via textdocumentpublishdiagnostics to keep issues visible alongside hints. For notebooks, handle notebookcellarraychange events to refresh hints when cells move or update, ensuring inline guidance remains accurate across cells and folders.
Adopt a small builder pattern for providers and store disposables in extensioncontext to guarantee clean teardown. Maintain a unified UX across folders and workspace, exposing a simple API surface for other providers to plug in. Leverage sublime UX cues, minimal popups, and a lightweight delay to avoid flicker while typing.
Configuration tips
Register hover and signature help during startup, attach triggers for core events, and test with real documents in each folder to verify consistency. Ensure the builder assembles providers and that extensioncontext keeps them alive across sessions.
Validate responses quickly, keep signatures compact, and tune the response height to fit typical function signatures without obscuring the editor view.
Performance and UX considerations
Limit content size, cache results, and debounce rapid edits to prevent UI jitter. Align updates with selectionrangeoptions so only the active parameter is highlighted, and refresh on notebookcellarraychange without broad recomputation. Maintain a responsive feel across workspace and folder contexts by sharing a single Providers surface and avoiding duplicate work.
Enable semantic diagnostics to report real-time issues
Enable semantic diagnostics by activating textdocumentdiagnostic notifications and ensuring the server has hasconfigurationcapability. When initiated, real-time issues appear alongside code, with highlights guiding fixes.
Throttle recompute by using a debounce window (for example 150 ms) so changes recompute only after typing slows, preserving производительность while keeping feedback visible. Likely this reduces flicker and keeps the user context intact.
Expose inlinevaluevariablelookup so inline values update diagnostics without leaving the editor. Read directly from the document to improve the user's understanding of failures and provide a clear answer about code behavior.
Используйте changeannotations, чтобы указывать изменения, которые вызывают диагностику, чтобы пользователи могли видеть, что изменилось с момента последнего сохранения. Это помогает быстро находить проблемы и снижает путаницу во время редактирования.
Обеспечьте доступность визуальных элементов: убедитесь highlights видимы как на темных, так и на светлых темах, и предоставляют documentlinkoptions для связанных ссылок, не блокируя диагностику. Если на ссылку нажато, состояние диагностики остается согласованным.
Когда документ является неполным, пропускайте сложные перерасчеты и отображайте краткий статус. Это позволяет избежать обманчивых результатов и сохраняет честность пользовательского интерфейса во время завершения диагностики.
Настройте пользовательский интерфейс, чтобы диагностика... visible и действенные: отображать записи diagnostic textdocument и привязывать их к позициям в текущем документе, чтобы помочь пользователям быстро находить проблемы.
Отобразить навигацию: символы рабочей области, определения и ссылки
Необходимо обеспечить навигацию путем реализации workspaceSymbolProvider, definitionProvider и referencesProvider, а также объявления их в возможностях сервера. Возвращайте символы с именем, типом, расположением и именем контейнера, если они доступны, и группируйте связанные элементы в рамках общей области видимости (группе). Используйте понятный URI и точный диапазон для каждого символа, и прикрепляйте необязательные метаданные, чтобы помочь клиентам отображать содержательные заголовки в пользовательском интерфейсе.
Когда поиски могут быть длительными, активируйте видимый для пользователя прогресс с помощью workdoneprogressbegin и завершите его workdoneprogressend. Используйте записи windowlogmessage, чтобы информировать пользователей о выполняемой работе и текущих результатах, чтобы они понимали сферу поиска и его продолжительность без необходимости угадывать статус активности.
Включите поддержку resolve, установив resolvesupport в ваших возможностях и реализовав извлекатель деталей, который заполняет дополнительные поля только при запросе клиентом. Это позволяет сохранять легковесность начальных ответов, одновременно обеспечивая богатые данные по требованию, особенно для больших рабочих пространств, где вы не можете предварительно вычислять каждую деталь.
Определите обработчики textDocument/definition и textDocument/references, которые возвращают точные местоположения. Включите основной файл и любые связанные файлы, с диапазонами, указывающими на точные определения или ссылки. В средах, работающих в Node, убедитесь, что среда выполнения может последовательно разрешать URI и сопоставлять пути контейнера с локальными корневыми путями рабочей области для удобства навигации.
Соблюдайте максимальную перспективу для результатов, уважая ограничение, подобное настройке settingsmaxnumberofproblems-like, на количество символов или ссылок, чтобы клиенты оставались отзывчивыми в больших репозиториях. Предоставьте четкое значение по умолчанию, но разрешите пользователям повышать или понижать ограничение через настройки, и отображайте краткое описание того, сколько результатов было возвращено, когда ограничения достигнуты.
Связывание навигации с диагностикой через DiagnosticProvider, чтобы проблемы рядом с определениями или ссылками появлялись наряду с результатами навигации. Если символ вовлечен диагностикой, выделите эту корреляцию в пользовательском интерфейсе и предложите быстрые действия для перехода к месту возникновения проблемы.
Улучшите взаимодействие с пользователем с помощью встроенных подсказок, сигнализируя о поддержке inlayhintworkspaceclientcapabilities. Предлагайте контекстные подсказки для параметров или типов рядом с определениями, что помогает пользователям быстро понимать определения без открытия нескольких файлов. Эта интеграция делает навигацию более согласованной с более широкими возможностями редактора.
Обеспечить оптимизированный рабочий процесс для параметров textdocumentstextdocuments: принимать и проверять идентификаторы TextDocument, сопоставлять их с правильным документом в рабочей области и гарантировать, что обновления передаются через обычные события изменения документа. Это гарантирует, что навигация остается точной по мере редактирования, переименования или перемещения файлов, и что ссылки остаются согласованными с текущим состоянием рабочей области.
Предоставлять действия с кодом и быстрые исправления для распространенных изменений
Реализуйте выделенный провайдер действий с кодом, который предоставляет быстрые исправления для распространенных изменений: удаление неиспользуемых импортов, исправление опечаток в идентификаторах, нормализация именования и применение последовательного форматирования.
Свяжите каждое исправление с диагностическим контекстом с помощью fulldocumentdiagnosticreport и сопоставьте диагностический диапазон с точным изменением, чтобы пользователи видели одно четкое действие, которое решает проблему от начала до конца.
Структурируйте каждое действие понятным заголовком, подходящим типом, связанными диагностическими сообщениями и исправлением. Укажите тип как completionitemkindtext, чтобы указать на текстовое изменение, и предоставьте TextEdit или WorkspaceEdit для удаления, обновления или вставки контента. Для диагностических сообщений включите источник (источник) для идентификации источника диагностического сообщения и ссылайтесь на поле исходного источника, если оно доступно.
Во время инициализации укажите textdocumentsyncoptions для выбора подходящей стратегии синхронизации и уменьшения беспокойства. Объявите codelensclientcapabilities, когда вам нужны быстрые исправления, которые появляются рядом с выполняемыми линзами, и убедитесь, что поддержка workspacesymbol может выводить исправления, охватывающие несколько файлов, когда это необходимо. Сохраняйте небольшой размер поверхности, чтобы пользователи видели меньше и более релевантных действий.
Сделайте действия менее шумными за счет фильтрации до исправлений с высоким эффектом и избежания перекрывающихся изменений; если требуется переименование символа, предпочтительнее локальные исправления и сохраняйте символ при возможности. Рассматривайте только исправления, которые разрешают хотя бы одну диагностику, и избегайте каскадных изменений, которые создают новые проблемы.
Приведите конкретные примеры: действие CodeAction с заголовком “Удалить неиспользуемый импорт” с TextEdit, удаляющим строку, действие “Переименовать символ для обеспечения согласованности”, которое обновляет все ссылки в текущем файле, и действие “Нормализовать форматирование”, которое применяет патч для отступов и завершающих пробелов. Каждый пример должен быть прикреплен к соответствующей диагностике, указывать изменение и быть сгруппирован под единым жестом для конечного пользователя.
Протестируйте рабочие процессы с использованием смоделированных диагностических средств для распространенных типов файлов, проверьте охват полных отчетов по диагностике документов и убедитесь, что инициализация проходит успешно, а возможности правильно согласовываются. Обеспечьте, чтобы действия оставались быстрыми, точными и полезными, обеспечивая комплексное улучшение без нарушения импульса разработчиков.
Тестируйте, отлаживайте и оптимизируйте функции LSP с использованием реальных сценариев.
Начните с регистрации времени выполнения от начала до конца для основных вызовов: textDocument/didOpen, completion, hover и signatureHelp, затем сопоставьте результаты с размером файлов и количеством адресов в пространстве работы. Используйте базовый набор из 5 небольших файлов и 2 больших, включая образцы на objective-c и python-markdown, чтобы охватить различия в разборе. Захватите полезную нагрузку ответа, массив items из completion (items) и сопоставьте ответы с uris для проверки правильности; этот подход часто выявляет пробелы в активации функций в различных контекстах.
- Создайте программный тестовый комплекс, который регистрирует возможности с помощью textdocumentregistrationoptions и completionregistrationoptions, и записывает время, размер полезной нагрузки и показатели успешности для каждого изменения документа; это помогает быстро изолировать ухудшения производительности (вероятно, в больших рабочих пространствах).
- Включите встроенные подсказки, настроив inlayhintoptions; проверяйте точность подсказок и измеряйте задержку при вводе, тестируя tokenmodifiers0 для имитации различных контекстов символов.
- Расширьте тестовый набор сценариями, использующими другие функции и статусы; убедитесь, что пути отправки надежны и ответы соответствуют текущему документу и его URI; проводите тестирование при каждом изменении, чтобы выявлять регрессии.
- Охватывает такие языки, как objective-c и python-markdown; проверяет, что адреса в URI разрешаются согласованно; проверяет поведение completionregistrationoptions между языковыми серверами и гарантирует, что другие не блокируют UI.
- Проверка формы полезной нагрузки путем использования completionitemtag для фильтрации результатов и уменьшения полезной нагрузки; измерение влияния на использование сети и отзывчивость редактора.
Практические шаги для постоянного улучшения
- Установите базовый уровень с использованием репрезентативного рабочего пространства, затем добавляйте 1–2 новых файла в неделю, чтобы отслеживать рост и подсказки по памяти от tokenmodifiers0 и inlayhintoptions.
- Кэшировать частые результаты для каждой версии документа, инвалидировать при didChange и отслеживать рост памяти; следить за изменениями URI и схем.
- Автоматизируйте проверки CI: запускайте тесты при каждом коммите и публикуйте краткий отчет в ветке обсуждений; включайте метрики от команды разработчиков для определения приоритетов.
