Obtenga la Guía de la Extensión del Servidor de Lenguaje: Construya y Extienda con LSP hoy para reducir el tiempo de configuración hasta en un 40% y entregar un cliente y servidor LSP robustos que pueda reutilizar en todos los proyectos.
La guía mapea la arquitectura en internal módulos, espectáculos range handling, y define los protocolo fluir con secuencias explícitas desde la inicialización hasta el apagado.
Implementarás codeactionkinds and startcharacter handling, model uinteger valores para posiciones, y asignar monikerkind for language tokens. It demonstrates tool patrones de integración y cómo combinarlos react Componentes de IU con los eventos LSP, mientras semantictokensworkspaceclientcapabilities soporte de tokens semánticos de gates en clientes.
Siga un flujo de trabajo concreto: defina un range schema, registrar codeactionkinds junto con los diagnósticos, cablear el tool cadena, y ejecutar pruebas de extremo a extremo contra editores reales para verificar el cumplimiento del protocolo.
Los resultados esperados incluyen una incorporación más rápida para los nuevos contribuyentes, una superficie de depuración más pequeña y un rendimiento predecible en todos los editores. En nuestra muestra, un servidor mínimo comienza en aproximadamente 256 kB y crece a menos de 2 MB durante los picos de solicitudes, con tiempos de respuesta promedio inferiores a 8 ms en escenarios típicos.
Para actuar, descargue la guía, abra el proyecto de ejemplo y adapte el semantictokensworkspaceclientcapabilities and protocolo configuraciones a tu idioma. Usa react componentes para una interfaz de usuario opcional, y confiar en las recetas claras para agregar codeactionkinds y tokens semánticos sin interrumpir las herramientas existentes.
Define a minimal LSP server scaffold for language features
Comience con un andamio mínimo que exponga autocompletado, sugerencias al pasar el cursor y documentSync, más una única capacidad de notebookdocumentsync, y asegúrese de que el servidor pueda iniciarse, responder a una secuencia de didOpen/didChange y cerrarse correctamente. Registre un executionsummary al inicio y en cada fase importante para ayudar con las analíticas; mantenga los registros detallados desactivados de forma predeterminada, pero actívelos al solucionar problemas según sea necesario.
Componentes de andamiaje mínimos
Coloque la lógica en un pequeño conjunto de clases. Use un objeto compacto de opciones de implementación para alternar funciones en las pruebas, y emita un rastro claro, primero con los detalles. El servidor debe exponer preseleccionados en los elementos de finalización y devolver las ediciones de forma atómica. Incluya anotaciones en los diagnósticos y un paso de transformación para normalizar las cargas útiles. Proporcione una carga útil de parámetros de tokens semánticos bajo demanda, y proteja los registros detallados detrás de una bandera. Deje que la configuración global dirija las banderas de función, y asegúrese de que las necesidades de los hosts estén a la vista para una fácil extensión.
Configuración, puntos de extensión y tabla
| Aspect | Guidance |
| notebookdocumentsync | Soporte para la sincronización de documentos de notebook; mantener el estado por notebook y sincronizar en didOpen, didChange, didClose. |
| shutdown | Salida elegante: cerrar recursos, vaciar modificaciones pendientes, devolver el código de salida correcto al host. |
| globalsettings | Exponer un esquema JSON mínimo para controlar las características; valores predeterminados de solo lectura con anulaciones. |
| completionlistitemdefaults | Proporcionar una forma estable: etiqueta, tipo, detalle; usar la bandera de preselección para sugerir el elemento más probable. |
| semantictokensparams | Activar cargas útiles de tokens semánticos; asignar tipos de tokens a la semántica del lenguaje. |
| anotaciones | Informar diagnósticos como anotaciones con rango, severidad, mensaje; evitar inundaciones. |
| edits | Agregación de ediciones para aplicación por lotes; enviar ediciones de texto completo o cambios incrementales donde sea compatible. |
| classes | Mantener la lógica del servidor modular: una clase para el transporte, una para el despacho de protocolos y una para las características del lenguaje. |
| implementationoptions | Exponer interruptores para funciones; documentar su impacto y estados predeterminados. |
| details | Devolver payloads precisos: cambios de contenido, rango y posiciones exactas; evitar campos extra. |
A medida que expande, aumentar la cobertura sigue siendo sencillo: la transformación de la entrada a cargas útiles de protocolo se mantiene explícita, y la preselección sigue siendo una indicación confiable para los usuarios. Utilice la tabla como referencia rápida durante las compilaciones incrementales y las mejoras futuras.
Implementar finalización de código: caracteres de activación, fragmentos y resolución
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.
Proporcionar soporte para fragmentos para construcciones y patrones de ayuda comunes. Cada fragmento debe usar insertText con marcadores de posición como ${1:default} y puntos de parada opcionales para guiar las ediciones. Cuando se selecciona un fragmento, generar el texto final e insertarlo con la sangría y la puntuación correctas para el idioma. Use ispreferred en el elemento más relevante para elevarlo en la lista y acortar el camino hacia el resultado deseado.
Resolver con detalles más ricos después de que se elija un elemento de finalización. El servidor debe obtener datos adicionales a través de una solicitud de resolución, intercambiando declarationparams para obtener contexto como definiciones o firmas. La respuesta puede incluir ubicaciones para referencias y definiciones, usando uinteger coordenadas para línea y carácter. Asegúrese de que los campos devueltos sean correct y conciso, para que el editor pueda mostrar documentación precisa sin viajes de ida y vuelta adicionales.
Publicitar las capacidades semánticas to align highlighting and tokenization. Emit capabilitiesworkspace y semantictokensworkspaceclientcapabilities para describir el soporte para tokens semánticos, incluyendo tokenformat and semantictokenslegend. Una leyenda bien definida mapea los tipos de token a los colores del editor, ayudando a los usuarios a comprender los tipos, palabras clave y variables de un vistazo. El servidor puede generar tokens semánticos sin solicitudes adicionales si el cliente proporciona la leyenda por adelantado.
Aprovechar el contexto de la llamada cuando sea relevante usando callhierarchyincomingcall datos durante sugerencias vinculadas a puntos de entrada o callbacks. Esto ayuda a priorizar elementos que sirven como llamadas entrantes y mejora la relevancia. Los datos intercambiados en este flujo se mantienen pequeños al principio, con un contexto más completo entregado durante la resolución según sea necesario; normalmente se comienza con resultados livianos y se enriquece más tarde.
Evitarbloat by keeping payloads lean and avoiding duplicates. Normalize labels, use ubicaciones con moderación, y depender de intercambiado metadatos para obtener campos adicionales solo para los candidatos principales. Este enfoque reduce la latencia y mantiene la experiencia del usuario fluida.
Agregar información sobre herramientas y ayuda con la firma para una guía en línea
Registre un proveedor de sugerencias al pasar el cursor (hoverProvider) y un proveedor de sugerencias de firma (signatureHelpProvider) en extensioncontext durante la activación para ofrecer sugerencias en línea mientras los usuarios escriben, sin clics adicionales.
Devuelve el contenido al pasar el cursor como texto conciso o Markdown y configura la ayuda para la firma con una estructura de datos ligera que enumere las firmas, los parámetros y la documentación. Utiliza selectionrangeoptions para resaltar el parámetro activo y proporcionar sugerencias claras de parámetros en tiempo real.
Emitir informe de diagnóstico de documento sin cambios en el espacio de trabajo cuando el estado del documento cambia y publicar diagnósticos a través de textdocumentpublishdiagnostics para mantener los problemas visibles junto con las sugerencias. Para cuadernos, manejar eventos de notebookcellarraychange para actualizar las sugerencias cuando las celdas se muevan o actualicen, asegurando que la orientación en línea siga siendo precisa en las celdas y carpetas.
Adopte un patrón de construcción pequeño para proveedores y almacene elementos desechables en extensioncontext para garantizar una limpieza adecuada. Mantenga una experiencia de usuario (UX) unificada en carpetas y espacio de trabajo, exponiendo una superficie de API simple para que otros proveedores puedan integrarse. Aproveche las señales de UX de Sublime, ventanas emergentes mínimas y un retardo ligero para evitar el parpadeo al escribir.
Consejos de configuración
Registrar la ayuda de información al pasar el cursor y la ayuda con la firma durante el inicio, adjuntar disparadores para eventos principales, y probar con documentos reales en cada carpeta para verificar la consistencia. Asegurarse de que el constructor ensambla proveedores y que extensioncontext los mantiene activos a través de las sesiones.
Valide rápidamente las respuestas, mantén las firmas compactas y ajusta la altura de la respuesta para que se ajuste a las firmas de función típicas sin obstruir la vista del editor.
Consideraciones de rendimiento y UX
Limitar el tamaño del contenido, almacenar en caché los resultados y reducir la sensibilidad de las ediciones rápidas para evitar el parpadeo de la interfaz de usuario. Alinear las actualizaciones con las opciones de rango de selección para que solo se resalte el parámetro activo, y actualizar al cambiar la matriz de celdas de libreta de notas sin volver a calcular en general. Mantener una sensación de capacidad de respuesta en los contextos de espacio de trabajo y carpeta compartiendo una única superficie de Proveedores y evitando el trabajo duplicado.
Habilita los diagnósticos semánticos para reportar problemas en tiempo real
Habilite el diagnóstico semántico activando las notificaciones textdocumentdiagnostic y asegurándose de que el servidor tenga hasconfigurationcapability. Cuando se inicia, los problemas en tiempo real aparecen junto con el código, con destacados correcciones de guiado.
Reducir el reajuste mediante el uso de una ventana de espera (por ejemplo, 150 ms) para que los cambios se recalculen solo después de que la escritura disminuya, conservando rendimiento while keeping feedback visible. Probablemente esto reduce el parpadeo y mantiene intacto el contexto del usuario.
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 sobre el comportamiento del código.
Usar changeannotations para indicar ediciones que activan diagnósticos, para que los usuarios puedan ver qué cambió desde el último guardado. Esto ayuda a localizar problemas rápidamente y reduce la confusión durante las ediciones.
Mantener las imágenes accesibles: asegurarse destacados son visibles tanto en temas oscuros como claros, y proporcionan opciones de enlace de documento para enlaces relacionados sin interrumpir los diagnósticos. Si se hace clic en un enlace, el estado del diagnóstico se mantiene consistente.
Cuando un documento está incompleto, omita los recálculos complejos y muestre un estado conciso. Esto evita resultados engañosos y mantiene la experiencia del usuario honesta mientras finalizan los diagnósticos.
Configure la interfaz de usuario para que los diagnósticos sean visible y accionables: mostrar entradas de diagnóstico de textdocument y vincularlas con posiciones en el documento actual para ayudar a los usuarios a localizar problemas rápidamente.
Exponer la navegación: símbolos, definiciones y referencias del espacio de trabajo
Debe exponer la navegación implementando workspaceSymbolProvider, definitionProvider e referencesProvider y publicitándolos en las capacidades de su servidor. Devuelva símbolos con nombre, tipo, ubicación y containerName cuando estén disponibles, y agrupe elementos relacionados dentro de un alcance común (группе). Utilice un URI claro y un rango preciso para cada símbolo, y adjunte metadatos opcionales para ayudar a los clientes a mostrar títulos significativos en la interfaz de usuario.
Cuando las búsquedas puedan ser largas, activa una barra de progreso visible para el usuario con workdoneprogressbegin y completa con workdoneprogressend. Emite entradas de windowlogmessage para informar a los usuarios sobre el trabajo en curso y los resultados actuales, para que comprendan el alcance y la duración de la búsqueda sin necesidad de adivinar el estado de la actividad.
Habilite el soporte de resolución configurando resolvesupport en sus capacidades e implementando un recuperador de detalles que complete campos adicionales solo cuando el cliente los solicite. Esto mantiene las respuestas iniciales livianas al mismo tiempo que permite datos enriquecidos bajo demanda, especialmente para espacios de trabajo grandes donde no puede precalcular cada detalle por adelantado.
Defina los controladores textDocument/definition y textDocument/references que devuelvan ubicaciones precisas. Incluya tanto el archivo principal como cualquier archivo relacionado, con rangos que apunten a definiciones o referencias exactas. En entornos que se ejecutan en Node, asegúrese de que el tiempo de ejecución pueda resolver URIs de forma consistente y mapear las rutas de los contenedores a las raíces locales del espacio de trabajo para una experiencia de navegación fluida.
Respete una perspectiva máxima para los resultados mediante el cumplimiento de un límite similar a settingsmaxnumberofproblems en los recuentos de símbolos o referencias, para que los clientes sigan siendo receptivos en repositorios masivos. Proporcione un valor predeterminado claro, pero permita a los usuarios aumentar o disminuir el límite a través de la configuración, y muestre un resumen conciso de cuántos resultados se devolvieron cuando se alcanzan los límites.
Conectar la navegación con el diagnóstico a través de diagnosticprovider, para que los problemas cerca de las definiciones o referencias aparezcan junto con los resultados de navegación. Si un símbolo está implicado por un diagnóstico, resaltar esa correlación en la UI y ofrecer acciones rápidas para saltar a la ubicación del problema.
Mejore la experiencia del usuario con pistas integradas señalando la compatibilidad con inlayhintworkspaceclientcapabilities. Ofrezca pistas contextuales para parámetros o tipos adyacentes a definiciones, lo que ayuda a los usuarios a comprender las definiciones rápidamente sin abrir varios archivos. Esta integración hace que la navegación se sienta cohesionada con las características más amplias del editor.
Proporcionar un flujo de trabajo optimizado para los parámetros textdocumentstextdocument: aceptar y validar los identificadores de TextDocument, mapearlos al documento correcto en el espacio de trabajo y garantizar que las actualizaciones fluyan a través de los eventos de cambio de documento normales. Esto garantiza que la navegación siga siendo precisa a medida que los archivos se editan, se renombran o se mueven, y que las referencias se mantengan alineadas con el estado actual del espacio de trabajo.
Proporcionar acciones de código y correcciones rápidas para ediciones comunes
Implementar un proveedor de acciones de código dedicado que muestre correcciones rápidas para ediciones comunes: eliminar importaciones no utilizadas, corregir errores tipográficos en identificadores, normalizar la denominación y aplicar un formato coherente.
Relaciona cada corrección con el contexto de diagnóstico utilizando fulldocumentdiagnosticreport, y mapea el rango de diagnóstico a una edición precisa para que los usuarios vean una única acción clara que resuelve el problema de principio a fin.
Estructure cada acción con un título claro, un tipo apropiado, diagnósticos asociados y una edición. Especifique el tipo como completionitemkindtext para indicar un cambio orientado al texto, y proporcione un TextEdit o WorkspaceEdit que elimine, actualice o inserte contenido. Para los diagnósticos, incluya el источник para identificar la fuente del diagnóstico, y haga referencia al campo fuente original cuando esté disponible.
Durante la inicialización, especifique textdocumentsyncoptions para elegir la estrategia de sincronización apropiada y reducir la actividad excesiva; declare codelensclientcapabilities cuando desee que las correcciones rápidas aparezcan junto a lentes ejecutables, y asegúrese de que el soporte de workspacesymbol pueda mostrar correcciones que abarquen varios archivos cuando sea necesario. Mantenga la superficie compacta para que los usuarios vean menos acciones más relevantes.
Mantén las acciones menos ruidosas filtrando para correcciones de alto impacto y evitando ediciones superpuestas; si se requiere un cambio de nombre de símbolo, prefiere correcciones localizadas y mantén el símbolo cuando sea seguro hacerlo. Considera solo las correcciones que resuelven al menos un diagnóstico y evita las ediciones en cascada que crean nuevos problemas.
Proporcione ejemplos concretos: una acción CodeAction titulada “Eliminar importación no utilizada” con una edición de texto que elimina la línea, una acción “Renombrar símbolo para mantener la coherencia” que actualiza todas las referencias en el archivo actual y una acción “Normalizar formato” que aplica un parche a espacios finales e indentación. Cada ejemplo debe adjuntarse al diagnóstico relevante, especificar la edición y agruparse bajo un único gesto de usuario final.
Probar flujos de trabajo con diagnósticos simulados en tipos de archivo comunes, verificar la cobertura del informe de diagnóstico de documento completo y validar que la inicialización se complete y que las capacidades se negocien correctamente. Asegurarse de que las acciones sigan siendo rápidas, precisas y útiles, ofreciendo una mejora de extremo a extremo sin interrumpir el impulso del desarrollador.
Probar, depurar y optimizar las funciones LSP con escenarios reales
Comience registrando los tiempos de extremo a extremo para llamadas principales: textDocument/didOpen, autocompletado, información sobre la colocación del cursor y ayuda para firmas, y luego correlacione los resultados con los tamaños de archivo y el número de адресов en el espacio de trabajo. Use un conjunto de referencia de 5 archivos pequeños y 2 archivos más grandes, incluyendo ejemplos en objective-c y python-markdown para cubrir las diferencias de análisis. Capture la carga útil de la respuesta, el array de elementos de autocompletado (items), y mapee las respuestas a uris para verificar la corrección; este enfoque a menudo revela brechas en la activación de funciones en diferentes contextos.
- Establecer un entorno de pruebas programático que registre funciones con textdocumentregistrationoptions y completionregistrationoptions, y registre el tiempo de ejecución, el tamaño de la carga útil y las tasas de éxito para cada cambio de documento; esto ayuda a aislar rápidamente las regresiones de rendimiento (probablemente en espacios de trabajo grandes).
- Habilite las sugerencias en línea configurando inlayhintoptions; verifique la precisión de las sugerencias y mida la latencia de la escritura, probando tokenmodifiers0 para simular diferentes contextos de símbolos.
- Ampliar el conjunto de pruebas con escenarios que ejerciten otras características y estados; asegurar que las rutas de envío sean robustas y que las respuestas se ajusten al documento activo y a sus URIs; ejercitar siempre que se produzcan ediciones para detectar regresiones.
- Cubrir lenguajes como objective-c y python-markdown; verificar que las direcciones a través de uris se resuelvan de manera consistente; validar el comportamiento de completionregistrationoptions a través de servidores de lenguaje y asegurarse de que otros no bloqueen la interfaz de usuario.
- Prueba del modelado de carga útil utilizando completionitemtag para filtrar resultados y reducir cargas útiles; mide el efecto en el uso de la red y la capacidad de respuesta del editor.
Pasos prácticos para la mejora continua
- Establece una línea de base con un espacio de trabajo representativo, luego agrega 1–2 archivos nuevos semanalmente para monitorear el crecimiento y los consejos de memoria de tokenmodifiers0 e inlayhintoptions.
- Almacenar en caché los resultados frecuentes por versión del documento, invalidar al cambiar, y rastrear el crecimiento de la memoria; vigilar los cambios en los uris y esquemas.
- Automatizar las comprobaciones de CI: ejecutar las pruebas en cada confirmación y publicar un informe conciso en el hilo de discusión; incluir métricas del equipo de desarrollo para guiar las prioridades.
