LSP 开发指南 / 第 15 章：最佳实践

// 分层示例
class LanguageServer {
  private protocol: ProtocolHandler;    // 协议层
  private services: ServiceManager;     // 业务层
  private analyzer: ProjectAnalyzer;    // 分析层
  private fileSystem: FileSystem;       // 基础设施层

  constructor() {
    this.fileSystem = new FileSystem();
    this.analyzer = new ProjectAnalyzer(this.fileSystem);
    this.services = new ServiceManager(this.analyzer);
    this.protocol = new ProtocolHandler(this.services);
  }
}

// ❌ 错误：业务逻辑与协议混合
connection.onRequest("textDocument/completion", (params) => {
  const doc = documents.get(params.textDocument.uri);
  const lines = doc.split("\n");
  const line = lines[params.position.line];
  // ... 50 行解析逻辑 ...
  return items;
});

// ✅ 正确：分离业务逻辑
class CompletionService {
  getCompletions(document: string, position: Position): CompletionItem[] {
    // 纯业务逻辑，可独立测试
  }
}

connection.onRequest("textDocument/completion", (params) => {
  const doc = documents.get(params.textDocument.uri);
  if (!doc) return { items: [] };
  return completionService.getCompletions(doc, params.position);
});

class IncrementalAnalyzer {
  private documentASTs = new Map<string, AST>();
  private dirtyDocuments = new Set<string>();

  onDocumentChange(uri: string, changes: TextChange[]): void {
    // 增量更新 AST，而非重新解析
    const ast = this.documentASTs.get(uri);
    if (ast) {
      for (const change of changes) {
        updateAST(ast, change);
      }
    } else {
      this.dirtyDocuments.add(uri);
    }
  }

  async analyzeDirtyDocuments(): Promise<void> {
    const toAnalyze = [...this.dirtyDocuments];
    this.dirtyDocuments.clear();

    // 分批处理，避免阻塞
    for (let i = 0; i < toAnalyze.length; i += 10) {
      const batch = toAnalyze.slice(i, i + 10);
      await Promise.all(batch.map((uri) => this.reanalyze(uri)));

      // 让出事件循环
      await new Promise((r) => setImmediate(r));
    }
  }
}

class DebouncedDiagnostics {
  private timers = new Map<string, NodeJS.Timeout>();

  scheduleValidation(uri: string, delay: number = 300): void {
    // 清除之前的定时器
    const existing = this.timers.get(uri);
    if (existing) clearTimeout(existing);

    // 设置新的定时器
    const timer = setTimeout(() => {
      this.timers.delete(uri);
      this.validate(uri);
    }, delay);

    this.timers.set(uri, timer);
  }

  validateImmediately(uri: string): void {
    const existing = this.timers.get(uri);
    if (existing) clearTimeout(existing);
    this.timers.delete(uri);
    this.validate(uri);
  }

  private validate(uri: string): void {
    // 执行实际的分析
  }
}

// 使用
connection.onNotification("textDocument/didChange", (params) => {
  docManager.applyChanges(params);
  diagnostics.scheduleDiagnostics(params.textDocument.uri);
});

connection.onNotification("textDocument/didSave", (params) => {
  diagnostics.validateImmediately(params.textDocument.uri);
});

class ParallelAnalyzer {
  private workerPool: Worker[] = [];
  private maxWorkers = os.cpus().length;

  constructor() {
    for (let i = 0; i < this.maxWorkers; i++) {
      this.workerPool.push(new Worker("./analyzer-worker.js"));
    }
  }

  async analyzeFiles(files: string[]): Promise<Map<string, Diagnostic[]>> {
    const results = new Map<string, Diagnostic[]>();
    const chunks = this.chunkArray(files, this.maxWorkers);

    const promises = chunks.map((chunk, i) => {
      const worker = this.workerPool[i % this.maxWorkers];
      return this.sendToWorker(worker, chunk).then((diagnostics) => {
        for (const [uri, diags] of diagnostics) {
          results.set(uri, diags);
        }
      });
    });

    await Promise.all(promises);
    return results;
  }
}

class LRUCache<K, V> {
  private cache = new Map<K, V>();
  private maxSize: number;

  constructor(maxSize: number) {
    this.maxSize = maxSize;
  }

