renaissance-architecture

文艺复兴式架构

创造真正全新的事物。不要做“面向 Y 的 X”。

---

核心理念

问题不在于现代工具，而在于我们构建的是评论，而不是创造。

中世纪学者写的是亚里士多德的评论，而不是新的哲学。我们制作《星球大战》衍生作品，而不是新的科幻作品。我们把 AI 加进现有工作流，而不是思考哪些工作流因此成为可能。

文艺复兴式架构意味着：

• 从第一性原理出发，思考要构建什么
• 以务实的方式选择如何构建
• 创造新的范式，而不是扩展旧范式
• 利用现代工具，让真正全新的事物成为可能

---

架构原则

1. 默认简单，复杂性要有充分理由

从简单开始，只有在痛点可衡量时才增加复杂性。

从……开始	转向	适用情况
SQLite	Postgres	并发写入者 >10、数据量 >100GB，或需要 PostGIS/全文搜索
单文件	多个文件	文件超过约 500 LOC，或承担多项职责
单体架构	服务	团队无法在同一代码库上协作，或确实需要规模隔离
静态托管	服务端	需要身份验证、实时功能或服务端计算
本地状态	云同步	多设备是用户的真实需求，而非想当然

**这不是教条，而是默认做法。**如需违反，请记录理由。

---

2. 框架选择

只有在框架确实能带来优势时才使用。

框架	适用情况	避免使用的情况
Next.js	全栈 React 应用、SSR 很重要、团队熟悉该框架	简单的静态网站、非 React 团队
Remix	数据密集型应用、优先考虑渐进增强	简单的 SPA、团队不熟悉该框架
Astro	内容型网站、局部水合有价值	高度交互式应用
SvelteKit	精简包体至关重要、团队愿意学习	大型现有 React 代码库
Rails/Django	快速构建 CRUD 应用、管理面板、经过验证的模式	实时功能需求较重、团队更偏好 JS
FastAPI	Python API、异步能力很重要	简单脚本、团队更偏好其他语言
Hono/Elysia	Edge 函数、轻量级 API	需要完整框架的复杂应用

问题不在于“要不要用框架”，而在于“这个框架是在服务我们要创造的东西，还是我们在创造服务于框架的东西？”

---

3. 人类可读的系统

配置

• YAML/JSON 都没问题，格式本身不是问题
• 问题在于：包含嵌套条件判断的 500 行配置
• 好的标准：新团队成员能在 10 分钟内读懂并修改配置
• 在行内说明不易理解的设置

能起到指导作用的错误消息

• 发生了什么
• 为什么会发生
• 应该如何处理
• 如果问题复杂，附上文档链接

易于理解的日志

• 面向机器的结构化日志（JSON）
• 面向开发的可读格式
• 包含时间戳、上下文和严重级别
• 无需专用工具即可搜索

文档与代码放在一起

• 每个重要目录都要有 README
• 从代码生成 API 文档
• 记录架构决策（ADR）
• 外部 Wiki 仅用于入职和流程说明

---

4. 在合适的场景采用本地优先

不是“绝不用云”，而是“不做不必要的云依赖”。

功能	本地优先的做法	适合使用云的情况
核心功能	离线可用	核心功能永远不应依赖云
数据存储	SQLite/本地存储	同步、备份、多设备
计算	尽可能在客户端执行	处理量大、需要共享资源
身份验证	本地会话可用	第三方 OAuth、企业 SSO

状态应可供检查

• 将状态序列化为文件，以便调试
• 状态机应显式定义，而非隐式存在
• 可从快照重现

将同步作为增强功能

• 尽可能以本地数据为事实来源
• 同步失败不应导致应用无法使用
• 冲突解决方式应明确，并由用户控制

5. 组合思维

以下情况优先选择库，而非框架：

• 你只需要一种能力，而不是一整套生态系统
• 你想掌控架构
• 退出成本比速度更重要

以下情况优先选择框架，而非库：

• 团队具备相关专业知识
• 上市时间至关重要
• 约定优于配置很有价值
• 框架的设计理念符合你的需求

API 暴露基础功能

