shivangiG/CodeAtlas

# CodeAtlas 一个使代码库变得可查询的 REST 服务。将其指向一个代码仓库，触发一次快照，Agent 便可以询问：如果我更改了这个文件会导致什么破坏，这个功能是否已经存在，我需要为该任务阅读的最小文件集是什么，以及从这个 controller 开始执行流是如何走向的。基于 OpenAPI 3.1.0 采用契约优先（contract-first）的方式构建，后端采用分层的 Spring Boot 架构。 ## 模块 ``` codeatlas/ ├── openapi-spec/ OpenAPI 3.1.0 contract + code generation │ Produces: Spring interfaces, model classes ├── server/ Spring Boot application │ Implements the generated interfaces ├── service-client/ Typed OkHttp client for the CodeAtlas API │ Used by integration tests and downstream consumers └── integration-tests/ Black-box HTTP tests via the service client Starts server at a random port, no MockMvc ``` ## 前置条件 | 工具 | 版本 | |---|---| | Java | 23 | | Gradle (wrapper) | 8.x (使用 `./gradlew`) | ## 本地运行 ``` ./gradlew :server:bootRun --args='--spring.profiles.active=local' ``` `local` 配置文件使用位于 `~/codeatlas-db` 的基于文件的 H2 数据库（参见 `server/src/main/resources/application-local.yml`）。 ## 构建与测试 ``` # 包含所有单元和集成测试的完整构建 ./gradlew clean build # 仅服务器（更快的反馈循环） ./gradlew :server:build # 仅集成测试 ./gradlew :integration-tests:test ``` ## API 领域 | 前缀 | 状态 | 描述 | |---|---|---| | `GET /health` | 已实现 | 存活检查 | | `POST /snapshots` | 已实现 | 创建一个命名的索引快照 | | `GET /snapshots` | 已实现 | 列出所有快照 | | `GET /snapshots/active` | 已实现 | 获取当前活动的快照 | | `DELETE /snapshots/{id}` | 已实现 | 删除快照（如果处于活动状态则不允许） | | `GET /graph/summary` | 501 | 高层模块/包映射图 | | `GET /graph/symbols` | 501 | 按名称模式搜索符号 | | `GET /graph/symbols/{id}` | 501 | 带有边的单个符号 | | `GET /graph/call-flows` | 501 | 从某个符号追踪调用路径 | | `POST /graph/task-contexts` | 501 | 任务的最小文件集 | | `POST /impacts` | 501 | 更改文件/符号的影响范围 | | `POST /capabilities/search` | 501 | 查找已有的可复用功能 | | `GET /capabilities/clients` | 501 | 列出内部服务客户端 | | `GET /analyzers/violations` | 501 | 架构违规发现 | | `GET /analyzers/openapi-drift` | 501 | 规范与代码的偏差发现 | | `GET /analyzers/reviews` | 501 | 完整的架构审查报告 | | `POST /ci/gates` | 501 | 评估 CI 门禁 (BLOCK/WARN/PASS) | | `POST /ci/baselines` | 501 | 将当前发现捕获为基线 | 完整的 OpenAPI 3.1.0 规范位于 `openapi-spec/src/main/openapi/codeatlas.yaml`。 ## 架构 ``` HTTP request └── Controller (implements generated *Api interface) └── Service (business rules, accepts/returns DTOs) └── Repository interface (domain boundary) └── RepositoryJpaImpl (JPA adapter) └── JpaRepository (Spring Data) ``` 关键不变量： - **Controller 仅作为适配器** —— 不包含任何业务逻辑。 - **JPA 实体永远不会脱离 `repositories/`** —— Service 和 Controller 只能看到 DTO。 - **异常到 HTTP 状态码的映射** 完全存在于 `GlobalExceptionHandler` 中。 - **每个端点** 在 `server/` 中都有一个单元测试，并在 `integration-tests/` 中有一个真实的 HTTP 测试。 - **未实现的端点** 返回 `HTTP 501`。搜索 `NOT_IMPLEMENTED` 以枚举所有缺失项。 ## Agent 指南 参见 [`CLAUDE.md`](CLAUDE.md) 获取完整的编码标准、SOLID 原则、所使用的 GoF 设计模式以及可用技能的集合。 `.claude/skills/` 中的核心技能： | 技能 | 适用场景 | |---|---| | `openapi-first` | 添加或更改任何 HTTP 端点时 | | `new-domain-entity` | 添加新的由 JPA 支持的领域概念时 | | `java-staff-review` | 在提交任何实质性的 Java 更改之前 | | `prepare-pr` | 在发起 pull request 之前 | | `dead-code-removal` | 在进行任何重大重构之后 | | `clean-code` | 命名、规模、内聚性、注释规范 | | `java-best-practices` | Java 17+ 模式 (records、Optional、MapStruct) |

标签：AI智能体, API客户端, AST解析, Gradle, H2数据库, Java 23, OpenAPI 3.1, RESTful API, Spring Boot, 代码仓库智能分析, 代码图谱, 代码审查辅助, 代码搜索, 代码架构, 代码爆炸半径分析, 代码索引, 任务上下文, 依赖图分析, 后台面板检测, 域名枚举, 威胁情报, 开发者工具, 影响分析, 提示词优化, 数据管道, 漏洞测试, 符号图谱, 能力搜索, 自托管服务, 调用流程追踪, 软件工程, 错误基检测, 静态代码分析