组合结构图（CSD）是一种专门的UML图，旨在展示分类器的内部结构及其各部分之间的交互。虽然它们能提供系统架构的细粒度视图，但创建这些图需要极高的精确度。在组合、连接或定义中的任何单一错误，都可能导致开发阶段出现重大误解。
许多工程师将这些图视为类图的可选扩展，但它们具有独特的目的：揭示复杂对象的拓扑结构。设计得当，它们能阐明组件如何协作以履行职责；设计不当，则会引入歧义，导致实施停滞。
本指南探讨了在创建这些图时经常出现的七种错误。通过识别这些陷阱，您可以确保架构文档保持准确且可操作。
1. 混淆组件与类 🏷️
最常见的错误是将组合部件简单地视为类。虽然CSD中的组件在技术上属于分类器，但其角色与类图中的标准类有着本质区别。
- 类代表单个单元内的数据结构与逻辑。
- 组件代表可独立部署的实现模块化单元。
当您在组合结构内部绘制部件时，您正在定义一个具有自身生命周期和接口契约的物理或逻辑单元。如果您仅使用类属性和方法来定义部件，而未指定端口或接口，就会丢失结构上下文。
为何这很重要：
- 它模糊了部署边界。
- 它隐藏了交互协议。
- 它会导致代码生成过程中的混淆。
纠正策略：
- 确保每个部件都代表一个独立的工作单元。
- 验证部件是否已定义用于通信的接口。
- 区分内部实现细节与外部契约。
2. 忽视端口与接口 🚪
组合结构图本质上是一张交互蓝图。如果没有端口和接口，组件的内部连接将不可见。
许多设计者直接在部件之间绘制连接，而未定义入口和出口点。这在UML语义上是技术上错误的。连接必须附着于端口，且端口必须由接口进行类型定义。
常见错误：
- 直接将一个部件连接到另一个部件。
- 使用无箭头的线条来表示方向。
- 未指定接口是提供的（棒棒糖符号）还是所需的（插座符号）。
对架构的影响：
如果没有明确的端口，该图就无法展示依赖管理。此时将无法确定哪个部件依赖于哪个服务。这种歧义会在软件开发生命周期的后期引发耦合问题。
最佳实践：
- 始终为每个交互点定义一个端口。
- 在端口上指定接口类型。
- 使用提供的和所需的接口构造型来显示依赖关系的流向。
3. 过度复杂化内部结构 🕸️
细节很有价值，但过多的细节会使图表失去作用。一个常见的错误是试图在单个组合结构图中记录组件的整个内部逻辑。
当组合结构变得过于密集时，读者将无法追踪数据或控制的流向。该图表的目的是展示结构，而非行为。如果您发现自己正在部件内部添加状态转换或活动流，则很可能已经超出了组合结构图（CSD）的范围。
过度复杂化的迹象：
- 单个分类器内部包含超过 5-7 个部件。
- 部件隔间内包含密集的文字描述。
- 多个嵌套的组合结构。
修正策略：
- 将大型组件拆分为子组合结构。
- 关注部件之间的关系，而非内部代码。
- 使用单独的图表来表示行为（状态机图或活动图）。
4. 忽视连接语义 🧵
连接器定义了数据在部件之间的流动方式。然而，这些连接的语义往往被忽略。简单的线条无法传达足够的关联类型信息。
在组合结构中，您必须区分以下类型：
- 关联：一种结构关系。
- 依赖：一种使用关系。
- 聚合：一种共享所有权关系。
表：连接器类型
| 连接器类型 | 含义 | 视觉指示器 |
|---|---|---|
| 关联 | 部件之间存在结构关系 | 普通线条 |
| 依赖 | 一个部分使用另一个部分 | 虚线箭头 |
| 组合 | 部分随整体一同消亡 | 实心菱形 |
| 聚合 | 部分可以独立存在 | 空心菱形 |
为什么语义很重要：
错误的连接符意味着错误的生命周期管理。如果在需要聚合的地方使用了组合菱形，则意味着部分无法脱离整体而存在。这会限制架构的灵活性。
5. 命名规范不一致 📝
可读性依赖于术语的一致性。一个常见的疏忽是在图表与代码库或其他 UML 工件之间混用命名风格。
常见不一致之处：
- 对某些部分使用驼峰命名法，而对其他部分使用蛇形命名法。
- 使用实现类名称而非逻辑角色来标记部分。
- 使用未在别处定义的缩写。
对协作的影响：
当开发人员查看图表以理解系统时，他们期望看到熟悉的术语。如果图表显示“PaymentProcessor” 但代码中却是“PayService”，所需的心理转换会产生摩擦。
标准化规则：
- 为所有部分采用严格的命名规范。
- 确保部分名称反映其功能，而非文件名。
- 保持名称与领域模型一致。
6. 误用部分生命周期（组合与聚合）⚖️
整体与其部分之间的关系决定了生命周期。当设计者混淆组合与聚合时，会出现关键错误。
组合：部分在没有整体的情况下没有意义。如果整体被销毁，部分也会被销毁。示例：一个“房屋 及其 门.
聚合： 部件可以独立存在。示例：一个 团队 及其 成员.
为何这种区分至关重要：
- 它影响内存管理策略。
- 它影响数据库持久化逻辑。
- 它定义了错误处理的边界。
修正：
审查每个部件的所有权规则。问：“如果主组合体被移除，该部件是否仍能存在？”如果答案是肯定的，请使用聚合；如果是否定的，请使用组合。
7. 未能展示部件内部的行为 🎭
组合结构图侧重于结构，但它并非孤立存在。通常，设计者未能将结构与驱动该结构的行为联系起来。
虽然你不应该在部件内部绘制完整的活动流程，但应标明该部件是否具有影响组合体的内部状态或操作。
应包含的内容：
- 向组合体暴露的操作。
- 与组合体功能相关的状态变化。
- 部件之间传递的信号。
应排除的内容：
- 完整的调用序列。
- 详细的算法逻辑。
- 与外部系统的交互（除非与部件相关）。
最佳实践：
使用构造型或标签来标明部件是否包含重要的行为逻辑。这向读者表明，该部件不仅仅是一个数据容器。
比较：组合结构图与类图 📊
为确保清晰，理解何时使用组合结构图与标准类图至关重要。二者不可互换。
| 特性 | 组合结构图 | 类图 |
|---|---|---|
| 重点 | 分类器的内部结构 | 类之间的关系 |
| 粒度 | 部件、端口、连接器 | 属性、方法、关联 |
| 部署视图 | 可暗示部署 | 仅限逻辑视图 |
| 复杂度 | 高（适用于复杂对象） | 中等（标准建模） |
| 用途 | 基于组件的架构 | 面向对象设计 |
验证清单 ✅
在最终确定图表之前，请对照此验证清单检查常见错误。
- 端口已定义：所有外部交互是否都定义了端口？
- 接口已类型化：端口是否连接到特定的接口定义？
- 生命周期正确：组合和聚合的菱形符号是否准确？
- 范围已检查：内部结构是否清晰可读且未过于拥挤？
- 名称一致：部件名称是否与领域模型匹配？
- 连接器是否有效：连线是否表示有效的关系？
- 行为上下文：如有必要，是否已注明关键内部行为？
最终考量 🧭
设计有效的组合结构图需要在结构保真度和可读性之间取得平衡。其目标是清晰地传达系统组件的内部组织。
通过避免上述错误，您可以确保您的图表成为开发人员和利益相关者的可靠参考。端口、接口和关系的精确性可防止实施阶段出现歧义。
请记住，图表是沟通工具，而不仅仅是代码的记录。如果新团队成员在不加解释的情况下无法理解该图表，则需要进行简化。应专注于定义系统行为和稳定性的结构关系。
遵循这些准则将产生经得起时间考验的文档，支持架构的演进，而无需频繁重写。