架构规范模板
阶段 4 模板：系统架构规范
文档信息
| 字段 |
值 |
| 项目名称 |
{项目名称} |
| 版本 |
1.0.0 |
| 创建日期 |
{日期} |
1. 架构概述
1.1 高层架构
graph TB
subgraph "客户端层"
WEB[Web 应用]
MOBILE[移动应用]
API_CLIENT[API 客户端]
end
subgraph "API 网关"
GW[API 网关 / 负载均衡]
end
subgraph "应用层"
SVC1[服务 1]
SVC2[服务 2]
SVC3[服务 3]
end
subgraph "数据层"
DB[(主数据库)]
CACHE[(缓存)]
QUEUE[消息队列]
end
subgraph "外部"
EXT[外部服务]
end
WEB --> GW
MOBILE --> GW
API_CLIENT --> GW
GW --> SVC1
GW --> SVC2
GW --> SVC3
SVC1 --> DB
SVC2 --> DB
SVC3 --> DB
SVC1 --> CACHE
SVC2 --> CACHE
SVC1 <--> QUEUE
SVC2 <--> QUEUE
SVC3 --> EXT
1.2 架构模式
| 模式 |
描述 |
| 类型 |
单体 / 微服务 / 无服务器 |
| 通信方式 |
REST / GraphQL / gRPC / 事件驱动 |
| 数据策略 |
共享数据库 / 每服务一库 |
2. 技术栈
2.1 前端技术栈
| 组件 |
技术 |
版本 |
选择理由 |
| 框架 |
|
|
|
| 状态管理 |
|
|
|
| UI 组件库 |
|
|
|
| 构建工具 |
|
|
|
2.2 后端技术栈
| 组件 |
技术 |
版本 |
选择理由 |
| 运行时 |
|
|
|
| 框架 |
|
|
|
| ORM |
|
|
|
| 校验库 |
|
|
|
2.3 数据技术栈
| 组件 |
技术 |
版本 |
选择理由 |
| 主数据库 |
|
|
|
| 缓存 |
|
|
|
| 消息队列 |
|
|
|
| 搜索引擎 |
|
|
|
2.4 基础设施技术栈
| 组件 |
技术 |
选择理由 |
| 云服务商 |
|
|
| 容器编排 |
|
|
| CI/CD |
|
|
| 监控 |
|
|
3. 组件架构
3.1 组件目录
| 组件 |
类型 |
描述 |
所属模块 |
| API 网关 |
基础设施 |
请求路由、限流 |
平台 |
| 认证服务 |
服务 |
认证、授权 |
MOD-AUTH |
|
|
|
|
3.2 组件交互
sequenceDiagram
participant 客户端
participant 网关
participant 认证服务
participant 业务服务
participant 数据库
客户端->>网关: 携带 Token 的请求
网关->>认证服务: 校验 Token
认证服务-->>网关: Token 有效
网关->>业务服务: 转发请求
业务服务->>数据库: 查询数据
数据库-->>业务服务: 返回数据
业务服务-->>网关: 响应
网关-->>客户端: 最终响应
4. 数据架构
4.1 数据库设计原则
| 原则 |
描述 |
| 命名规范 |
表/列使用 snake_case |
| 主键 |
UUID v4 |
| 软删除 |
使用 deleted_at 列 |
| 时间戳 |
所有表包含 created_at, updated_at |
4.2 数据流
graph LR
A[数据源] --> B[转换]
B --> C[存储]
C --> D[服务]
4.3 数据所有权
5. 集成架构
5.1 内部集成
| 集成点 |
协议 |
模式 |
描述 |
| 服务间通信 |
HTTP/REST |
同步 |
直接 API 调用 |
| 事件通信 |
消息队列 |
异步 |
发布/订阅模式 |
5.2 外部集成
5.3 API 版本策略
| 策略 |
实现方式 |
| URL 版本控制 |
/api/v1/resource |
| Header 版本控制 |
Accept: application/vnd.api+json;version=1 |
6. 安全架构
6.1 认证流程
sequenceDiagram
participant 用户
participant 客户端
participant 认证服务器
participant 资源服务器
用户->>客户端: 登录请求
客户端->>认证服务器: 凭据
认证服务器->>认证服务器: 校验
认证服务器-->>客户端: 访问令牌 + 刷新令牌
客户端->>资源服务器: API 请求 + 令牌
资源服务器->>认证服务器: 校验令牌
认证服务器-->>资源服务器: 令牌有效
资源服务器-->>客户端: 响应
6.2 安全层级
| 层级 |
控制措施 |
| 网络 |
防火墙、VPC、安全组 |
| 传输 |
TLS 1.3、证书固定 |
| 应用 |
输入校验、OWASP Top 10 防护 |
| 数据 |
静态加密、字段级加密 |
6.3 密钥管理
| 密钥类型 |
存储位置 |
轮换周期 |
| API 密钥 |
Vault/云密钥管理 |
90 天 |
| 数据库凭据 |
Vault |
30 天 |
| JWT 签名密钥 |
KMS |
180 天 |
7. 可扩展性架构
7.1 扩展策略
| 组件 |
扩展类型 |
触发条件 |
| API 服务器 |
水平扩展 |
CPU > 70% |
| 数据库 |
垂直扩展 + 只读副本 |
连接数 > 80% |
| 缓存 |
水平扩展 |
内存 > 80% |
7.2 负载均衡
| 层级 |
方法 |
健康检查 |
| L4 (TCP) |
轮询 |
TCP 连接 |
| L7 (HTTP) |
最少连接 |
HTTP /health |
7.3 容量规划
| 指标 |
当前 |
6 个月 |
12 个月 |
| 日活用户 |
|
|
|
| 请求/秒 |
|
|
|
| 数据存储 (GB) |
|
|
|
8. 部署架构
8.1 环境配置
| 环境 |
用途 |
数据 |
扩展 |
| 开发环境 |
功能开发 |
模拟数据 |
单实例 |
| 测试环境 |
集成测试 |
脱敏数据 |
类生产 |
| 生产环境 |
正式流量 |
真实数据 |
自动扩展 |
8.2 部署流水线
graph LR
A[代码提交] --> B[构建]
B --> C[单元测试]
C --> D[集成测试]
D --> E[测试环境部署]
E --> F[E2E 测试]
F --> G[生产环境部署]
G --> H[冒烟测试]
8.3 基础设施即代码
| 工具 |
用途 |
| Terraform |
云基础设施 |
| Docker |
容器化 |
| Kubernetes |
编排 |
9. 可观测性架构
9.1 监控技术栈
| 组件 |
工具 |
用途 |
| 指标 |
Prometheus/Grafana |
系统和应用指标 |
| 日志 |
ELK Stack |
集中式日志 |
| 链路追踪 |
Jaeger/Zipkin |
分布式追踪 |
9.2 告警策略
| 严重程度 |
响应时间 |
通知方式 |
| 严重 |
5 分钟 |
电话 + 即时通讯 |
| 警告 |
1 小时 |
即时通讯 |
| 信息 |
下个工作日 |
邮件 |
9.3 SLI/SLO
| SLI |
SLO |
测量方式 |
| 可用性 |
99.9% |
正常运行监控 |
| 延迟 (P95) |
< 500ms |
APM |
| 错误率 |
< 0.1% |
错误追踪 |
10. 灾难恢复
10.1 备份策略
| 数据类型 |
频率 |
保留期 |
存储位置 |
| 数据库 |
每小时 |
30 天 |
跨区域 |
| 文件存储 |
每天 |
90 天 |
跨区域 |
| 配置 |
变更时 |
永久 |
Git |
10.2 恢复流程
| 场景 |
RTO |
RPO |
恢复步骤 |
| 数据库故障 |
1 小时 |
1 小时 |
故障转移到副本 |
| 区域故障 |
4 小时 |
1 小时 |
激活灾备站点 |
11. 架构决策记录 (ADR)
ADR-001：{决策标题}
| 属性 |
值 |
| 状态 |
提议中 / 已采纳 / 已废弃 |
| 日期 |
|
| 背景 |
要解决什么问题？ |
| 决策 |
建议/实施的变更是什么？ |
| 后果 |
有哪些权衡？ |
12. 合规与标准
12.1 标准合规
| 标准 |
要求 |
实现方式 |
| 等保三级 |
数据保护 |
访问控制、加密存储 |
| SOC 2 |
安全控制 |
审计日志、访问控制 |
12.2 代码标准
| 标准 |
工具 |
配置文件 |
| 代码检查 |
ESLint/Pylint |
.eslintrc / .pylintrc |
| 代码格式化 |
Prettier/Black |
.prettierrc / pyproject.toml |
| 类型检查 |
TypeScript/mypy |
tsconfig.json / mypy.ini |
校验清单
