modern-web-app-architecture

现代 Web 应用架构（SPA/SSR/SSG/RSC）

概述

全面指导如何设计和构建现代 Web 应用（包括 SPA 和混合渲染应用）。本技能强调权衡、明确边界和生产就绪实践（性能、无障碍、安全、测试、交付）。

核心原则： 架构中的一切都是权衡。没有绝对“正确”的答案，只有最适合特定情境的组合。

工作模式（如何使用此技能）

激活后，按以下顺序开展工作：

1. 明确情境（最多 5–10 个问题） → 用户、路由、SEO、交互性、数据、身份验证、团队、约束。
2. 为每条路由选择渲染策略（而不是“整个应用只用一种策略”）。
3. 定义边界 → 功能/领域模块、共享库、所有权和稳定接口。
4. 规划状态和数据 → 本地/共享/全局/服务端/URL 状态、缓存策略、失效处理、乐观更新。
5. 规划非功能性需求 → 性能预算与衡量、无障碍计划、安全态势、可观测性。
6. 产出成果 → 简明建议并明确权衡，同时提供具体后续步骤（文件夹结构、ADR、检查清单）。

如果用户无法回答某个问题，请说明合理的假设并继续（不要因此停下）。

适用场景

• 启动新的 SPA 或 Web 应用
• 选择渲染策略（CSR、SSR、SSG、ISR、RSC）
• 实施状态管理
• 优化 Core Web Vitals（LCP/INP/CLS）
• 扩展到多个前端团队
• 做出架构权衡决策
• 从旧版前端迁移到现代前端

快速了解需求的问题（先提问）

• 最重要的 3 个用户旅程是什么？其目标延迟是多少（例如，“搜索 → 商品 → 结账”）？
• 是否有任何路由需要 SEO？哪些是公开的，哪些需要身份验证？
• 数据形态是什么：主要是 CRUD、实时数据、离线优先、复杂表单，还是大型表格/图表？
• 有哪些约束：浏览器支持、包体积限制、上市时间、合规要求（SOC2/HIPAA/PCI）？
• 团队构成如何：有多少开发人员/团队、发布频率如何、所有权边界是什么？
• 你偏好的技术栈是什么（React/Vue/Angular/vanilla）？是否愿意使用 TypeScript？

参考文件

主题	何时加载
@references/design-patterns.md	实施 JS 模式（Module、Observer、Factory 等）时
@references/react-patterns.md	使用 React 组件、hooks、状态和组合时
@references/spa-fundamentals.md	设计 SPA 架构、路由和模块组织时
@references/micro-frontends.md	扩展团队并实现独立部署时
@references/performance.md	优化包体积、加载和 Core Web Vitals 时
@references/architecture-decisions.md	评估权衡、耦合和适应度函数时
@references/rendering-strategies.md	比较 CSR、SSR、SSG、ISR 和 RSC 时
@references/state-management.md	设计本地、全局和服务端状态模式时
@references/security-and-auth.md	选择身份验证方式，处理令牌存储、XSS/CSRF、CSP 和 API 边界时
@references/accessibility-and-i18n.md	了解 WCAG 基础知识、SPA 焦点管理、包容性组件和 i18n 陷阱时
@references/testing-and-quality.md	制定测试策略、CI 质量门禁、无障碍检查和契约测试时
@references/tooling-and-delivery.md	处理打包、环境、部署、可观测性和功能开关时

快速架构决策树

Project Requirements?
├─ SEO critical + dynamic content → SSR (or SSR+streaming)
├─ SEO critical + mostly static → SSG/ISR (or hybrid)
├─ Mostly behind auth + app-like UX → CSR SPA (or hybrid with pre-rendered shell)
├─ Mixed (marketing + app) → Hybrid/Islands (route-level strategy)
│
Team Size?
├─ <5 developers → Modular monolith SPA
├─ 5-15 developers → Well-structured SPA or Service-based
├─ >15 developers, multiple teams → Consider micro-frontends
│
Domain Complexity?
├─ Simple CRUD → Layered architecture
├─ Complex workflows → Domain-partitioned (DDD)
├─ Multiple bounded contexts → Micro-frontends

默认输出（应提供的内容）

根据用户请求，尽量输出：

• 路由策略图：用小型表格列出路由 → CSR/SSR/SSG/ISR/RSC，并说明原因
• 模块边界草图：功能文件夹、共享库、接口契约
• 状态图：本地/共享/全局/服务端/URL，以及选用的工具模式
• 数据方案：缓存/失效、错误状态、乐观更新、分页
• 质量方案：测试层级 + CI 门禁 + 无障碍检查
• 性能方案：预算 + 衡量方式 + 具体加载策略（拆分点）
• 风险登记表：排名前 5 的风险 + 缓解措施（例如，水合开销、身份验证方案、团队耦合）

核心模式速查

组件模式

模式	使用场景
容器/展示组件	分离数据与 UI
复合组件	构建可组合的 API（Select、Menu）
Hooks	无需 HOC 即可共享有状态逻辑
Provider	避免全局数据的属性层层传递

状态管理

方案	使用场景
useState/useReducer	组件本地状态
Context	主题、身份验证、低频全局状态
Zustand/Jotai	简单的全局状态，样板代码极少
Redux Toolkit	复杂状态、时间旅行调试
React Query/SWR	服务端状态、缓存、后台刷新
XState	使用显式状态机处理复杂流程

性能要点

技术	影响
代码拆分	减少初始包体积
延迟加载	延后加载非关键内容
React.memo	避免不必要的重新渲染
useMemo/useCallback	保持引用稳定
虚拟列表	处理大型数据集

架构特征（选择 3–7 项）

特征	要思考的问题
可扩展性	并发用户有多少？增长率如何？
性能	可接受的 TTI 是多少？LCP 目标是多少？
可部署性	发布频率如何？是否需要独立部署？
可测试性	验证变更有多容易？
可维护性	预期使用寿命是多久？
模块化	需求变更频率如何？

应避免的反模式

反模式	问题	修复方法
属性层层传递	紧密耦合	使用 Context 或状态管理
巨型组件	职责过多	按关注点拆分
过早优化	缺乏依据地增加复杂性	先分析性能
共享可变状态	竞态条件、错误	使用不可变模式
单体包	初始加载缓慢	代码拆分
过度获取数据	浪费带宽	使用 GraphQL 或 BFF
默认将令牌存储在 LocalStorage 中	XSS 会导致账户被接管	优先使用 httpOnly Cookie + CSP（参见安全参考资料）
使用全局存储管理服务端数据	缓存失效难以处理	使用 React Query/SWR 管理服务端状态

性能预算

预算必须根据用户/设备进行校准，但以下是“默认快速”应用的良好起点：

指标	目标	需要改进
LCP	<2.5s	2.5–4s
INP	<200ms	200–500ms
CLS	<0.1	0.1–0.25
TTFB	<800ms	800ms–1.8s
路由 JS（初始）	<170KB gzip	<300KB gzip

来源

综合参考：

• Learning JavaScript Design Patterns（Osmani，2023）
• React in Depth（Barklund，2024）
• SPA Design and Architecture（Scott）
• Single Page Web Applications（Mikowski & Powell）
• Building Micro-Frontends（Mezzalira）
• Micro Frontends in Action（Geers）
• Responsible JavaScript（Wagner）
• High Performance Browser Networking（Grigorik）
• Web Performance in Action（Wagner）
• Frontend Architecture for Design Systems（Godbolt）
• Fundamentals of Software Architecture（Richards & Ford）
• Software Architecture: The Hard Parts（Ford 等）
• Patterns.dev