软件文档写作-plantuml画用例图和时序图
背景
当下的软件开发人员，不可避免的需要输出一些软件设计文档，作为一个软件工程专业毕业的工程师，最常用的设计工具就是UML，使用UML工具绘制一些软件相关的图，是必备技能，也是输出的技术文档中的重要组成部分。不关注逆向工程，这里只关注快速的绘制对应的图，plantuml是一款比较不错的工具。本节先初步熟悉用例图和时序图。
plantuml介绍
官网主页
功能介绍：
支持快速绘制
- 时序图
- 用例图
- 活动图
- 类图
- 组件图
- 状态图
- 对象图
- 部署图
- 定时图
还支持非UML图：
- 架构图
- 甘特图
- 思维导图
- ER图
以及不常用的的图：
- SDL（规范描述语言）
- 线框图形界面
- Ditaa
- 数学公式
画完图之后，可以生成PNG,SVG,Latex格式的图片;
业务场景
x项目的用户后端服务,包括用户登录，用户积分模块；
用例图
用户角度描述系统功能
语法
系统用例图
内部系统用例
@startuml
left to right direction
actor : 其它LX提供给TA的后端系统: as otherLxTaBackendService
note top of otherLxTaBackendService
比如tianansp
负责活动和文章的服务
比如tiananseason
负责西游活动的服务
通过dubbo的rpc方法调用
end note
usecase 修改用户积分 as changeUserPoint
usecase 查询用户总积分 as getUserTotalPoint
usecase 登录校验 as getRestContextByAccessToken
otherLxTaBackendService --> getRestContextByAccessToken:获取用户的登录态[RPC]
otherLxTaBackendService --> changeUserPoint:活动增加或者扣减积分[RPC]
otherLxTaBackendService --> getUserTotalPoint: 查询用户当前总积分[RPC]
@enduml生成的图：
外部系统用例
@startuml
'left to right default
actor : ta用户: as taUser
usecase 用户登录 as userLogin
usecase 查询积分明细 as findUserPointDetail
usecase 改变积分 as changeUserPointDetail
note bottom of userLogin
TA用户登录
LX交互的后端系统
LX的saas系统
构造登录态
end note
taUser -right-> userLogin: 登录进LX交付的功能[REST]
taUser --> changeUserPointDetail : 修改积分\n阅读文章\n分享文章\n参加活动[REST]
taUser --> findUserPointDetail : 查询积分\n消费获取\n明细[REST]
@enduml
时序图（顺序图）
展示对象跟对象之间的协作关系
语法
| 对象 | 语法 | 说明 |
|---|---|---|
| 箭头和线 | -> <-实线箭头 <-- -->虚线箭头 | 标识参与者之间的消息传递 |
| 参与者 | actor 角色 boundary 带边界 control控制 entity 实体 database 数据库 collections 集合 participant 参与者 | 标识参与者 |
| 重命名 | participant 参与者详细名称 as 简称 | 重命名参与者 |
| 定义顺序 | participant 参与者详细名称 order 排序号 | 序号越小越靠前 |
| 参与者含有特殊字符 | “参与者” | 双引号包围 |
| 箭头样式 | 丢失的消息 ->x 实心箭头 -> 虚箭头 ->> 半实心箭头 - 半虚箭头 -\ 箭头末尾加0 ->o |
各种箭头 |
| 箭头颜色 | 参与者1-[颜色定义]->参与者 | 改变箭头颜色 |
| 消息自动编号 | autonumber | 放在开始的位置 |
| 设置 | title,header,footer | header footer title在开始的地方定义 |
| 组合消息条件分支 | alt/else end |
条件分支 |
| 组合消息循环分支分支 | loop end | 循环 |
| 组合消息 group | group end |
分组 |
| 单行注释 | note 位置 ：注释内容 | 给消息增加备注 |
| 多行注释 | note 位置（right,left,over） 换行 注释内容 换行 end note | 给消息增加备注 |
| 改变注释的形状 | hnote 六边形 rnote 四边形 | 注释的形状 |
| 分隔符 | ==分割备注内容== | 横向划分模块 |
| 引用 | ref over 参与者1 参与者2 : 引用内容 | 引用 |
| 延迟 | ···标识延迟 ··· | 消息固定延迟 |
| 空间 | 3根竖线 | 间隔 |
| 激活生命线 | activate 参与者 | 激活生命线 |
| 取消激活生命线 | deactivate 参与者 | 激活生命线 |
| 返回 | return 参与者 | 返回 |
| 创建参与者 | create 参与者 | 标识创建对象 |
| 快捷键 | 激活参与者 --取消激活参与者 ** 创建参与者 ！！销毁参与者 | 见语法说明 |
| 创建盒子 | box "box的命名" #背景色 换行 参与者1 参与者2 end box | 纵向划分模块 |
登录接口时序图
@startuml
autonumber "[00]"
title 登录接口时序图
actor "TA用户" as User #white
participant "TAAPP" as TAAPP #gold
box "LX交付" #gray
participant "LX交付SDK" as LXSDK #orange
participant "LX交付后端\ntiananuser" as LXServer #red
participant "LXsaas后端" as LXSaasServer #gray
end box
participant "TA后端" as TAServer #green
activate User
User -> TAAPP : 登录TAAPP\n打开健康TAP页面
==sdk对接==
TAAPP -> LXSDK : userId\n或者加密信息
==后端对接==
LXSDK -> LXServer : 登录转换为LX登录态接口
==TA后端对接==
LXServer <-> TAServer : 用户信息校验\n
==对接saas==
LXServer <-> LXSaasServer : 注册并登录\n到LXSaas
==构造LX专属登录态==
LXServer -> LXServer : 登记用户信息\n保存登录令牌到redis
LXServer -> LXSDK : 构造LX专属登录态(token)
==后端对接完成==
LXSDK --> TAAPP : 正常使用LX交互功能
TAAPP --> User : 看到LX交互功能
@enduml
改变用户积分
@startuml
autonumber "[#]"
actor TAapp用户 as taUser
control 网关 as nginx
box 接口程序 #green
boundary Web服务器 as tomcat
end box
collections Redis as redis
database Mysql as mysql
taUser -> nginx : 看文章，增加积分
nginx ->> tomcat : 负载均衡策略遭到一台tomcat
==接口处理流程开始==
tomcat --> tomcat : 参数判断
alt 参数判断不合法
tomcat -[#red]> taUser : 参数传错误
else 参数合法
tomcat -> mysql : 插入积分改变的明细记录
return 表记录id
tomcat ->redis : 获取缓存中用户对应的记录id
alt 缓存中userId对应的积分id存在
tomcat -> mysql : 更新用户的总积分
else 缓存中userId对应的积分id不存在
tomcat -> mysql : 查询得到用户对应的id
alt 用户的总积分记录在数据库中存在
tomcat -> mysql :更新用户的总积分
else userId对应的积分记录id不存在
tomcat -> mysql :插入用户的总积分记录
end
return 用户积分记录对应的记录id
tomcat -> redis : 用户积分记录对应的记录id保存到redis
return 无返回值
end
tomcat ->redis: 清除掉总积分缓存，分页缓存，总条数缓存
return 用户增加积分明细记录id
end
tomcat -[#green]> taUser : 改变积分成功
@enduml查询用户积分
小结
原创不易，转载请注明出处，欢迎多沟通交流