  get(key: K): V | undefined {
    const value = this.cache.get(key);
    if (value !== undefined) {
      // 移到最后（最近使用）
      this.cache.delete(key);
      this.cache.set(key, value);
    }
    return value;
  }

  set(key: K, value: V): void {
    if (this.cache.has(key)) {
      this.cache.delete(key);
    } else if (this.cache.size >= this.maxSize) {
      // 删除最旧的条目
      const firstKey = this.cache.keys().next().value;
      this.cache.delete(firstKey);
    }
    this.cache.set(key, value);
  }
}

// 使用缓存
class CachedAnalyzer {
  private completionCache = new LRUCache<string, CompletionItem[]>(100);
  private hoverCache = new LRUCache<string, Hover>(200);

  getCompletions(uri: string, position: Position): CompletionItem[] | null {
    const key = `${uri}:${position.line}:${position.character}`;
    return this.completionCache.get(key) ?? null;
  }

  setCompletions(uri: string, position: Position, items: CompletionItem[]): void {
    const key = `${uri}:${position.line}:${position.character}`;
    this.completionCache.set(key, items);
  }

  invalidate(uri: string): void {
    // 失效该文件的所有缓存
    for (const key of this.completionCache.keys()) {
      if (key.startsWith(uri)) {
        this.completionCache.delete(key);
      }
    }
  }
}

class ErrorHandler {
  constructor(private connection: any) {}

  handleRequestError(err: any, method: string): ResponseError {
    console.error(`Error in ${method}:`, err);

    if (err instanceof ResponseError) {
      return err;
    }

    if (err instanceof SyntaxError) {
      return new ResponseError(
        ErrorCodes.ParseError,
        `Parse error in ${method}: ${err.message}`
      );
    }

    return new ResponseError(
      ErrorCodes.InternalError,
      `Internal error in ${method}: ${err.message}`
    );
  }

  wrapHandler<P, R>(
    method: string,
    handler: (params: P) => R | Promise<R>
  ): (params: P) => Promise<R> {
    return async (params: P): Promise<R> => {
      try {
        return await handler(params);
      } catch (err) {
        throw this.handleRequestError(err, method);
      }
    };
  }
}

// 使用
const errorHandler = new ErrorHandler(connection);

connection.onRequest(
  "textDocument/completion",
  errorHandler.wrapHandler("textDocument/completion", (params) => {
    return completionService.getCompletions(params);
  })
);

class ResilientAnalyzer {
  async analyzeWithFallback(text: string): Promise<Diagnostic[]> {
    try {
      // 尝试完整分析
      return await this.fullAnalysis(text);
    } catch (err) {
      console.error("Full analysis failed, falling back:", err);

      try {
        // 降级到快速分析
        return await this.quickAnalysis(text);
      } catch (err2) {
        console.error("Quick analysis failed:", err2);
        // 最终降级：只返回语法错误
        return this.syntaxOnlyAnalysis(text);
      }
    }
  }
}

class RecoverableServer {
  private errorCount = 0;
  private maxErrors = 10;

  async handleRequest(method: string, handler: () => Promise<any>): Promise<any> {
    try {
      const result = await handler();
      this.errorCount = 0; // 成功后重置
      return result;
    } catch (err) {
      this.errorCount++;
      console.error(`Error #${this.errorCount} in ${method}:`, err);

      if (this.errorCount >= this.maxErrors) {
        // 触发重启
        this.connection.sendNotification("window/showMessage", {
          type: MessageType.Error,
          message: "Server encountered too many errors, restarting...",
        });
        this.restart();
      }

      throw err;
    }
  }
}

enum LogLevel {
  DEBUG = 0,
  INFO = 1,
  WARN = 2,
  ERROR = 3,
}

class Logger {
  private level: LogLevel = LogLevel.INFO;

  constructor(private connection: any) {}

  log(level: LogLevel, message: string, data?: any): void {
    if (level < this.level) return;

    const entry = {
      timestamp: new Date().toISOString(),
      level: LogLevel[level],
      message,
      data,
    };

    // 输出到 stderr（不干扰协议）
    process.stderr.write(JSON.stringify(entry) + "\n");

    // 同时发送到客户端
    const lspType = [4, 3, 2, 1][level]; // Log, Info, Warning, Error
    this.connection.sendNotification("window/logMessage", {
      type: lspType,
      message: `[${entry.level}] ${message}`,
    });
  }

