architecture-review

架构审查技能

从宏观层面分析项目结构，包括包、模块、分层和边界。

适用场景

• 用户要求“审查架构”／“检查项目结构”
• 评估包的组织方式
• 检查各层之间的依赖方向
• 识别架构违规
• 评估是否符合整洁架构／六边形架构

---

快速参考：架构异味

异味	表现	影响
按层组织的包臃肿	service/ 中有 50+ 个类	难以找到相关代码
领域 → 基础设施依赖	实体导入 @Repository	核心逻辑与框架绑定
循环依赖	A → B → C → A	无法测试，脆弱
上帝包	util/ 或 common/ 不断膨胀	成为放置错位代码的垃圾场
抽象泄漏	控制器了解 SQL	违反分层边界

---

包组织策略

按层组织（传统方式）

com.example.app/
├── controller/
│   ├── UserController.java
│   ├── OrderController.java
│   └── ProductController.java
├── service/
│   ├── UserService.java
│   ├── OrderService.java
│   └── ProductService.java
├── repository/
│   ├── UserRepository.java
│   ├── OrderRepository.java
│   └── ProductRepository.java
└── model/
    ├── User.java
    ├── Order.java
    └── Product.java

优点：易于理解，适合小型项目
缺点：相关代码分散，难以扩展，也难以提取模块

按功能组织（推荐）

com.example.app/
├── user/
│   ├── UserController.java
│   ├── UserService.java
│   ├── UserRepository.java
│   └── User.java
├── order/
│   ├── OrderController.java
│   ├── OrderService.java
│   ├── OrderRepository.java
│   └── Order.java
└── product/
    ├── ProductController.java
    ├── ProductService.java
    ├── ProductRepository.java
    └── Product.java

优点：相关代码集中在一起，易于提取，边界清晰
缺点：横切关注点可能需要共享内核

六边形／整洁架构

com.example.app/
├── domain/                    # Pure business logic (no framework imports)
│   ├── model/
│   │   └── User.java
│   ├── port/
│   │   ├── in/               # Use cases (driven)
│   │   │   └── CreateUserUseCase.java
│   │   └── out/              # Repositories (driving)
│   │       └── UserRepository.java
│   └── service/
│       └── UserDomainService.java
├── application/               # Use case implementations
│   └── CreateUserService.java
├── adapter/
│   ├── in/
│   │   └── web/
│   │       └── UserController.java
│   └── out/
│       └── persistence/
│           ├── UserJpaRepository.java
│           └── UserEntity.java
└── config/
    └── BeanConfiguration.java

关键规则：依赖指向内部（适配器 → 应用层 → 领域层）

---

依赖方向规则

黄金法则

┌─────────────────────────────────────────┐
│              Frameworks                 │  ← Outer (volatile)
├─────────────────────────────────────────┤
│           Adapters (Web, DB)            │
├─────────────────────────────────────────┤
│         Application Services            │
├─────────────────────────────────────────┤
│          Domain (Core Logic)            │  ← Inner (stable)
└─────────────────────────────────────────┘

Dependencies MUST point inward only.
Inner layers MUST NOT know about outer layers.

需要标记的违规

// ❌ Domain depends on infrastructure
package com.example.domain.model;

import org.springframework.data.jpa.repository.JpaRepository;  // Framework leak!
import javax.persistence.Entity;  // JPA in domain!

@Entity
public class User {
    // Domain polluted with persistence concerns
}

// ❌ Domain depends on adapter
package com.example.domain.service;

import com.example.adapter.out.persistence.UserJpaRepository;  // Wrong direction!

// ✅ Domain defines port, adapter implements
package com.example.domain.port.out;

public interface UserRepository {  // Pure interface, no JPA
    User findById(UserId id);
    void save(User user);
}

---

架构审查清单

1. 包结构

• 组织策略清晰（按层、按功能或六边形架构）
• 各模块命名一致
• util/ 或 common/ 包没有无限膨胀
• 功能包具有内聚性（相关代码放在一起）

