作为后端工程师，我们经常需要编写设计文档。但你是否注意过，那些优秀的文档总能在恰当的地方使用图表，在需要细节的地方使用文字？经过多年实践和认知心理学研究，我总结出一套行之有效的方法。

一、图表与文字的DNA差异

技术文档本质上是在进行信息编码，而图表和文字是两种完全不同的编码方式：

维度 图表 文字
信息密度 高（一张架构图抵千言） 低（但精确）
解析方式 并行处理（整体感知） 线性处理（顺序阅读）
记忆留存率 65%（三天后） 10%（三天后）
创作成本 高（需专业工具） 低（纯文本即可）

二、后端文档的黄金分割法则

必须用图的5大场景

  1. 系统边界划分
    使用C4模型的L1上下文图，比如：

    1
    2
    [用户] -> [API网关] -> [订单服务] -> [支付服务]
              ^------------------------v

  2. 数据流动展示
    用序列图表现微服务调用，箭头宽度可代表流量压力。

  3. 状态机转换
    特别是支付/订单等有复杂状态变迁的业务：

    1
    2
    3
    4
    stateDiagram
      [*] --> PENDING
      PENDING --> SUCCESS: 校验通过
      PENDING --> FAILED: 超时3次

  4. 部署拓扑
    标注K8s集群、数据库实例等物理分布。

  5. 数据结构关系
    ER图比文字描述更直观展示表关联。

文字更合适的场景

• 字段约束：varchar(32) NOT NULL COMMENT '业务流水号'
• 算法描述：使用Snowflake算法，worker_id取IP最后两段模32
• 错误码：40001: 余额不足 | 40002: 风控拦截
• 事务说明：在@Transactional中设置isolation=REPEATABLE_READ

三、混合使用的进阶技巧

1. 分层绘图法

• L1架构图：Visio/Excalidraw手绘风格
• L2组件图：PlantUML代码化（可版本控制）
• L3代码图：IDEA自动生成UML

2. 结构化文字模板

1
2
3
4
5
6
## 缓存策略选择

| 策略          | 一致性   | 适用场景       | 代码示例       |
|---------------|---------|--------------|---------------|
| Write-through | 强一致   | 支付核心      | `@CachePut`   |
| Cache-aside   | 最终一致 | 商品信息      | `@Cacheable`  |

3. 动态文档技术

• Swagger UI：自动生成API可视化文档
• Mermaid.js：在Markdown中嵌入交互图表
• Diagrams as Code：用Python生成架构图

四、来自认知科学的建议

  1. 前注意加工：在架构图中使用不同颜色标注核心服务（人类视觉可在50ms内识别）
  2. 信息分块：每个图表包含4±1个主要元素（符合工作记忆容量）
  3. 双重编码：关键流程同时提供流程图和伪代码描述

五、要避免的三大反模式

  1. 蜘蛛网图：节点超过15个的流程图应该分层展示
  2. 幽灵引用：禁止出现”如上图所示”而图上未标注的情况
  3. 版本分裂：图表和文字出现版本不一致（建议嵌入git hash）

结语：蒙眼测试法则

写完文档后，尝试：

  1. 遮住所有图表，看文字是否能独立传达完整信息
  2. 遮住说明文字，看图表是否能自解释

通过这种双通道校验，你的技术文档将同时具备工程师需要的精确性和架构师需要的全局观。记住：好的文档就像好的代码——需要持续重构和维护。

许可协议

本文采用 署名-非商业性使用-相同方式共享 4.0 国际 许可协议，转载请注明出处。