上下文图完全指南：从入门到画好一张专业的系统边界图

上下文图Context Diagram是系统设计中最顶层的一张图。它只回答三个问题系统是什么、谁在用它、它跟哪些外部系统有交互。不展示任何内部实现只画边界。正因为简单它往往是架构沟通中信息密度最高、受众最广的一张图。一、上下文图是什么上下文图又称系统上下文图或 Level 0 数据流图是结构化系统分析的起点。它的核心特征特征说明单一中心整个系统只画一个方框/圆圈不拆分内部组件只画边界图上只有系统内部和系统外部两个区域外部实体围绕中心的所有人、系统、组织都是外部实体数据流箭头标注系统与外部实体之间传递的数据/请求零实现细节不画数据库、不画微服务、不画代码结构一张上下文图就是系统的一张身份证——告诉所有人这个系统的范围在哪、跟谁打交道、打交道的方式是什么。二、上下文图的三类元素元素类型图形约定含义示例系统中心方框或圆圈你要建设/维护的软件系统在线支付平台、教务管理系统外部人员矩形方框直接使用系统的真人角色用户、管理员、运营人员外部系统矩形方框与系统交互但不在你控制范围内的其他系统支付网关、短信服务、CRM注意区分运维工程师不是外部人员除非他直接使用系统界面。如果只是维护系统的人不画在图上。上下文图画的是直接交互方不是所有利益相关者。三、上下文图与相邻图表的关系很多人会把上下文图和架构图、DFD搞混。它们的关系是层层递进的关系图表类型视角粒度内部结构典型用途上下文图系统边界最粗系统1个方框无范围界定、需求确认、干系人沟通数据流图(DFD Level 1)内部数据流中等系统拆为几个主要过程有子过程需求分析、流程梳理架构图技术实现最细展示组件/服务/数据库完整技术栈技术方案评审、开发参考用例图功能视角用例级别角色与功能映射需求验证、功能范围一句话总结上下文图画的是系统的外墙DFD画的是墙内的走廊架构图画的是每间房里的家具。四、C4模型中的上下文图在 C4 架构描述模型中上下文图对应 Level 1System Context是四个层级中的最顶层C4层级名称内容对应角色Level 1System Context系统作为一个整体 外部交互所有人含非技术干系人Level 2Container系统内部的主要容器应用、数据库、消息队列等架构师、技术负责人Level 3Component每个容器内部的组件/模块开发工程师Level 4Code类级别细节可选很少画具体开发者C4模型强调Level 1 上下文图是所有架构沟通的起点。不是代码、不是架构图而是这张最简单的边界图。因为只有先回答系统是什么、谁在用、跟谁连才能讨论内部怎么实现。五、六步绘制法第1步定义系统给系统起一个清晰的名字。用干系人能理解的业务名称不用技术名称。正确示例订单交易系统、在线支付平台错误示例Spring Boot微服务集群 v2.3、Java后端写一句话描述系统的核心职责这个系统做什么它在什么场景下提供什么价值第2步识别外部人员问自己四个问题谁直接使用这个系统列出所有角色每个角色用系统做什么动作级别有没有来自合作方的外部用户如合作商户有没有内部团队通过系统界面操作的人注意只画直接交互的人。不画间接干系人如CEO不直接用系统不画。第3步识别外部系统问自己三个问题系统需要调用哪些外部服务出站调用哪些外部系统会调用本系统入站调用有没有内部遗留系统被当作黑盒对待原则如果某个系统不在你团队的修改范围内就画成外部系统。不因为它是公司内部的就不画。第4步绘制数据流用带标签的箭头连接系统和外部实体。每条箭头标注三个要素要素说明示例方向谁发起的数据传输用户→系统提交订单内容传输的是什么数据系统→支付网关支付请求双向如果是双向交互用双向箭头用户↔系统登录认证标签用动词名词格式如提交订单、查询库存、推送状态通知。避免模糊标签如数据交互、通信。第5步审查边界画完后逐项自检系统边界是否清晰一个方框代表整个系统外部实体数量是否合理建议3-8个超过8个考虑是否画得太细每个外部实体是否直接与系统交互有没有画了不该画的间接干系人箭头标签是否具体能不能一眼看懂在传什么数据非技术人员能否看懂这张图拿给产品经理看一遍第6步迭代更新上下文图不是画完就锁死。以下场景需要更新新增外部系统集成时如接入新的支付渠道系统边界发生变化时如拆分微服务、合并系统新增用户角色时如开放给合作伙伴使用架构评审或需求评审时定期复核六、五个常见错误错误1把内部组件画进来了上下文图只画一个系统方框。数据库、缓存、消息队列、微服务——这些是内部实现不属于上下文图的范畴。画进来就成了架构图失去了上下文图最简沟通的价值。错误2外部实体太多如果图上有15个外部实体说明你在画需求清单而不是系统边界。聚焦核心交互方3-8个最佳。次要的可以合并或省略。错误3标签太模糊箭头上写数据交互、API调用——等于没写。标签要具体到提交订单请求、返回支付结果这种动作对象的粒度。错误4混入实现技术系统方框上写K8s集群、Redis缓存——上下文图不关心技术栈。一个方框只写业务名称和核心职责。技术细节留给架构图。错误5忘记验证画完直接归档不拿给干系人看。上下文图最大的价值是对齐认知——你以为系统边界是这样的产品以为边界是那样的运营以为边界又不一样。不验证就白画了。七、与其他图表的配合上下文图不是孤立使用的它是图表体系的入口配合图表配合方式价值架构图上下文图定义边界 → 架构图展示边界内的技术实现先对齐范围再讨论实现数据流图(DFD)上下文图定义Level 0 → DFD Level 1拆分内部过程从粗到细的层次化分析时序图上下文图标注的数据流 → 时序图展示具体调用时序从数据流到调用细节ER图上下文图标注的系统 → ER图展示系统内部数据模型从系统范围到数据结构用例图上下文图的外部人员 → 用例图的角色来源从角色识别到功能映射八、工具选择工具适用场景优点不足纸笔/白板快速讨论、头脑风暴零门槛、随时修改、参与感强无法保存和版本管理draw.io / Excalidraw正式文档、评审材料免费、上手快、导出格式多无结构化校验Lucidchart企业协作、多人编辑模板丰富、协作流畅付费StructurizrC4模型专用直接生成C4四层图、语义化学习门槛较高上下文图结构极简任何工具都能画。选工具的关键不在于功能多少而在于干系人能不能打开看。如果评审人打不开文件画得再好也没用。singcheng.com九、自检清单发布前逐项核对系统方框只有一个名称用的是业务语言外部实体数量在3-8个之间每个都有明确交互每条数据流箭头都有具体标签动词名词图上没有任何内部组件、数据库、技术栈信息拿给非技术人员看过他能看懂系统范围系统边界与需求文档中的范围一致所有外部系统的交互方向是否标注清楚是否记录了制图日期和版本号是否标注了假设和约束条件