2. 依赖方向

• 领域层完全不导入框架（Spring、JPA、Jackson）
• 适配器依赖领域层，而非反过来
• 包之间没有循环依赖
• 依赖层级清晰

3. 分层边界

• 控制器不包含业务逻辑
• 服务层不了解 HTTP（不使用 HttpServletRequest）
• 仓储不会泄漏到控制器中
• 边界处使用 DTO，内部使用领域对象

4. 模块边界

• 每个模块都有明确的公共 API
• 内部类为包级私有
• 跨模块通信通过接口进行
• 不会为了访问内部实现而“跨模块伸手”

5. 可扩展性指标

• 能否将某项功能提取为独立服务？（可为微服务做好准备）
• 边界是强制执行的，还是仅约定俗成？
• 添加一项功能是否需要修改许多包？

---

常见反模式

1. 一团乱麻

src/main/java/com/example/
└── app/
    ├── User.java
    ├── UserController.java
    ├── UserService.java
    ├── UserRepository.java
    ├── Order.java
    ├── OrderController.java
    ├── ... (100+ files in one package)

修复方法：引入包结构（从按功能组织开始）

2. util 垃圾场

util/
├── StringUtils.java
├── DateUtils.java
├── ValidationUtils.java
├── SecurityUtils.java
├── EmailUtils.java      # Should be in notification module
├── OrderCalculator.java # Should be in order domain
└── UserHelper.java      # Should be in user domain

修复方法：将领域逻辑移到合适的模块，只保留真正通用的工具代码

3. 贫血领域模型

// Domain object is just data
public class Order {
    private Long id;
    private List<OrderLine> lines;
    private BigDecimal total;
    // Only getters/setters, no behavior
}

// All logic in "service"
public class OrderService {
    public void addLine(Order order, Product product, int qty) { ... }
    public void calculateTotal(Order order) { ... }
    public void applyDiscount(Order order, Discount discount) { ... }
}

修复方法：将行为移到领域对象中（构建充血领域模型）

4. 领域层与框架耦合

package com.example.domain;

@Entity  // JPA
@Data    // Lombok
@JsonIgnoreProperties(ignoreUnknown = true)  // Jackson
public class User {
    @Id @GeneratedValue
    private Long id;

    @NotBlank  // Validation
    private String email;
}

修复方法：将领域模型与持久化／API 模型分离

---

分析命令

审查架构时，请检查：

# Package structure overview
find src/main/java -type d | head -30

# Largest packages (potential god packages)
find src/main/java -name "*.java" | xargs dirname | sort | uniq -c | sort -rn | head -10

# Check for framework imports in domain
grep -r "import org.springframework" src/main/java/*/domain/ 2>/dev/null
grep -r "import javax.persistence" src/main/java/*/domain/ 2>/dev/null

# Find circular dependencies (look for bidirectional imports)
# Check if package A imports from B and B imports from A

---

建议格式

报告发现时：

## Architecture Review: [Project Name]

### Structure Assessment
- **Organization**: Package-by-layer / Package-by-feature / Hexagonal
- **Clarity**: Clear / Mixed / Unclear

### Findings

| Severity | Issue | Location | Recommendation |
|----------|-------|----------|----------------|
| High | Domain imports Spring | `domain/model/User.java` | Extract pure domain model |
| Medium | God package | `util/` (23 classes) | Distribute to feature modules |
| Low | Inconsistent naming | `service/` vs `services/` | Standardize to `service/` |

### Dependency Analysis
[Describe dependency flow, violations found]

### Recommendations
1. [Highest priority fix]
2. [Second priority]
3. [Nice to have]

---

令牌优化

针对大型代码库：

1. 从 find 开始了解项目结构
2. 仅检查领域包是否导入框架
3. 抽查 2-3 个功能，分析其模式
4. 不要阅读每个文件，而要寻找模式