---
title: "Performance Contracts"
type: concept
tags: [performance, latency, engineering]
sources: [lsp-index-engineer]
last_updated: 2026-04-25
---

## Definition

性能契约（Performance Contracts）是 LSP/Index Engineer 定义的量化性能约束体系，为 graphd 系统的每个关键操作设定明确的延迟、吞吐量和资源上限，作为所有实现决策的北极星指标。

## Contract Table

| Operation | Constraint | Notes |
|-----------|-----------|-------|
| `/graph` endpoint | <100ms | 数据集 <10k 节点 |
| `/nav/:symId` (cached) | <20ms | 缓存命中 |
| `/nav/:symId` (uncached) | <60ms | 缓存未命中 |
| WebSocket event stream | <50ms latency | 端到端推送延迟 |
| Memory usage | <500MB | 典型项目 |
| Go-to-definition | <150ms | 任意符号 |
| Hover documentation | <60ms | 悬停响应 |
| Graph update propagation | <500ms | 文件保存后 |
| Symbol scale | 100k+ symbols | 无性能降级 |

## Measurement Strategy

- **基准测试**：每次提交后运行基准测试套件
- **Profiling**：识别性能瓶颈并优先处理
- **P99 监控**：关注 P99 而非平均值，确保长尾性能

## Optimization Techniques

- 内存映射文件（Memory-mapped files）
- 零拷贝网络传输（io_uring）
- 无锁数据结构（Lock-free data structures）
- SIMD 优化图操作
- 批量 LSP 请求以减少往返开销
- 主动缓存 + 精确失效