component-identification-sizing

组件识别与规模评估

此技能用于识别代码库中的架构组件（逻辑构建块），并计算规模指标，以评估拆分的可行性并找出规模过大的组件。

使用方法

快速开始

请求分析代码库：

• “识别并评估此代码库中所有组件的规模”
• “查找需要拆分的超大组件”
• “创建组件清单，以便规划拆分”
• “分析组件规模分布”

使用示例

示例 1：完整分析

User: "Identify and size all components in this codebase"

The skill will:
1. Map directory/namespace structures
2. Identify all components (leaf nodes)
3. Calculate size metrics (statements, files, percentages)
4. Generate component inventory table
5. Flag oversized/undersized components
6. Provide recommendations

示例 2：查找超大组件

User: "Which components are too large?"

The skill will:
1. Calculate mean and standard deviation
2. Identify components >2 std dev or >10% threshold
3. Analyze functional areas within large components
4. Suggest specific splits with estimated sizes

示例 3：组件规模分析

User: "Analyze component sizes and distribution"

The skill will:
1. Calculate all size metrics
2. Generate size distribution summary
3. Identify outliers
4. Provide statistics and recommendations

分步流程

1. 初步分析：从完整的组件清单开始
2. 识别问题：找出需要关注的组件
3. 获取建议：请求可执行的拆分/合并建议
4. 跟踪进度：持续跟踪组件规模的变化

适用场景

在以下情况下使用此技能：

• 启动单体拆分工作
• 评估代码库的结构与组织方式
• 找出规模过大或过小的组件
• 为迁移规划创建组件清单
• 分析各组件的代码分布
• 为基于组件的拆分模式做准备

核心概念

组件定义

组件是一种架构构建块，具有以下特征：

• 具有明确的角色与职责
• 通过命名空间、包结构或目录路径进行识别
• 包含归为一组的源代码文件（类、函数、模块）
• 执行特定的业务或基础设施功能

关键规则：组件由目录/命名空间结构中的叶节点确定。如果某个命名空间继续扩展（例如，将 services/billing 扩展为 services/billing/payment），则其父级将成为子域，而非组件。

规模指标

语句数（而非代码行数）：

• 统计以分号或换行符结尾的可执行语句
• 与代码行数相比，更适合用于规模比较
• 衡量代码复杂度，不受格式影响

组件规模指标：

• 代码库占比：组件语句数 / 总语句数
• 文件数：组件中的源文件数量
• 标准差：组件规模与平均值的差距

分析流程

阶段 1：识别组件

扫描代码库的目录结构：

1. 映射目录/命名空间结构

   • 对于 Node.js：services/、routes/、models/、utils/
   • 对于 Java：包结构（例如，com.company.domain.service）
   • 对于 Python：模块路径（例如，app/billing/payment）

2. 识别叶节点

   • 组件是包含源文件的最深层目录
   • 示例：services/BillingService/ 是一个组件
   • 示例：services/BillingService/payment/ 扩展了它，因此 BillingService 成为一个子域

3. 创建组件清单

   • 列出每个组件及其命名空间/路径
   • 标注所有父级命名空间（子域）

阶段 2：计算规模指标

针对每个组件：

1. 统计语句数

   • 解析组件目录中的源文件
   • 统计可执行语句（不包括注释、空行或单独的声明）
   • 汇总组件中所有文件的语句数

2. 统计文件数

   • 源文件总数（.js、.ts、.java、.py 等）
   • 排除测试文件、配置文件和文档

3. 计算百分比

   component_percent = (component_statements / total_statements) * 100
   

4. 计算统计数据

   • 组件规模平均值：total_statements / number_of_components
   • 标准差：sqrt(sum((size - mean)^2) / (n - 1))
   • 组件偏差：(component_size - mean) / std_dev

第 3 阶段：识别规模问题

过大的组件（可考虑拆分）：