• 便捷方法没有问题
• 但高级用户可以访问更底层的功能
• 不要把机器藏起来

尽量降低退出成本

• 数据可导出为标准格式
• 尽可能避免专有技术锁定
• 记录退出路径，即使你永远不会用到它

---

云与基础设施

何时适合使用云

用例	适合使用云	本地／边缘更合适
身份验证	企业级 SSO、OAuth 提供商	简单的用户名／密码
存储	多设备同步、协作	单用户、支持离线
计算	大型 ML 推理、视频处理	文本处理、简单转换
数据库	多写入者、全球分布	单用户、本地优先
实时功能	多用户协作	单用户状态

务实地使用云

• 无服务器适用于负载突增且难以预测的场景
• 边缘函数适用于对延迟敏感的操作
• 当运维开销 > 成本时，使用托管数据库
• 控制权／成本／合规性有要求时，采用可自托管方案

问题在于：云是在服务你的用户，还是在服务你对并不存在的规模的假设？

---

UI/UX 理念

1. 即时反馈

用户操作的反馈时间 <100ms；较长操作则如实显示进度

• 在安全时采用乐观更新（可回滚）
• 进度指示器应反映实际工作
• 使用旋转加载图标没有问题——它能如实表示正在处理
• 对可预测的加载模式使用骨架屏

加载状态应当：

• 显示正在发生什么
• 尽可能估算耗时
• 允许取消长时间运行的操作
• 绝不伪造进度

---

2. 状态可见

用户始终知道系统在做什么

• 无需深入查找即可看到状态
• 显示后台进程
• 突出显示错误，而不是将其隐藏
• 在决策不明显时，由系统说明原因

没有黑箱

• 用户能理解某件事为何发生
• 重要操作有审计跟踪
• 可在开发者工具中检查状态

---

3. 空间一致性

放在哪里，就保持在哪里

• 加载完成后不发生布局偏移
• 不要“为了用户”重新排列内容
• 保持肌肉记忆有效
• 组件位置保持一致

导航应当可预测

• 返回按钮可正常工作
• URL 可添加书签并分享
• 刷新后状态仍然保留
• 深层链接可正常工作

---

4. 撤销与恢复

在数据层实现，而不仅仅是在 UI 中实现

• 默认软删除
• 在有价值时对状态进行版本管理
• 记录恢复路径
• “确定吗？”不能代替撤销功能

破坏性操作

• 对不可逆操作进行确认
• 永久删除前设置宽限期
• 清楚说明操作后果

---

5. 尊重注意力

通知

• 用户明确选择接收
• 有实际意义，而不是为了提升参与度
• 适当合并发送
• 易于调整或关闭

模态框与打断

• 由用户发起，而不是由系统发起
• 可以关闭
• 不要不必要地锁定焦点
• 支持键盘操作

自动播放

• 音频绝不自动播放
• 视频仅在用户明确选择时播放
• 动画应遵循 prefers-reduced-motion

默认设置优于自定义

• 良好的默认设置可以减少选项
• 提供高级用户选项，但不强制要求使用
• 逐步呈现复杂性

---

本文反对的做法

衍生式思维

• 不问 Y 是否需要 X，就提出“面向 Y 的 X”
• 因为竞争对手有某项功能就添加它
• 因为教程用了某种模式就照搬
• 因为 FAANG 这么做就采用某种架构

盲目照搬工程实践

• 照搬不同规模公司的“最佳实践”
• 3 人团队采用微服务
• 单服务器负载采用 Kubernetes
• 内部工具采用 OAuth

过早复杂化

• “为未来灵活性”而增加抽象层
• 在出现规模问题之前就扩展架构
• 基础功能尚未完善就添加特性
• 单用户场景尚未可用就实现实时功能

流程凌驾于思考之上

• Scrum 仪式取代了实际思考
• 文档为合规而写，而非为了清晰
• 为了开会而开会
• 路线图假装能够预测未来

---

应用

审查设计时

第一性原理检查

• 这会创造什么新事物？（而不是“它会扩展什么现有事物？”）
• 为什么需要它？
• 它能带来哪些以前不可能实现的事情？

