common-mistakes

# 常见的 C4 模型错误及避免方法 本指南记录了创建 C4 架构图时常见的反模式和错误，并提供了正确的做法示例。 ## 抽象级别错误 ### 1. 混淆容器和组件 **问题：** 容器是**可部署单元**（应用程序、服务、数据库）。组件是**容器内不可部署的元素**（模块、类、包）。 **错误 - 将 Java 类显示为容器：** mermaid C4Container title 错误：将类作为容器 Container(userController, "UserController", "Java 类", "处理用户请求") Container(userService, "UserService", "Java 类", "业务逻辑") ContainerDb(db, "数据库", "PostgreSQL", "用户数据") Rel(userController, userService, "调用") Rel(userService, db, "查询") **正确 - 将类作为容器内的组件：** mermaid C4Component title 正确：将类作为组件 ContainerDb(db, "数据库", "PostgreSQL", "用户数据") Container_Boundary(api, "用户 API 服务") { Component(userController, "UserController", "Spring MVC", "REST 端点") Component(userService, "UserService", "Spring Bean", "业务逻辑") Component(userRepo, "UserRepository", "JPA", "数据访问") } Rel(userController, userService, "调用") Rel(userService, userRepo, "使用") Rel(userRepo, db, "查询", "JDBC") ### 2. 添加未定义的抽象级别 **问题：** C4 明确定义了四个级别。不要发明“子组件”、“模块”或其他任意级别。 **错误：** - 级别 3.5：“子组件” - 级别 2.5：“微服务组” - 自定义级别，如“包”或“模块” **正确：** 坚持使用人员、软件系统、容器、组件。如果需要更多细节，说明您处于第 4 级（代码），应使用 UML 类图。 ### 3. 模糊的子系统 **问题：** “子系统”含义模糊。它是系统、容器还是组件？ **错误：** Subsystem(orders, "订单子系统", "处理订单") **正确 - 具体化：** System(orderSystem, "订单系统", "处理订单生命周期") # 或 Container(orderService, "订单服务", "Java", "订单处理 API") # 或 Component(orderProcessor, "订单处理器", "Spring Bean", "订单业务逻辑") ## 共享库错误 **问题：** 将共享库建模为容器意味着它是一个独立运行的服务。库是被复制到应用程序中的，而不是单独部署的。