• 占代码库总量超过 30%（适用于组件少于 10 个的小型应用）
• 占代码库总量超过 10%（适用于组件多于 20 个的大型应用）
• 超出平均值 2 个标准差以上
• 包含多个不同的功能领域

过小的组件（可考虑合并）：

• 占代码库总量不到 1%（粒度可能过细）
• 低于平均值 1 个标准差以上
• 仅包含少量文件，功能有限

规模适中的组件：

• 与平均值相差 1–2 个标准差
• 代表单一、内聚的功能领域
• 对应用规模而言，占比适当

输出格式

组件清单表

## Component Inventory

| Component Name  | Namespace/Path               | Statements | Files | Percent | Status       |
| --------------- | ---------------------------- | ---------- | ----- | ------- | ------------ |
| Billing Payment | services/BillingService      | 4,312      | 23    | 5%      | ✅ OK        |
| Reporting       | services/ReportingService    | 27,765     | 162   | 33%     | ⚠️ Too Large |
| Notification    | services/NotificationService | 1,433      | 7     | 2%      | ✅ OK        |

状态图例：

• ✅ 正常：规模适中（与平均值相差 1–2 个标准差）
• ⚠️ 过大：超过规模阈值或高于平均值 2 个标准差以上
• 🔍 过小：占代码库总量不到 1% 或低于平均值 1 个标准差以上

规模分析摘要

## Size Analysis Summary

**Total Components**: 18
**Total Statements**: 82,931
**Mean Component Size**: 4,607 statements
**Standard Deviation**: 5,234 statements

**Oversized Components** (>2 std dev or >10%):

- Reporting (33% - 27,765 statements) - Consider splitting into:
  - Ticket Reports
  - Expert Reports
  - Financial Reports

**Well-Sized Components** (within 1-2 std dev):

- Billing Payment (5%)
- Customer Profile (5%)
- Ticket Assignment (9%)

**Undersized Components** (<1 std dev):

- Login (2% - 1,865 statements) - Consider consolidating with Authentication

组件规模分布

## Component Size Distribution

组件规模分布（占代码库的百分比）

[如可行，请提供可视化表示或直方图]

最大：████████████████████████████████████ 33%（Reporting） ████████ 9%（Ticket Assign） ██████ 8%（Ticket） ██████ 6%（Expert Profile） █████ 5%（Billing Payment） ████ 4%（Billing History） ...

### Recommendations

