工程实践02

架构设计实践

用质量属性和取舍驱动架构设计:确定关键质量属性,划分系统层次,用 ADR 记录决策,交付可评审的架构图和接口契约。

P0 · 《企业级系统架构设计规范》

目标

把架构设计从画图变成可评审的决策过程:质量属性、取舍、ADR、架构图和接口契约一一对应。

  • 从业务目标推导质量属性并排序
  • 候选方案按同一组维度对比,写清代价
  • 关键决策落成 ADR,图和文档只引用编号
  • 交付六张图、接口契约和评审检查单

原则

  1. 从质量属性出发先确认系统最不能坏的是哪一点,再决定分层、冗余和一致性策略。
  2. 实时与控制链路分离视频和遥测走长连接通道,指令下发走独立的有状态服务,任务状态只在平台服务里流转。
  3. AI 在末端、人在环上AI 只输出候选事件和结构化动作,处置由人决定,不可逆动作必须人工确认。
  4. ADR 编号贯穿文档只引用 ADR 编号,不复述内容;每张图都能指回对应的决策。

流程

推导评估决策产出校验需求与约束业务目标 · 硬约束质量属性排序性能 · 一致性 · 可用性质量场景方案对比两个以上候选 · 同维度对比表ADR 决策记录结论 · 代价 · RevisitADR-00xx架构图与契约六张图 · 接口契约OpenAPI评审与演进检查单 · 版本迭代reviewFlow: 架构设计实践
阶段与产物
阶段输入处理输出
需求与约束业务目标、合规与资源限制识别关键参与者、外部系统和硬约束约束清单、非目标
质量属性排序约束清单写可度量的质量场景并排序质量属性表
方案对比质量属性与现状给出两个以上候选,按同一组维度比较方案对比表
ADR 决策对比结论记录结论、理由、代价和 Revisit 条件ADR 文档
图与契约ADR 集产出分层图、链路图、部署图和接口契约六张图、OpenAPI / AsyncAPI
评审与演进图与契约按检查单评审,记录遗留问题与版本评审记录、架构版本

规范

个人实践

六张必交图与评审检查单

  • 六张图:功能架构、业务流程、总体架构、技术架构、交互时序、部署架构
  • 每张图标注版本和对应 ADR 编号
  • 评审检查单核对质量属性、压测数据和故障演练证据
  • 遗留问题登记负责人和截止时间

工程做法

接口契约模板

  • 错误码按服务前缀编号,前端只按错误码分支
  • 写操作必须定义幂等键和重复请求的返回
  • 超时、拒绝、部分成功分别定义,避免把超时当成功重试
示例
# 统一动作接口(节选)
POST /actions/{action}
请求:{ deviceId, params, confirmToken? }
响应:{ actionId, status: accepted | rejected | timeout }
错误码:DEVICE_OFFLINE / NEED_CONFIRM / DUPLICATE_ACTION
幂等键:actionId

个人实践

ADR 决策记录

  • 至少两个候选方案,按同一组维度比较
  • 代价写清:运维复杂度、一致性损失、迁移成本
  • 写明 Revisit 条件,条件触发时重新评审
示例
# ADR-0003 设备上报使用 MQTT
状态:已采纳
背景:设备需要长连接上报遥测,HTTP 轮询延迟不可接受
决策:MQTT over TLS,EMQX 集群接入
代价:需要维护会话与离线消息,运维复杂度上升
Revisit:设备量超过 5 万或需要双向强一致时重新评估
交付物与提示词模板
  • 《企业级系统架构设计规范》与六张图模板
  • 六张可交互架构图(无人机智能作业平台)
  • 平台 ADR 集(含取舍、代价与重新评估条件)
  • 接口契约模板与设计评审检查单
  • 统一动作层改造前后对比与审计日志样例
为一个「设备实时接入 + 业务状态管理 + AI 辅助决策」的系统设计分层架构,不要直接堆技术名词。
按以下顺序输出:
1) 从业务目标推导 3 个质量属性并排序,说明最不能坏的是哪一个;
2) 给出分层(终端 / 接入 / 业务应用 / 平台服务 / 数据与中间件 / 基础设施),每层写职责与「不负责什么」;
3) 分别画出实时上行与指令下行两条链路经过哪些层,指出瓶颈与隔离点;
4) 说明 AI 能力放在哪一层、它不能做什么、人工确认放在哪里;
5) 列出 3 个关键 ADR 标题,每个含两个候选方案与各自代价、Revisit when。
约束:状态只能在一处流转;AI 不进入控制闭环;每张图都要能指回某个 ADR 编号。
行业参考

案例真实项目

Copilot 工具调用链改造

  • Agent 输出动作名加参数,协议适配收敛在动作层
  • 起飞、返航、清除记录强制人工确认,确认态写进审计日志
  • 超时、拒绝、部分成功分别定义返回,避免把超时当成功重试
  • 每次调用记录输入、动作、结果和确认人,支持逐条回放

真实项目:无人机智能作业平台,改造前后均有架构图与 ADR 对照。

效果与局限

6 张可交互架构图

功能、流程、总体、技术、时序、部署

3 项 ADR关键决策

MQTT 上报、统一动作层、状态机位置

1 份接口契约

统一动作层的字段、错误码与幂等键

局限

  • 规范在单平台验证,多团队并行评审流程尚未运行。
  • 六张图对小型系统偏重,裁剪规则还需按项目规模补充。

图与 ADR 可在站内 /architecture 页面逐项核对。