Update README_CN.md
SmellDoc是一个基于Elastic Stack的微服务异味检测与分析插件，通过结合运行时数据（指标、追踪、日志）与静态代码指标数据，实现对微服务架构中各种异味、性能问题和架构问题的检测与可视化。
核心价值： Step 1 - 配置阶段： 部署agent代理 → 收集运行时数据Step 2 - 数据收集： 预处理与整合指标数据 → 发送至ElasticsearchStep 3 - 检测与可视化： 异味检测 → 展示于Kibana
service/datacollector/
controller/
docs
elastic-apm-agent.jar
/com-inter/hardcoded-endpoints
/decomposition/scattered-functionality
/decomposition/wrong-cuts
/decomposition/microservice-greedy
/api/no-api-versioning
/infrastructure/esb-usage
/infrastructure/no-api-gateway
/infrastructure/hub-like-dependency
/infrastructure/shared-libraries
/infrastructure/sharing-persistence
/infrastructure/inappropriate-service-intimacy
/infrastructure/god-component
POST /dynamic/fragile-service
POST /dynamic/uneven-load-distribution
POST /dynamic/inconsistent-service-response
POST /dynamic/call-rate-anomaly
POST /dynamic/uneven-api-usage
POST /dynamic/high-frequency-slow-queries
POST /dynamic/frequent-gc
POST /dynamic/long-time-gc
POST /dynamic/memory-jitter-of-service
POST /dynamic/uneven-logic-processing
POST /dynamic/the-ramp
POST /dynamic/cyclic-dependency
BSDProject/ ├── commons/ # 公共模块 │ ├── src/main/java/com/yang/apm/springplugin/ │ │ ├── base/ # 基础类库 │ │ │ ├── context/ # 检测结果类 │ │ │ ├── Enum/ │ │ │ ├── item/ │ │ │ └── utils/ │ │ ├── constant/ # 常量定义 │ │ ├── expection/ # 异常处理 │ │ ├── indexmapping/ # ES索引映射 │ │ ├── model/ # 数据模型 │ │ ├── pojo/ # 数据传输对象 │ │ └── utils/ # 通用工具 │ └── pom.xml ├── BSDComponent/ # 主组件模块 │ ├── src/main/java/com/yang/apm/springplugin/ │ │ ├── BSDComponentApplication.java │ │ ├── config/ # 配置类 │ │ │ ├── AsyncConfig.java # 异步配置 │ │ │ ├── CacheConfig.java # 缓存配置 │ │ │ └── WebConfig.java # Web配置 │ │ ├── controller/ # REST API控制器 │ │ │ ├── datacollector/ # 数据收集端点 │ │ │ ├── dynamicanalysis/ # 动态分析端点 │ │ │ ├── staticanalysis/ # 静态分析端点 │ │ │ └── HealthCheckController.java # 健康检查 │ │ ├── factory/ # 工厂类 │ │ ├── listener/ # 事件监听器 │ │ ├── manager/ # 资源管理器 │ │ ├── mapper/ # 数据访问层 │ │ ├── monitor/ # 监控组件 │ │ ├── pojo/ # 数据对象 │ │ ├── services/ # 业务逻辑服务 │ │ │ ├── datacollector/ # 数据收集组件 │ │ │ ├── dynamicdetect/ # 动态检测服务 │ │ │ ├── staticdetect/ # 静态检测服务 │ │ │ └── db/ # 数据库服务 │ │ └── utils/ # 工具类 │ ├── src/main/resources/ │ │ ├── application.yml # 主配置文件 │ │ ├── application-dev.yml # 开发环境配置 │ │ ├── application-pro.yml # 生产环境配置 │ │ └── logback-spring.xml # 日志配置 │ └── pom.xml # 主组件配置 ├── docs/ # 文档目录 │ ├── cn/ # 中文文档 │ │ ├── FINAL_COMPLETE_API_LIST.md # 完整API列表 │ │ ├── UnevenApiUsageDetection.md # API使用不均检测 │ │ └── ... # 其他技术文档 │ ├── datademo/ # 数据示例 │ │ ├── BusinessMetricsDemo.json # 业务指标示例 │ │ ├── SvcMetricsResDemo.json # 服务指标示例 │ │ └── cycleDependencyDemo.json # 循环依赖示例 │ └── img/ │ └── architecture.jpg # 架构图 ├── pom.xml # 根项目配置 └── README.md # 项目说明文档
克隆仓库
git clone https://github.com/yang66-hash/BSDProject.git cd BSDProject
配置数据库 导入数据库脚本 docs/db/data_collector_db.sql到本地mysql数据库
docs/db/data_collector_db.sql
更新配置文件 编辑 BSDComponent/src/main/resources/application-dev.yml:
BSDComponent/src/main/resources/application-dev.yml
server: port: 32000 spring: datasource: username: your_username password: your_password url: jdbc:mysql://localhost:3306/data_collector_db elasticsearch: username: elastic password: your_elasticsearch_password uris: "http://localhost:9200" mbst: repository: username: your_git_username password: your_git_password local-repository: "/path/to/local/repo" remote-repositories: "repo1,repo2"
构建项目
mvn clean install
运行应用
cd BSDComponent mvn spring-boot:run
应用将在默认端口32000上启动。或者也可以通过java -jar命令启动jar包。
java -jar
需要配置mbst.repository参数，用于访问Git仓库。
mbst.repository
curl -X POST http://localhost:32000/com-inter/hardcoded-endpoints \ -H "Content-Type: application/json" \ -d '{"serviceName": "user-service"}'
curl -X POST http://localhost:32000/decomposition/scattered-functionality \ -H "Content-Type: application/json" \ -d '{"serviceName": "order-service"}'
需要存在已经配置好APM Java Agent的微服务系统才可以使用。
curl -X POST http://localhost:32000/dynamic/uneven-load-distribution \ -H "Content-Type: application/json" \ -d '{"serviceName": "payment-service"}'
curl -X POST http://localhost:32000/dynamic/call-rate-anomaly \ -H "Content-Type: application/json" \ -d '{"serviceName": "user-service"}'
curl -X POST http://localhost:32000/dynamic/frequent-gc \ -H "Content-Type: application/json" \ -d '{"serviceName": "order-service"}'
git checkout -b feature/AmazingFeature
git commit -m 'Add some AmazingFeature'
git push origin feature/AmazingFeature
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
Q: 如何调整检测阈值？ A: 可以通过修改配置文件中的相关参数来调整检测阈值，如 coefficient、threshold 等。
coefficient
threshold
Q: 系统支持哪些数据库？ A: 目前主要支持MySQL 8.0作为关系数据库，同时使用Elasticsearch进行数据存储和检索。
Q: 如何添加自定义检测规则？ A: 实现 IDetectConvert 接口，创建新的服务类，并在控制器中添加相应的端点。
IDetectConvert
Q: 系统的性能如何？ A: 系统采用异步处理和缓存机制，支持高并发访问。具体性能指标取决于部署环境和数据量。
Q: 如何集成到现有系统？ A: 系统提供REST API接口，可以轻松集成到现有的监控和告警系统中。
SmellDoc - 让微服务架构更加健康、高效、可维护！
核心理念: 通过智能检测和分析，帮助开发团队识别和解决微服务架构中的各种异味问题，提升系统的可维护性、性能和稳定性。
SmellDoc 是一个基于 Elastic Stack 构建的微服务坏味道检测与分析插件，能够融合运行时数据（指标、追踪、日志）与静态代码度量数据，对微服务架构中的坏味道、性能问题和架构异常进行检测、分析与可视化。围绕该项目形成的学术论文已被 ICSOC 2025 接收。凭借该项目在微服务可观测性与开源工具扩展方面的贡献，项目负责人获得2026 Elastic Gold Contributor。
版权所有：中国计算机学会技术支持：开源发展技术委员会 京ICP备13000930号-9 京公网安备 11010802047560号
SmellDoc - 微服务异味检测与分析平台
📋 项目概述
SmellDoc是一个基于Elastic Stack的微服务异味检测与分析插件，通过结合运行时数据（指标、追踪、日志）与静态代码指标数据，实现对微服务架构中各种异味、性能问题和架构问题的检测与可视化。
service/datacollector/controller/docs🏗️ 系统架构
1) 配置层 (Configuration Layer)
elastic-apm-agent.jar) - 收集运行时指标、链路信息2) 数据收集层 (Data Collection Layer)
3) 检测与可视化层 (Detection & Visualization Layer)
🔧 技术栈
🚀 核心功能
🔍 静态分析功能 (12种异味类型)
/com-inter/hardcoded-endpoints/decomposition/scattered-functionality/decomposition/wrong-cuts/decomposition/microservice-greedy/api/no-api-versioning/infrastructure/esb-usage/infrastructure/no-api-gateway/infrastructure/hub-like-dependency/infrastructure/shared-libraries/infrastructure/sharing-persistence/infrastructure/inappropriate-service-intimacy/infrastructure/god-component📊 动态分析功能 (12种异味类型)
1️⃣ 基础运行时异味检测
POST /dynamic/fragile-servicePOST /dynamic/uneven-load-distributionPOST /dynamic/inconsistent-service-response2️⃣ 资源和性能异味检测
POST /dynamic/call-rate-anomalyPOST /dynamic/uneven-api-usage3️⃣ 数据库和查询异味检测
POST /dynamic/high-frequency-slow-queries4️⃣ 内存和GC异味检测
POST /dynamic/frequent-gcPOST /dynamic/long-time-gcPOST /dynamic/memory-jitter-of-service5️⃣ 逻辑处理异味检测
POST /dynamic/uneven-logic-processing6️⃣ 系统稳定性异味检测
POST /dynamic/the-ramp7️⃣ 循环依赖检测
POST /dynamic/cyclic-dependency📈 数据收集与监控
📁 项目结构
🚀 快速开始
前置条件
安装步骤
克隆仓库
配置数据库 导入数据库脚本
docs/db/data_collector_db.sql到本地mysql数据库更新配置文件 编辑
BSDComponent/src/main/resources/application-dev.yml:构建项目
运行应用
应用将在默认端口32000上启动。或者也可以通过
java -jar命令启动jar包。API文档访问
📖 使用示例
静态分析示例
需要配置
mbst.repository参数，用于访问Git仓库。检测硬编码端点
检测功能分散
动态分析示例
需要存在已经配置好APM Java Agent的微服务系统才可以使用。
检测负载分布不均
检测调用率异常
检测频繁GC
📈 系统特性
1. 全面覆盖
2. 统一架构
3. 高性能设计
4. 完整生命周期
🎯 检测能力矩阵
🤝 贡献指南
git checkout -b feature/AmazingFeature)git commit -m 'Add some AmazingFeature')git push origin feature/AmazingFeature)代码规范
📄 许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
🆘 支持与帮助
常见问题
Q: 如何调整检测阈值？ A: 可以通过修改配置文件中的相关参数来调整检测阈值，如
coefficient、threshold等。Q: 系统支持哪些数据库？ A: 目前主要支持MySQL 8.0作为关系数据库，同时使用Elasticsearch进行数据存储和检索。
Q: 如何添加自定义检测规则？ A: 实现
IDetectConvert接口，创建新的服务类，并在控制器中添加相应的端点。Q: 系统的性能如何？ A: 系统采用异步处理和缓存机制，支持高并发访问。具体性能指标取决于部署环境和数据量。
Q: 如何集成到现有系统？ A: 系统提供REST API接口，可以轻松集成到现有的监控和告警系统中。
获取帮助
📝 更新日志
版本 1.0.0 (2025-10-01)
版本 1.1.0 (计划中)
SmellDoc - 让微服务架构更加健康、高效、可维护！