PlantUML非功能性标注实战指南

在系统架构设计中，非功能性需求的可视化表达与功能性需求同等重要。本文将深入讲解如何使用PlantUML进行性能、安全、可靠性和事务等方面的标注，帮助您在时序图中完整呈现系统质量属性。

一、性能指标注释

性能指标是系统设计的关键约束条件，PlantUML提供了多种方式标注性能相关参数。

响应时间标注

@startuml
用户 -> 服务A: 查询请求
activate 服务A
服务A -> 服务B: 数据获取
... 300ms以内 ...
服务B --> 服务A: 返回数据
hnote over 服务A #LightBlue: 响应时间SLA\n<500ms
服务A --> 用户: 返回结果
deactivate 服务A
@enduml

关键语法：

... [时间] ... 表示预期延迟
hnote over 添加半透明注释框
颜色编码区分不同级别的SLA（如红色表示关键路径）

实践建议：

对核心链路标注端到端响应时间
使用不同颜色区分SLA等级
在异步调用处标注预期延迟范围

二、安全约束标记

安全要求需要通过视觉元素明确标识，避免设计疏漏。

认证授权标注

@startuml
participant 客户端
participant API网关 as gateway #LightGray
database 认证服务 as auth

客户端 -> gateway: 请求(含token)
gateway -> auth: 验证token
alt 验证成功
    gateway -> 业务服务: 转发请求
    hnote right gateway #Pink: 🔒 TLS 1.2+ required
else 验证失败
    gateway --> 客户端: 401 Unauthorized
end
@enduml

关键元素：

锁图标(🔒)表示安全要求
粉色背景高亮安全相关组件
alt/else 处理认证失败场景

最佳实践：

对敏感接口使用hnote结合安全图标
显式标注加密要求（如TLS版本）
为安全边界组件设置特殊颜色

三、可靠性标注

可靠性设计需要在流程中可视化重试、熔断等机制。

重试机制可视化

@startuml
客户端 -> 服务A: 订单创建请求
activate 服务A

loop 3次重试
    服务A -> 服务B: 库存扣减
    alt 调用成功
        break
    else 调用失败
        hnote right 服务A: 指数退避重试\n(间隔: 200ms, 500ms)
    end
end

服务A --> 客户端: 创建结果
deactivate 服务A
@enduml

关键设计：

loop块表示重试次数上限
hnote说明重试策略细节
break在成功时退出循环

实施建议：

明确标注重试次数和退避策略
对关键服务添加熔断器标记
使用group包裹容错逻辑块

四、事务边界标识

分布式事务需要清晰界定边界以保证数据一致性。

事务块标注

@startuml
participant "订单服务" as order
participant "库存服务" as stock
participant "支付服务" as payment

group 分布式事务 [try阶段]
    order -> stock: 预占库存
    order -> payment: 预授权扣款
end

group 事务确认 [confirm阶段]
    order -> stock: 确认扣减
    order -> payment: 实际扣款
end

hnote over order,payment #LightGreen: 最大努力型事务\n(重试3次+人工补偿)
@enduml

标注要点：

group划分事务阶段
颜色区分不同事务类型
hnote说明事务特性

设计原则：

显式标注事务参与方
区分柔性事务和刚性事务
标注异常处理方式

综合应用示例

@startuml
participant 客户端
participant "API网关" as gateway #LightGray
participant "订单服务" as order #LightBlue
database "MySQL" as db #LightGreen

客户端 -> gateway: POST /orders
hnote over gateway #Pink: 🔒 JWT校验+限流1000QPS

group 核心事务 [超时:2s]
    gateway -> order: 创建订单
    activate order
    
    order -> db: begin transaction
    loop 库存重试 [max 3次]
        order -> 库存服务: 扣减库存
        alt 库存不足
            order --> gateway: 409 Conflict
            break
        end
    end
    
    order -> 支付服务: 预授权
    hnote right 支付服务: 响应时间<300ms\n(99%分位)
    
    alt 全部成功
        order -> db: commit
        order --> gateway: 201 Created
    else 任何失败
        order -> db: rollback
        order --> gateway: 500 Error
    end
    deactivate order
end

hnote over order,db #LightYellow: 事务监控埋点\n(异常自动告警)
@enduml

总结

通过PlantUML的非功能性标注，我们可以在设计阶段：

明确性能SLA和关键路径指标
标识安全边界和防护要求
可视化可靠性设计模式
界定事务一致性边界

建议将这些标注纳入团队的设计评审checklist，确保质量属性在架构阶段就被充分考虑。对于复杂系统，可以建立标注规范（如颜色编码标准），提升图纸的可读性和一致性。

PlantUML非功能性需求标注实战：性能与安全可视化