介绍
# Senior Architect
用于做出明智技术决策的架构设计与分析工具。
## 目录
- [快速开始](#quick-start) - [工具概览](#tools-overview) - [架构图生成器](#1-architecture-diagram-generator) - [依赖分析器](#2-dependency-analyzer) - [项目架构师](#3-project-architect) - [决策工作流](#decision-workflows) - [数据库选择](#database-selection-workflow) - [架构模式选择](#architecture-pattern-selection-workflow) - [单体与微服务决策](#monolith-vs-microservices-decision) - [参考文档](#reference-documentation) - [技术栈覆盖](#tech-stack-coverage) - [常用命令](#common-commands)
---
## 快速开始
```bash # Generate architecture diagram from project python scripts/architecture_diagram_generator.py ./my-project --format mermaid
# Analyze dependencies for issues python scripts/dependency_analyzer.py ./my-project --output json
# Get architecture assessment python scripts/project_architect.py ./my-project --verbose ```
---
## 工具概览
### 1. 架构图生成器
从项目结构生成多种格式的架构图。
**解决：**“我需要可视化我的系统架构以用于文档编写或团队讨论”
**输入：**项目目录路径 **输出：**图表代码
**支持的图表类型：** - `component` - 显示模块及其关系 - `layer` - 显示架构层 - `deployment` - 显示部署拓扑
**用法：** ```bash # Mermaid format (default) python scripts/architecture_diagram_generator.py ./project --format mermaid --type component
# PlantUML format python scripts/architecture_diagram_generator.py ./project --format plantuml --type layer
# ASCII format (terminal-friendly) python scripts/architecture_diagram_generator.py ./project --format ascii
# Save to file python scripts/architecture_diagram_generator.py ./project -o architecture.md ```
**示例输出：** ```mermaid graph TD A[API Gateway] --> B[Auth Service] A --> C[User Service] B --> D[(PostgreSQL)] C --> D ```
---
### 2. 依赖分析器
分析项目依赖以检查耦合、循环依赖和过期包。
**解决：**“我需要了解我的依赖树并识别潜在问题”
**输入：**项目目录路径 **输出：**分析报告（JSON 或人类可读格式）
**分析：** - 依赖树（直接和传递） - 模块间的循环依赖 - 耦合评分（0-100） - 过期的包
**支持的包管理器：** - npm/yarn (`package.json`) - Python (`requirements.txt`, `pyproject.toml`) - Go (`go.mod`) - Rust (`Cargo.toml`)
**用法：** ```bash # Human-readable report python scripts/dependency_analyzer.py ./project
# JSON output for CI/CD integration python scripts/dependency_analyzer.py ./project --output json
# Check only for circular dependencies python scripts/dependency_analyzer.py ./project --check circular
# Verbose mode with recommendations python scripts/dependency_analyzer.py ./project --verbose ```
**示例输出：** ``` Dependency Analysis Report ========================== Total dependencies: 47 (32 direct, 15 transitive) Coupling score: 72/100 (moderate)
Issues found: - CIRCULAR: auth → user → permissions → auth - OUTDATED: lodash 4.17.15 → 4.17.21 (security)
Recommendations: 1. Extract shared interface to break circular dependency 2. Update lodash to fix CVE-2020-8203 ```
---
### 3. 项目架构师
分析项目结构并检测架构模式、代码异味和改进机会。
**解决：**“我想了解当前的架构并确定需要改进的领域”
**输入：**项目目录路径 **输出：**架构评估报告
**检测：** - 架构模式（MVC、分层、六边形、微服务指标） - 代码组织问题（上帝类、关注点混合） - 层违规 - 缺失的架构组件
**用法：** ```bash # Full assessment python scripts/project_architect.py ./project
# Verbose with detailed recommendations python scripts/project_architect.py ./project --verbose
# JSON output python scripts/project_architect.py ./project --output json
# Check specific aspect python scripts/project_architect.py ./project --check layers ```
**示例输出：** ``` Architecture Assessment ======================= Detected pattern: Layered Architecture (confidence: 85%)
Structure analysis: ✓ controllers/ - Presentation layer detected ✓ services/ - Business logic layer detected ✓ repositories/ - Data access layer detected ⚠ models/ - Mixed domain and DTOs
Issues: - LARGE FILE: UserService.ts (1,847 lines) - consider splitting - MIXED CONCERNS: PaymentController contains business logic
Recommendations: 1. Split UserService into focused services 2. Move business logic from controllers to services 3. Separate domain models from DTOs ```
---
## 决策工作流
### 数据库选择工作流
在新项目选择数据库或迁移现有数据时使用。
**步骤 1：确定数据特征** | 特征 | 倾向于 SQL | 倾向于 NoSQL | |----------------|---------------|-----------------| | 结构化且具有关系 | ✓ | | | 需要 ACID 事务 | ✓ | | | 灵活/演化的模式 | | ✓ | | 面向文档的数据 | | ✓ | | 时序数据 | | ✓ (专用) |
**步骤 2：评估规模需求** - <100 万条记录，单区域 → PostgreSQL 或 MySQL - 100 万 - 1 亿条记录，读密集型 → 带有读副本的 PostgreSQL - >1 亿条记录，全球分布 → CockroachDB、Spanner 或 DynamoDB - 高写入吞吐量（>10K/秒）→ Cassandra 或 ScyllaDB
**步骤 3：检查一致性要求** - 需要强一致性 → SQL 或 CockroachDB - 接受最终一致性 → DynamoDB、Cassandra、MongoDB
**步骤 4：记录决策** 创建一个 ADR（架构决策记录），包括： - 背景和需求 - 考虑的选项 - 决策及其基本原理 - 接受的权衡
**快速参考：** ``` PostgreSQL → Default choice for most applications MongoDB → Document store, flexible schema Redis → Caching, sessions, real-time features DynamoDB → Serverless, auto-scaling, AWS-native TimescaleDB → Time-series data with SQL interface ```
---
### 架构模式选择工作流
在设计新系统或重构现有架构时使用。
**步骤 1：评估团队和项目规模** | 团队规模 | 建议的起点 | |-----------|---------------------------| | 1-3 名开发人员 | 模块化单体 | | 4-10 名开发人员 | 模块化单体或面向服务 | | 10+ 名开发人员 | 考虑微服务 |
**步骤 2：评估部署需求** - 接受单一部署单元 → 单体 - 需要独立扩展 → 微服务 - 混合（某些服务的扩展方式不同）→ 混合模式
**步骤 3：考虑数据边界** - 接受共享数据库 → 单体或模块化单体 - 需要严格的数据隔离 → 带有独立数据库的微服务 - 适合事件驱动通信 → 事件溯源/CQRS
**步骤 4：根据需求匹配模式**
| 需求 | 推荐模式 | |-------------|-------------------| | 快速 MVP 开发 | 模块化单体 | | 独立团队部署 | 微服务 | | 复杂的领域逻辑 | 领域驱动设计 (DDD) | | 高读写比差异 | CQRS | | 需要审计跟踪 | 事件溯源 | | 第三方集成 | 六边形/端口与适配器 |
有关模式的详细描述，请参阅 `references/architecture_patterns.md`。
---
### 单体与微服务决策
**选择单体的情况：** - [ ] 团队规模小（<10 名开发人员） - [ ] 领域边界不明确 - [ ] 快速迭代是优先事项 - [ ] 必须最小化运维复杂性 - [ ] 接受共享数据库
**选择微服务的情况：** - [ ] 团队可以端到端地拥有服务 - [ ] 独立部署至关重要 - [ ] 每个组件有不同的扩展需求 - [ ] 需要技术多样性 - [ ] 领域边界已充分理解
**混合方法：** 从模块化单体开始。仅在以下情况提取服务： 1. 模块有显著不同的扩展需求 2. 团队需要独立部署 3. 技术约束要求分离
---
## 参考文档
加载这些文件以获取详细信息：
| 文件 | 包含内容 | 用户询问以下内容时加载 | |------|----------|--------------------------| | `references/architecture_patterns.md` | 9 种架构模式及其权衡、代码示例和使用场景 | “哪种模式？”，“微服务与单体”，“事件驱动”，“CQRS” | | `references/system_design_workflows.md` | 系统设计任务的 6 个分步工作流 | “如何设计？”，“容量规划”，“API 设计”，“迁移” | | `references/tech_decision_guide.md` | 技术选择的决策矩阵 | “哪种数据库？”，“哪种框架？”，“哪种云？”，“哪种缓存？” |
---
## 技术栈覆盖
**语言：** TypeScript、JavaScript、Python、Go、Swift、Kotlin、Rust **前端：** React、Next.js、Vue、Angular、React Native、Flutter **后端：** Node.js、Express、FastAPI、Go、GraphQL、REST **数据库：** PostgreSQL、MySQL、MongoDB、Redis、DynamoDB、Cassandra **基础设施：** Docker、Kubernetes、Terraform、AWS、GCP、Azure **CI/CD：** GitHub Actions、GitLab CI、CircleCI、Jenkins
---
## 常用命令
```bash # Architecture visualization python scripts/architecture_diagram_generator.py . --format mermaid python scripts/architecture_diagram_generator.py . --format plantuml python scripts/architecture_diagram_generator.py . --format ascii
# Dependency analysis python scripts/dependency_analyzer.py . --verbose python scripts/dependency_analyzer.py . --check circular python scripts/dependency_analyzer.py . --output json
# Architecture assessment python scripts/project_architect.py . --verbose python scripts/project_architect.py . --check layers python scripts/project_architect.py . --output json ```
---
## 获取帮助
1. 运行任何脚本时加上 `--help` 以获取使用信息 2. 查看参考文档以获取详细的模式和工作流 3. 使用 `--verbose` 标志以获取详细的解释和建议