架构设计关键产出

在很多团队里，“架构设计”这个词听起来很高级，但真正落地时却变成了“开个会画两张图，然后就开工写代码”。结果是，开发过程中不断返工，模块边界模糊，技术决策摇摆，产品上线一团糟。

问题的根源在于——架构设计阶段缺乏明确的产出要求。到底要产出什么，才能说“架构设计完成”？

我结合实际项目经验，总结了一份技术架构与开发准备阶段的 12 项关键成果。明确了这 12 项，你的项目就能从一开始走得很稳。

一、架构设计类产出

让所有人看得懂系统长什么样、怎么跑、核心流程如何走。

1. 系统总体架构图

• 形式：一张包含前端、后端、区块链交互层、数据库、缓存、消息队列、外部服务的架构图（draw.io、Mermaid、Visio 都可）。

• 要求：

  • 模块边界清晰（商户后台、API 网关、支付服务、账本、风控等分开画）。
  • 每个模块标注主要职责。
  • 显示依赖关系（箭头表示数据/事件流向）。

• 目标：任何新加入的研发，看这张图就能知道整个系统有哪些组件、怎么通信。

2. 关键业务流程图

• 形式：时序图 / 流程图（支付流程、结算流程、风控拦截流程至少各一张）。

• 要求：

  • 明确参与方（商户、用户、API、链上监听、账本、回调）。
  • 按时间顺序展示每一步动作和状态变化。

• 目标：任何人照图就能复现一次完整支付/结算过程。

3. 接口规范（API 设计文档）

• 形式：OpenAPI 3.0 / Swagger 文件，或 Markdown 表格。

• 要求：

  • 列出每个接口的 URL、HTTP 方法、请求参数、返回字段、错误码。
  • 定义签名和鉴权机制（API Key / OAuth）。
  • 指定字段格式（金额、币种、时间戳等）。

• 目标：商户和前端可以直接按文档调 API，无需口头解释。

4. 数据库与账本设计

• 形式：ER 图 + 建表 SQL。

• 要求：

  • 列出所有核心表（商户、订单、账本、结算、风险日志、Webhook 日志等）。
  • 指明字段类型、索引、外键关系。
  • 账本系统需有双分录规则说明（资产增减的记账逻辑）。

• 目标：后端开发可以直接按图建表，账务逻辑统一。

5. 事件与消息队列定义

• 形式：事件主题清单（Topic）+ 消息格式说明。

• 要求：

  • 列出每个事件名（如 payment.tx.detected、payment.intent.succeeded）。
  • 定义消息体 JSON 字段及含义。
  • 指明事件生产方和消费方。

• 目标：不同服务之间的异步通信有标准格式，避免临时约定。

6. 链上监听与确认策略

• 形式：参数表 + 流程图。

• 要求：

  • 确认区块数、监听超时时间、地址生成策略、金额误差容忍度等。
  • 链上数据如何触发内部账本更新的步骤。

• 目标：区块链交互有统一规则，减少漏单/重复入账风险。

7. 风控与合规规则文档

• 形式：规则清单（Excel / Markdown）。

• 要求：

  • 黑名单来源和更新频率。
  • 高风险交易判定条件（金额、地理位置、交易模式）。
  • 触发后的处理动作（冻结、人工审核、拒绝）。

• 目标：研发和合规部门共用一份规则，系统实现有明确依据。

二、开发优先级产出

目标是明确先做什么，后做什么，避免范围失控，让团队聚焦核心功能交付。

8. MVP 范围与阶段目标

• 形式：表格或一页 PDF

• 内容：

  • MVP 要实现的功能（收款 API、链上监听、商户后台订单查询等）
  • 明确不做的功能（法币结算、多链支持等）
  • 阶段目标和验收条件（如：“支持 TRC20-USDT 支付，商户能收到成功回调，账本余额一致”）

9. 迭代计划 & 优先级排序

• 形式：甘特图 / Sprint Backlog 表格

• 内容：

  • 按优先级列出功能模块（先做 API & 链上监听 → 再做账本与回调 → 再做风控与结算）
  • 每个阶段产出物和预计时间
  • 明确哪些模块可并行开发，哪些有依赖

三、技术选型产出

目标是提前定好技术路线，避免中途换技术导致返工。技术决策透明化、标准化，降低沟通成本。

10. 技术栈选型文档

• 形式：Markdown 文档或表格

• 内容：

  • 后端语言（Go / Node.js / Python）及选择原因（性能、团队经验、生态）
  • 前端框架（React/Vue）、UI 库
  • 数据库（PostgreSQL/MySQL）、缓存（Redis）
  • 区块链 SDK（Web3.js / ethers.js / TronWeb）
  • 消息队列（Kafka / RabbitMQ）
  • 云服务 / 部署方案（Kubernetes / Docker / 云厂商）

11. 技术标准与规范

• 形式：团队开发规范文档

• 内容：

  • API 命名、版本管理规范
  • 代码风格（lint、格式化工具）
  • Git 分支与提交规范
  • 环境变量与密钥管理规则

12. 基础设施规划

• 形式：环境对照表 + 架构草图

• 内容：

  • 开发、测试、预发布、生产环境的域名、链、配置
  • CI/CD 流程说明（代码 → 构建 → 测试 → 发布）
  • 监控与日志方案（Prometheus、Grafana、ELK）

常见问题

A：是不是这 12 项都做完才能写代码？
Q：不必一次做完，可以分阶段完成。总体架构图、MVP 范围、技术栈选型、核心业务流程图需要在启动开发前明确好，其他可在开发过程中完善。这样既能快速启动，又能逐步完善设计，保持项目的灵活性和可控性。