How to Write Architecture Docs That Developers Actually Read

Bad documentation example

"本系统采用微服务架构，使用Spring Cloud框架，通过Nginx做负载均衡，MySQL做主数据库，Redis做缓存，Kafka做消息队列..."

Issues: log‑like description, no focus, missing context, unclear problem being solved.

Good architecture document example

系统名称： 用户中心服务 解决的问题： 为其他业务系统提供统一用户认证、授权、用户信息查询服务，避免重复建设用户模块。 核心能力： 用户注册登录（支持手机号、邮箱、第三方OAuth） Token签发与验证 用户信息CRUD 权限管理（RBAC） 技术方案： 见下文 接口列表： 见附录

Common architecture document types

ADR (Architecture Decision Record)

# ADR-001: 采用JWT作为认证Token
## 状态
已通过，2024-01-15
## 背景
需要为移动端和Web端提供无状态的认证方案。
## 决策
采用JWT（JSON Web Token）作为认证Token。
## 选项对比
| 选项 | 优点 | 缺点 |
| JWT | 无状态、跨域 | 大小限制、不可撤销 |
| Session | 可控、可撤销 | 需要存储、有状态 |
## 后果
- 正面：性能好，扩展性强
- 负面：Token过期需要前端刷新处理
## 相关决策
- ADR-002: Token过期时间设置

Technical solution template

# 【功能名称】技术方案
## 1. 背景与目标
### 1.1 背景
- 业务背景是什么？
- 遇到什么问题？
- 为什么需要此功能？
### 1.2 目标
- 功能目标
- 非功能目标（性能、可用性等）
### 1.3 范围
- 本次方案覆盖范围
- 不在范围内的（后续计划）
## 2. 需求分析
### 2.1 功能需求
| 需求ID | 描述 | 优先级 |
| F001 | 用户可以通过手机号注册 | P0 |
| F002 | 用户可以设置登录密码 | P0 |
| F003 | 支持第三方登录 | P1 |
### 2.2 非功能需求
| 类型 | 描述 | 指标 |
| 性能 | 注册接口响应时间 | <500ms |
| 可用性 | 服务可用性 | 99.9% |
| 容量 | 同时在线用户 | 1,000,000 |
## 3. 方案设计
### 3.1 整体架构
[描述或图示整体架构]
### 3.2 模块设计
#### 3.2.1 用户注册模块
[详细设计]
#### 3.2.2 登录认证模块
[详细设计]
### 3.3 数据模型
<pre><code>CREATE TABLE `user` (
  `id` BIGINT NOT NULL AUTO_INCREMENT,
  `username` VARCHAR(50) NOT NULL COMMENT '用户名',
  `phone` VARCHAR(20) DEFAULT NULL COMMENT '手机号',
  `password_hash` VARCHAR(255) NOT NULL COMMENT '密码哈希',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP,
  `updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_username` (`username`),
  UNIQUE KEY `uk_phone` (`phone`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

### 3.4 接口设计 #### 用户注册

POST /api/v1/users/register
{
  "username": "string",
  "password": "string",
  "phone": "string"
}
Response:
{
  "code": 0,
  "message": "success",
  "data": {"userId": "12345"}
}

Risk assessment

并发注册导致重复： 可能性中，影响高， mitigation: 数据库唯一约束 + 幂等处理。

密码泄露： 可能性低，影响高， mitigation: 加密存储，HTTPS 传输。

Test plan

单元测试：核心逻辑覆盖，覆盖率 > 80%。

接口测试：所有接口验证，全部通过。

性能测试：并发注册，QPS > 1000。

Post‑deployment metrics

注册成功率 > 99.9%。

平均响应时间 < 500ms。

错误率 < 0.1%。

Conclusion

好文档 = 清晰的结构 + 准确的内容 + 适当的细节 + 定期维护

Key writing points:

开门见山说明要解决的问题。

用数据说明，避免模糊形容词。

图文并茂，使用表格或列表代替大量文字。

考虑不同读者的关注点。

保持文档更新，防止过期。