跳至主要內容

19 文档、图示与架构表达

文档与架构资产证据链
文档与架构资产证据链源文件、构建器、审查、导出物和治理状态共同决定一份技术资产是否可信。高清原图

技术文档真正难的不是“写出来”，而是半年后仍能回答：源文件在哪里，用什么版本生成，为什么做这个决策，谁确认过，图和代码是否仍然一致，接口变更会影响谁，离开当前平台还能不能恢复。

Markdown 页面、Mermaid 图、draw.io 文件、ADR、OpenAPI 契约和 Confluence 空间看似属于不同工具，进入团队后却共享同一条资产链：可维护源进入版本控制或受控知识空间，确定的工具链把它编译成可阅读输出，评审记录确认事实与权限，治理状态负责替代、废弃、导出和退出。缺少其中任意一环，文档都会从工程资产退化为一张“当时看起来正确”的截图。

文档资产链

源文件是可继续修改的事实，导出物是某次构建的交付结果。导出物可以随站点发布，但必须能回到源文件、工具版本和来源提交；只有 PNG 没有图源、只有在线页面没有可恢复导出、只有 API 文档没有 schema 校验，都不构成完整资产。

阅读路径

现场问题先看继续建立的工程能力
团队不知道该用哪种文本格式Markdown、MDX 与 AsciiDoc渲染方言、可执行内容、include、构建和迁移边界
图即代码在本地和站点显示不一致MermaidCLI/站点双渲染、主题字体、安全级别和失败证据
需要时序图、组件图或受控渲染服务PlantUMLJava、Graphviz、include、安全 profile、服务隔离和缓存
架构草图需要可视化编辑与版本化draw.io 与 Excalidraw源格式、附件、协作、只读导出和隐藏数据清理
多张架构图开始互相矛盾C4 Model 与 Structurizr单一模型、分层视图、DSL 校验、导出和漂移治理
团队反复争论已经做过的选择ADR决策状态、owner、替代链、关联变更和决策债务
API 或事件变更直到联调才暴露OpenAPI 与 AsyncAPIschema、lint、预览、兼容检查、示例脱敏和发布入口
知识散落在多个在线平台Confluence、语雀与 Notion空间权限、搜索、导出、离职回收、成本和退出演练

五类资产合同

文档源

文本源至少记录格式、解析器、插件、构建命令和输出位置。Markdown 不等于统一运行时，同一文件在 CommonMark、GFM、站点插件和 IDE 预览中可能产生不同结果；MDX 还会执行组件与模块代码；AsciiDoc 的 include 和 attribute 会扩大输入边界。团队需要锁定实际渲染链，而不是只在规范里写“使用 Markdown”。

图形源

图即代码工具要保存 .mmd、.puml 或 DSL；可视化工具要保存 .drawio、.excalidraw 等可编辑源。SVG、PNG 与 PDF 面向阅读和发布，不应成为唯一事实源。字体、外部图片、远程 include 和主题文件都属于构建输入，必须能在 CI 或受控容器里重新取得。

决策状态

ADR 不是会议纪要文件夹。每条决策要有编号、状态、背景、约束、选择、后果、owner、关联变更和替代关系。新决策取代旧决策时，两端都要可追踪；删除旧文件只会抹掉原因，不能表达迁移。

接口契约

OpenAPI 与 AsyncAPI 文件进入与代码相同的审查链。解析成功只是第一层，后面还要有组织规则、引用解析、破坏性变更检查、消费者验证和发布版本。Mock 与 Codegen 可以缩短反馈，但不能证明实现、权限、重试、顺序或运行时兼容。

知识空间

在线知识库要记录空间 owner、成员来源、页面权限、匿名分享、Integration Token、附件、审计、导出和恢复责任。团队拥有账号不等于拥有知识资产；只有结构、正文、附件、链接和权限关系都能导出并恢复，退出计划才算存在。

构建与发布基线

仓库内可以采用这样的最小结构：

docs/
  handbook/
  architecture/
    diagrams/
    adr/
    workspace.dsl
  api/
    openapi.yaml
    asyncapi.yaml
  review/
scripts/docs/
  lint.mjs
  render.mjs
  verify-exports.mjs

本机和 CI 执行同一组命令：解析文本、渲染图、校验契约、检查链接、比较导出物、扫描敏感内容。构建产物应记录来源提交和生成器版本；如果项目提交导出物，CI 还要验证重新生成后 git diff 为空，防止图源与图片分叉。

权限与数据边界

文档工具经常被低估为“只读工具”，实际可能读取仓库、执行插件、启动浏览器、访问远程 include、上传附件、调用 SaaS API 或导出完整空间。默认边界至少包括：

  1. 不可信 MDX、PlantUML、Mermaid 或插件不能进入高权限构建环境。
  2. 共享渲染服务限制文件读取、网络访问、并发、超时和输出大小。
  3. 图和契约示例不保存真实 Token、Cookie、内网域名、客户数据与生产 payload。
  4. 可编辑导出、SVG 链接、图片元数据、隐藏图层和附件逐项检查后才能公开。
  5. SaaS Token 使用独立集成身份和最小权限，人员离职时同时回收账号、Token、外部分享和内容 owner。

失败与恢复底线

解析或渲染失败时，先保存源文件、工具版本、退出码、日志、字体和输入依赖，不要用截图替换失败资产。契约变更失败时，保留破坏性差异和受影响消费者，不要通过关闭规则让流水线变绿。知识库导出失败时，先核对附件数、页面层级、链接和权限映射，再决定是否迁移；一个能解压的 ZIP 不是恢复证据。

工具退出或替换时，恢复目标不是“还能看到旧页面”，而是团队能继续编辑源文件、重新生成输出、查询历史决策、校验接口契约并重建必要权限。这个目标决定了日常应该保存哪些源、元数据和审查记录。

跳到正文