C4-PlantUML 项目中的图例样式问题解析

问题背景

在使用 Structurizr CLI 生成 PlantUML 图时，开发者发现生成的图例中出现了意外的样式属性（如 $lineStyle）。这不仅影响了图例的美观性，也可能导致用户对图例信息的误解。

问题分析

经过技术分析，这个问题主要源于以下几个方面：

1. 样式属性大小写问题：在生成的代码中，$borderstyle 属性使用了首字母大写的值（如 "Solid"），而实际上应该使用小写形式（如 "solid"）。

2. 默认样式显示问题：当 $borderThickness="1" 这样的默认值被显式设置时，系统会认为这是一个特殊设置，从而将其显示在图例中。

3. 不必要的属性显示：$lineStyle 等属性本不应该出现在图例中，这是需要修复的一个bug。

解决方案

针对上述问题，项目团队已经提供了以下解决方案：

1. 样式属性标准化：

   • 使用小写形式表示样式值（如 "solid" 而非 "Solid"）
   • 推荐使用预定义的宏（如 SolidLine()）来设置样式，这能提高代码的可读性和一致性

2. 布局指令优化：

   • 使用 LAYOUT_TOP_DOWN() 替代 "top to bottom direction"
   • 使用 LAYOUT_LANDSCAPE() 替代 "left to right direction"，这能确保关系箭头的方向正确

3. 图例显示优化：

   • 修复了 $lineStyle 等不必要属性显示在图例中的问题
   • 默认样式属性（如 $borderThickness="1"）不再显示在图例中

最佳实践建议

1. 简化样式定义：除非需要特殊样式，否则不必显式设置默认值，这样可以避免不必要的图例信息。

2. 使用标准布局宏：始终使用 LAYOUT_TOP_DOWN() 或 LAYOUT_LANDSCAPE() 来设置布局方向。

3. 保持样式一致性：使用项目提供的预定义宏来设置样式，这能确保不同图表间的一致性。

4. 最小化包含文件：只需要包含必要的文件（如 C4_Container.puml），避免包含冗余文件导致缓存问题。

总结

通过这次问题的解决，C4-PlantUML 项目的图例显示更加清晰和专业。开发者在使用时应注意遵循项目的最佳实践，使用标准化的样式定义和布局指令，以获得最佳的图表效果。项目团队也持续关注用户体验，及时修复发现的bug，确保工具的稳定性和易用性。