简洁性检查

• 复杂性是有必要的，还是想当然的？
• 新开发者能在一小时内理解它吗？
• 能解决核心问题的最简单版本是什么？

工具适配性检查

• 工具选择是为了服务于创造，还是创造在为工具服务？
• 这个框架是否适合团队的专业能力和问题需求？
• 云依赖是必需的，还是想当然的？

人类可读性检查

• 有人能通过阅读配置理解它吗？
• 错误消息能起到指导作用吗？
• 开发者能在需要的地方找到文档吗？

UI/UX 检查

• 反馈是即时的，还是明确地逐步呈现？
• 用户能看到系统正在执行什么吗？
• 所有操作都能恢复或撤销吗？
• 中断是否由用户主动发起？

---

生成解决方案时

先问：

1. 我们真正要创造什么新事物？
2. 能实现它的最简单架构是什么？
3. 哪些复杂性是实际约束所要求的？

默认选择：

• 能用的最简单工具
• 如果团队熟悉且适用，就用框架
• 尽可能采用本地优先方案
• 确有需要时再用云

在以下情况下增加复杂性：

• 痛点可衡量，而非理论上的
• 团队认同这种权衡
• 已记录回归简单方案的路径

---

升级阈值

何时从默认方案升级：

从	到	触发条件
SQLite	Postgres	并发写入者 >10，或数据量 >100GB，或需要 PostGIS/全文搜索
单体架构	服务	团队无法在同一代码库上协作，或确实需要隔离规模
静态	服务端	需要身份验证、实时功能或服务端计算
本地存储	云同步	多设备是经验证的用户需求，而非想当然的假设
库	框架	团队具备专业能力，且上市时间至关重要，并且框架的设计理念契合
简单	复杂	痛点可衡量，而非理论上的

---

合理的例外

在以下情况下，复杂性可以接受：

• 框架：团队具备专业能力，问题符合框架的设计理念，且上市时间很重要
• 云依赖：需要多用户协作、繁重计算或合规要求
• 微服务：团队无法在单体架构上协调协作，或确实需要隔离规模
• 重量级工具：构建投入能换来更高的开发效率

**记录理由。**未来的你会感谢现在的自己。

---

务实的默认方案

从简单开始，在痛点可衡量时再增加复杂性。

1. 从可行的最简单架构开始
2. 等待真实问题出现，而非臆想的问题
3. 优化前先进行衡量
4. 记录增加复杂性的原因
5. 确保存在回归简单方案的路径

过早复杂化就是会产生利息的技术债务。

---

反教条条款

这些是默认方案，不是铁律。有充分理由并做好记录时，可以违背。

这里的每条原则都有合理的例外。目标不是追求纯粹，而是有意识地做出选择。

偏离原则的合理理由：

• 团队的专业能力明显更适合其他方案
• 业务时间表要求采用更快的路径
• 监管或合规要求
• 经衡量的性能需求
• 用户研究结果与假设相悖

偏离原则的不合理理由：

• “大家都这么做”
• “以后可能会需要”
• “教程里就是这么用的”
• “这是最佳实践”（却不理解原因）

**偏离原则时，请写下原因。**在注释、ADR 或 README 中写一句话即可。

---

快速参考

维度	默认方案	升级条件
存储	SQLite	并发写入、扩展规模或需要更多功能时
框架	如果团队熟悉，就使用	如果更简单，可从头构建
云	确实需要时才使用	不要想当然，先验证
配置	YAML/JSON，并提供完善文档	-
错误	提供有助于理解的消息	-
加载	使用能如实显示进度的加载指示器	-
状态	可见、可检查	-
撤销	在数据层进行版本管理	-
复杂性	应有充分理由，而非想当然	记录决策依据

---

核心问题

设计任何事物时，都要问：

“我是在创造新事物，还是在评论已有事物？”

文艺复兴建筑并非要拒绝现代工具，而是要用它们创造真正的新事物，而不只是再添一种既有模式的变体。

中世纪学者只能撰写评注，因为他们相信真理已在过去揭示。我们没有这样的限制。我们可以创造。