  debug(msg: string, data?: any): void { this.log(LogLevel.DEBUG, msg, data); }
  info(msg: string, data?: any): void { this.log(LogLevel.INFO, msg, data); }
  warn(msg: string, data?: any): void { this.log(LogLevel.WARN, msg, data); }
  error(msg: string, data?: any): void { this.log(LogLevel.ERROR, msg, data); }
}

class PerformanceMonitor {
  private metrics = new Map<string, number[]>();

  measure<T>(name: string, fn: () => T | Promise<T>): T | Promise<T> {
    const start = performance.now();
    const result = fn();

    if (result instanceof Promise) {
      return result.then((value) => {
        this.record(name, performance.now() - start);
        return value;
      });
    }

    this.record(name, performance.now() - start);
    return result;
  }

  private record(name: string, duration: number): void {
    if (!this.metrics.has(name)) {
      this.metrics.set(name, []);
    }
    this.metrics.get(name)!.push(duration);
  }

  getReport(): Record<string, { avg: number; p95: number; count: number }> {
    const report: any = {};
    for (const [name, durations] of this.metrics) {
      const sorted = [...durations].sort((a, b) => a - b);
      report[name] = {
        avg: sorted.reduce((a, b) => a + b, 0) / sorted.length,
        p95: sorted[Math.floor(sorted.length * 0.95)],
        count: sorted.length,
      };
    }
    return report;
  }
}

// package.json
{
  "name": "my-language-server",
  "version": "1.0.0",
  "description": "Language Server for MyLang",
  "main": "dist/server.js",
  "bin": {
    "my-lang-server": "./bin/server.js"
  },
  "files": ["dist", "bin", "README.md"],
  "engines": {
    "node": ">=18"
  },
  "keywords": [
    "language-server",
    "lsp",
    "mylang",
    "code-intelligence"
  ],
  "license": "MIT"
}

#!/usr/bin/env node
// bin/server.js
require("../dist/server.js");

npm publish

// package.json
{
  "name": "my-lang-support",
  "displayName": "MyLang Language Support",
  "publisher": "my-publisher",
  "version": "1.0.0",
  "engines": { "vscode": "^1.75.0" },
  "categories": ["Programming Languages"],
  "keywords": ["mylang", "lsp"],
  "repository": {
    "type": "git",
    "url": "https://github.com/user/my-lsp"
  },
  "bugs": {
    "url": "https://github.com/user/my-lsp/issues"
  }
}

# 安装 vsce
npm install -g @vscode/vsce

# 打包
vsce package

# 发布
vsce publish

-- 在 nvim-lspconfig 中注册
-- lua/lspconfig/configs/my_lang.lua
local util = require "lspconfig.util"

return {
  default_config = {
    cmd = { "my-lang-server", "--stdio" },
    filetypes = { "mylang" },
    root_dir = util.root_pattern(".git", "mylang.toml"),
    settings = {},
  },
  docs = {
    description = [[
https://github.com/user/my-lsp

Language server for MyLang.
]],
    default_config = {
      root_dir = [[root_pattern(".git", "mylang.toml")]],
    },
  },
}

# pyproject.toml
[project]
name = "my-language-server"
version = "1.0.0"
description = "Language Server for MyLang"
license = {text = "MIT"}
requires-python = ">=3.10"
dependencies = [
    "pygls>=1.0.0",
]

[project.scripts]
my-lang-server = "my_lsp.server:main"

pip install build twine
python -m build
twine upload dist/*

# MyLang Language Server

[![npm](https://img.shields.io/npm/v/my-lang-server)](https://www.npmjs.com/package/my-lang-server)

Language Server Protocol implementation for MyLang.

## Features

- ✅ Code completion
- ✅ Hover information
- ✅ Go to definition
- ✅ Find references
- ✅ Diagnostics
- ✅ Code formatting
- ✅ Code actions

## Installation

\`\`\`bash
npm install -g my-lang-server
\`\`\`

## Editor Setup

### VS Code
Install the [MyLang extension](https://marketplace.visualstudio.com/items?itemName=my.my-lang).

### Neovim
\`\`\`lua
require('lspconfig').my_lang.setup({})
\`\`\`

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `maxProblems` | number | 100 | Max diagnostics per file |
| `enableTypeChecking` | boolean | true | Enable type checking |

## Development

\`\`\`bash
npm install
npm run build
npm test
\`\`\`