nareshtammineni01/crossctx

# CrossCtx **立即发现隐藏的服务依赖关系。** [](https://nareshtammineni01.github.io/crossctx/) ``` npx crossctx scan ./services ``` ``` 🔍 CrossCtx Results ───────────────────────────────────────────── ✔ 7 services detected ✔ 42 endpoints mapped ✔ 18 cross-service calls found Top dependencies: - order-service → payment-service - order-service → inventory-service - payment-service → user-service ⚠️ Insights: - order-service has high fan-out (calls 4 services) - user-service is a critical dependency (used by 3 services) - 2 unresolved service calls detected Next steps: crossctx graph # open interactive dependency graph crossctx insights # full architecture analysis crossctx blame # impact analysis for a service crossctx export # save JSON / Markdown ``` 无需配置。无需仪器化。无需在集群中运行代理。 CrossCtx 直接读取您的源代码，并告诉您服务实际是如何连接的。 ## 快速参考 ``` # 扫描你的服务并输出摘要 npx crossctx scan ./services # 生成交互式 HTML 依赖关系图 npx crossctx graph ./services -o service-view-map.html # 从之前的扫描中打开图形（无需重新扫描） npx crossctx graph --input crossctx-output.json -o service-view-map.html # 架构分析 — 循环依赖、高扇出、风险 npx crossctx insights ./services # 爆炸半径 — 如果此服务宕机会有什么损坏？ npx crossctx blame PaymentService # 追踪每个端点的跳转 npx crossctx trace /api/orders # 检测破坏性 API 变更（非常适合 CI） npx crossctx diff baseline.json # 将扫描结果导出为 JSON 和 Markdown npx crossctx export --format all # 避免每次手动输入路径 npx crossctx init # creates .crossctxrc.json npx crossctx scan # reads paths from config ``` ## CrossCtx 的功能 CrossCtx 扫描您的代码并： - 自动检测服务 - 提取 API（控制器、端点） - 理解请求/响应负载 - 映射跨服务调用 - 构建完整的调用链 - 识别架构风险 全部来自源代码 — 无需 OpenAPI。 ## 为什么要使用 CrossCtx？ 微服务难以全面理解： - *“什么调用了这个 API？”* - *“如果我修改这个，什么会断裂？”* - *“这些服务实际是如何连接的？”* 文档会过时。图表会撒谎。部落知识无法扩展。 **CrossCtx 读取您的代码并告诉您真相。** ## 安装 ``` npm install -g crossctx ``` 或者无需安装直接运行： ``` npx crossctx scan ./services ``` ## 截图 [](https://nareshtammineni01.github.io/crossctx/) *引导入口覆盖层 — 打开时选择您的意图* [](https://nareshtammineni01.github.io/crossctx/) *洞察面板 — 图形中高亮的循环依赖、高扇出和爆炸半径警告* [](https://nareshtammineni01.github.io/crossctx/) *端点详细面板 — 完整调用链、请求/响应形状和一键 AI 上下文复制* ## 命令 ### `crossctx scan` — 起点 ``` crossctx scan ./order-service ./payment-service ./user-service ``` 自动检测语言，映射端点和跨服务调用，并显示纯英文摘要。支持 TypeScript、Java、Python、Go、C#、gRPC 和 GraphQL — 无需配置。 使用 `crossctx init` 设置 `.crossctxrc.json`，这样就无需重复路径： ``` crossctx init # creates .crossctxrc.json crossctx scan # reads paths from config ``` ### `crossctx graph` — 可视化依赖关系图 ``` # 基础模式 — 在当前目录输出 crossctx-graph.html crossctx graph ./order-service ./payment-service ./user-service # 自定义输出文件名（使用 -o 指定保存位置） crossctx graph ./services -o service-view-map.html # 扫描多个目录，保存到子文件夹 crossctx graph ./order-service ./payment-service -o ./output/service-view-map.html # 过滤低置信度边以获得更清晰的图形 crossctx graph ./services -o service-view-map.html --min-confidence 0.7 ``` 生成自包含的交互式 HTML 文件。在任何浏览器中打开 — 无需服务器。 [](https://nareshtammineni01.github.io/crossctx/) **图形功能：** - **引导入口** — 打开时选择意图：系统概览、查找风险服务、追踪 API 或自由探索 - **焦点模式** — 概览 / 依赖 / 风险 / 调试工具栏更改图形着色和行为 - **风险模式** — 节点按扇出严重程度以红/橙/绿色着色 - 服务视图和控制器视图 - 最小置信度滑块 — 实时过滤嘈杂边 - 服务筛选芯片 — 隔离单个服务及其连接 - 端点详细面板 — 请求/响应形状、完整调用链树 - 调用链动画 — 逐步跳转遍历 或者使用之前保存的扫描输出跳过重新扫描： ``` crossctx graph --input crossctx-output.json ``` ### `crossctx insights` — 架构分析 ``` crossctx insights ./services ``` 运行完整分析并通过以下方式呈现： ``` ⚡ Architecture Insights ───────────────────────────────────────────── ✖ Circular dependency: order-service ↔ payment-service These services form a dependency cycle... ⚠️ High fan-out: order-service calls 4 services Consider introducing an orchestrator or API gateway... ⚠️ High-risk service: auth-service is called by 6 services An outage here has wide blast radius... ℹ️ 12 outbound calls could not be mapped Add service URL hints or include all service dirs in scan... ``` 如果发现关键问题（循环依赖），退出代码为 1 — 适用于 CI。 洞察也直接显示在图形中 — 点击右侧面板中的 **Insights** 标签查看所有警告，并点击任何洞察以突出显示受影响的服务： [](https://nareshtammineni01.github.io/crossctx/) ### `crossctx blame` / `crossctx impact` — 影响分析 ``` crossctx blame PaymentService # 或 crossctx impact PaymentService ``` ``` 💥 Blast radius: PaymentService ───────────────────────────────────────────── If PaymentService goes down: Direct callers (2): ✖ order-service will break ✖ checkout-service will break Transitively affected (1): ~ api-gateway (indirect) Total impact: 3 service(s) affected ``` 适用于值班准备、事件响应和变更审查。 ### `crossctx trace` — 可视化调用链 ``` crossctx trace /api/orders ``` ``` 🔎 Trace: POST /api/orders order-service → payment-service (POST /api/charge) → stripe-adapter (POST /v1/charges) → inventory-service (PUT /api/stock/:id) ``` 逐服务查看调用某个端点时发生的一切。 ### `crossctx explain` — 为 ChatGPT / AI 复制上下文 ``` crossctx explain /api/orders ``` 生成可立即粘贴到 ChatGPT 或任何 LLM 的上下文块 — 包括端点的调用链、请求/响应架构以及它触及的服务。自动复制到剪贴板。 ``` Copied to clipboard ✅ Includes: - full call chain - request/response schema - dependent services ``` AI 上下文构建器也内建在图形中 — 点击任何端点查看其完整详细信息并点击 **Copy context**： [](https://nareshtammineni01.github.io/crossctx/) ### `crossctx export` — 保存输出文件 ``` crossctx export --format all # JSON + Markdown crossctx export --format markdown # Markdown only crossctx export --format json # JSON only ``` 或者从保存的扫描中导出： ``` crossctx export --input crossctx-output.json --format all ``` ### `crossctx diff` — 检测破坏性变更 ``` crossctx diff baseline.json ``` 比较两次扫描并报告新增、移除和变更的端点。检测到破坏性变更时退出代码为 1 — 适用于 CI 防护。 ``` # 在 CI 中：在 main 分支保存基线，在 PR 中比较 crossctx scan ./services --output baseline.json crossctx diff baseline.json ``` ## 实际用例 **“为什么这个端点失败了？”** → `crossctx trace /api/orders` — 秒级查看其调用的每个下游服务。 **“修改这个会有什么影响？”** → `crossctx blame ` — 修改前进行影响分析。 **“这个系统是如何工作的？”** → `crossctx scan` + `crossctx graph` — 第一天就获得可视化与结构化理解。 **“向 ChatGPT 解释这段代码库”** → `crossctx explain /api/orders` — 将完整调用链和架构复制到剪贴板，粘贴即用。 ## 语言与协议支持 | 语言 | 框架 | 入站 | 出站 | DTO | |---|---|---|---|---| | TypeScript | NestJS, Express | ✅ | axios, fetch, HttpService, got | class-validator, Swagger 注解 | | Java | Spring Boot | ✅ | RestTemplate, WebClient, FeignClient | POJO 类、records | | C# | ASP.NET Core | ✅ | HttpClient, IHttpClientFactory, Refit | 类、位置记录 | | Python | FastAPI, Django REST, Flask | ✅ | httpx, requests, aiohttp | Pydantic, DRF 序列化器 | | Go | Gin, Chi | ✅ | net/http, go-resty | 结构体 | | gRPC | 任意语言 | ✅ | .proto 文件解析 | 消息类型 | | GraphQL | 任意语言 | ✅ | 架构解析 | 类型定义 | 检测到 OpenAPI/Swagger 规范时也会扫描并用于增强输出。 ## 配置（可选） ``` crossctx init ``` 创建 `.crossctxrc.json`： ``` { "paths": ["./order-service", "./payment-service"], "format": "all" } ``` 然后无需重复路径即可运行任何命令： ``` crossctx scan ``` ## 输出 | 格式 | 文件 | 描述 | |---|---|---| | **JSON** | `crossctx-output.json` | 便于自动化和 AI 工具处理的结构化数据 | | **Markdown** | `crossctx-output.md` | 适用于提示词和文档的 LLM 友好摘要 | | **图形** | `crossctx-graph.html` | 自包含的交互式 HTML 文件 | ## 示例 该仓库附带八个示例微服务，涵盖所有支持的语言： ``` cd examples crossctx scan ``` ``` crossctx graph crossctx insights crossctx blame analytics-service ``` ## 性能 设计为足够快以适用于 CI（在 M2 MacBook Pro、Node.js 20 上进行基准测试）： | 数据集 | 服务 | 文件 | 耗时 | |---|---|---|---| | 8 种混合语言服务 | 8 ~120 | ~2 秒 | | 10 个 TypeScript/NestJS 服务 | 10 | 160 | ~3 秒 | | 50 个 TypeScript/NestJS 服务 | 50 | 800 | ~12 秒 | ## 工作原理 CrossCtx 遵循四阶段流水线 — **检测 → 解析 → 解析 → 渲染**： **检测** — 通过标记文件（`package.json`、`pom.xml`、`go.mod` 等）识别每个项目文件夹的语言和框架，并带有置信度评分。 **解析** — 直接从源代码提取控制器、端点、HTTP 方法、路径、请求/响应形状以及出站调用。无需 OpenAPI 规范。 **解析** — 使用五层策略将出站调用映射到目标服务：命名客户端（FeignClient、IHttpClientFactory）→ 主机名匹配 → 环境变量启发式 → URL 片段匹配 → 路径匹配。 **渲染** — 生成钩子摘要、洞察、JSON、Markdown 和交互式 HTML 图形。 ## 插件接口 通过社区插件接口添加对自定义语言或框架的支持： ``` { "paths": ["./my-service"], "plugins": ["crossctx-plugin-ruby"] } ``` 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解插件 API。 ## CI 集成 ``` # .github/workflows/crossctx.yml - name: Check for breaking API changes run: | crossctx scan ./services --output current.json crossctx diff baseline.json current.json ``` 提供 [Docker 镜像](docs/docker-ci.md) 和 [GitHub Action](action.yml)，实现零安装 CI 使用。 ## 路线图 - **v0.3** ✅ — gRPC、GraphQL、数据库使用检测、共享库检测、单体仓库发现 - **v1.0** ✅ — 稳定的 JSON 架构、插件接口、`diff` 子命令、Docker、性能基准 - **v2.0** ✅ — `scan`、`graph`、`insights`、`blame`、`explain`、`export` 子命令；架构洞察层 - **v2.x** — PR 影响分析 GitHub Action、VS Code 扩展、监听模式洞察 参见 [ROADMAP.md](ROADMAP.md) 了解完整计划。 ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 [MIT](LICENSE)

标签：API映射, CI集成, CMS安全, DevOps工具, GNU通用公共许可证, JavaScript, JS文件枚举, MITM代理, Node.js, Python工具, SEO: 代码扫描, SEO: 依赖图, SEO: 服务依赖, SEO: 架构分析, SEO: 隐藏依赖, TypeScript, WebSocket, 二进制发布, 云安全监控, 依赖关系发现, 依赖分析, 依赖图, 关键依赖识别, 安全插件, 开源工具, 性能分析, 断点分析, 无代理, 无配置, 日志审计, 服务依赖, 服务拓扑, 架构可视化, 自动化攻击, 跨服务调用, 逆向工具, 静态分析, 风险分析, 高扇出检测