senior-architect

Senior Architect

用于做出明智技术决策的架构设计与分析工具。

目录

• 快速开始
• 工具概览
  • 架构图生成器
  • 依赖分析器
  • 项目架构师
• 决策工作流
  • 数据库选型
  • 架构模式选型
  • 单体 vs 微服务
• 参考文档
• 技术栈覆盖
• 常用命令

---

快速开始

# 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. 架构图生成器

根据项目结构生成多种格式的架构图。

解决的问题："我需要可视化系统架构，用于文档编写或团队讨论"

**输入：**项目目录路径 **输出：**图表代码（Mermaid、PlantUML 或 ASCII）

支持的图表类型：

• component：展示模块及其关系
• layer：展示架构分层（表现层、业务层、数据层）
• deployment：展示部署拓扑

用法：

# 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）

用法：

# 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、分层、六边形、微服务迹象）
• 代码组织问题（上帝类、职责混杂）
• 分层违规
• 缺失的架构组件

用法：

# 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
• 高写入吞吐（>1 万/秒） → 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 步：考虑数据边界

• 可接受共享数据库 → 单体或模块化单体
• 要求严格的数据隔离 → 使用独立数据库的微服务
• 适合事件驱动通信 → Event-sourcing/CQRS

第 4 步：将模式与需求匹配

需求	推荐模式
快速开发 MVP	模块化单体
团队独立部署	微服务
复杂的领域逻辑	领域驱动设计
读写比例差异较大	CQRS
需要审计追踪	Event Sourcing
第三方集成	六边形架构/Ports & Adapters

详细的模式说明请参阅 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

---

常用命令

# 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 参数获取详细的说明和建议