```markdown
## Recommendations

### High Priority: Split Large Components

**Reporting Component** (33% of codebase):
- **Current**: Single component with 27,765 statements
- **Issue**: Too large, contains multiple functional areas
- **Recommendation**: Split into:
  1. Reporting Shared (common utilities)
  2. Ticket Reports (ticket-related reports)
  3. Expert Reports (expert-related reports)
  4. Financial Reports (financial reports)
- **Expected Result**: Each component ~7-9% of codebase

### Medium Priority: Review Small Components

**Login Component** (2% of codebase):
- **Current**: 1,865 statements, 3 files
- **Consideration**: May be too granular if related to broader authentication
- **Recommendation**: Evaluate if should be consolidated with Authentication/User components

### Low Priority: Monitor Well-Sized Components

Most components are appropriately sized. Continue monitoring during decomposition.

分析检查清单

组件识别：

• 映射所有目录/命名空间结构
• 区分叶节点（组件）与父节点（子域）
• 创建完整的组件清单
• 记录每个组件的命名空间/路径

规模计算：

• 统计每个组件的语句数（而非行数）
• 统计源文件数量（不包括测试/配置文件）
• 计算占代码库总量的百分比
• 计算平均值和标准差

规模评估：

• 识别过大的组件（超过阈值或高于平均值 2 个标准差）
• 识别过小的组件（占比不到 1% 或低于平均值 1 个标准差）
• 标记需要拆分或合并的组件
• 记录规模分布

建议：

• 提出过大组件的拆分方案
• 提出过小组件的合并方案
• 按影响优先级排列建议
• 为重构创建架构故事

实施说明

对于 Node.js/Express 应用

组件通常位于：

• services/ - 业务逻辑组件
• routes/ - API 端点组件
• models/ - 数据模型组件
• utils/ - 工具组件
• middleware/ - 中间件组件

组件识别示例：

services/
├── BillingService/          ← Component (leaf node)
│   ├── index.js
│   └── BillingService.js
├── CustomerService/          ← Component (leaf node)
│   └── CustomerService.js
└── NotificationService/      ← Component (leaf node)
    └── NotificationService.js

对于 Java 应用

根据包结构识别组件：

• com.company.domain.service - 服务组件
• com.company.domain.model - 模型组件
• com.company.domain.repository - 仓库组件

组件识别示例：

com.company.billing.payment   ← Component (leaf package)
com.company.billing.history   ← Component (leaf package)
com.company.billing           ← Subdomain (parent of payment/history)

语句计数

JavaScript/TypeScript：

• 统计以 ; 或换行符结尾的语句
• 包括：赋值、函数调用、返回语句、条件语句、循环
• 排除：注释、空行、未进行赋值的声明

Java：

• 统计以 ; 结尾的语句
• 包括：方法调用、赋值、返回语句、条件语句
• 排除：类/接口声明、注释、空行

Python：

• 统计可执行语句（不包括注释或空行）
• 包括：赋值、函数调用、返回语句、条件语句
• 排除：文档字符串、注释、空行

适应度函数

识别并确定组件规模后，创建自动化检查：

组件规模阈值

// Alert if any component exceeds 10% of codebase
function checkComponentSize(components, threshold = 0.1) {
  const totalStatements = components.reduce((sum, c) => sum + c.statements, 0)
  return components
    .filter((c) => c.statements / totalStatements > threshold)
    .map((c) => ({
      component: c.name,
      percent: ((c.statements / totalStatements) * 100).toFixed(1),
      issue: 'Exceeds size threshold',
    }))
}

标准差检查

// Alert if component is >2 standard deviations from mean
function checkStandardDeviation(components) {
  const sizes = components.map((c) => c.statements)
  const mean = sizes.reduce((a, b) => a + b, 0) / sizes.length
  const stdDev = Math.sqrt(sizes.reduce((sum, size) => sum + Math.pow(size - mean, 2), 0) / (sizes.length - 1))

  return components
    .filter((c) => Math.abs(c.statements - mean) > 2 * stdDev)
    .map((c) => ({
      component: c.name,
      deviation: ((c.statements - mean) / stdDev).toFixed(2),
      issue: 'More than 2 standard deviations from mean',
    }))
}

最佳实践

应做事项 ✅

• 使用语句数，而非代码行数
• 仅将叶节点识别为组件
• 同时计算百分比和标准差
• 设定阈值时考虑应用规模
• 记录每个组件的命名空间/路径
• 如可行，创建规模分布可视化图

不应做的事 ❌

• 计算组件大小时，不要将测试文件计入其中
• 不要将父目录视为组件
• 不要在未考虑应用规模的情况下使用固定阈值
• 不要忽略小型组件（可能需要合并）
• 不要跳过标准差计算
• 不要在同一分析中混合基础设施组件和领域组件

后续步骤

完成组件识别和大小评估后：

1. 应用 Gather Common Domain Components Pattern - 识别重复功能
2. 应用 Flatten Components Pattern - 从根命名空间中移除孤立类
3. 应用 Determine Component Dependencies Pattern - 分析组件之间的耦合
4. 创建组件领域 - 将组件归入逻辑领域

说明

• 组件大小阈值因应用规模而异
• 小型应用（<10 个组件）：30% 的阈值可能合适
• 大型应用（>20 个组件）：10% 的阈值更合适
• 标准差比固定百分比更可靠
• 大小合适的组件与均值相差 1-2 个标准差
• 过大的组件通常包含多个可拆分的功能区域