| name | architecture |
| description | Web全栈架构设计,包括技术选型、模块划分、数据流设计 |
架构设计技能
触发条件
- 新项目启动
- 重大功能需要架构设计
- 技术选型决策
- 重构现有架构
Web 全栈架构模式
分层架构
┌─────────────────────────────────┐
│ 表现层 (Presentation) │
│ React / Next.js / API Routes │
├─────────────────────────────────┤
│ 业务层 (Business) │
│ Services / Use Cases │
├─────────────────────────────────┤
│ 数据层 (Data) │
│ Repository / ORM / Cache │
├─────────────────────────────────┤
│ 基础设施层 (Infra) │
│ DB / Queue / Storage / Auth │
└─────────────────────────────────┘
模块化组织(Feature-based)
src/
├── features/
│ ├── auth/ # 认证模块
│ │ ├── components/
│ │ ├── hooks/
│ │ ├── services/
│ │ ├── types/
│ │ └── index.ts # 公共 API
│ ├── user/ # 用户模块
│ └── order/ # 订单模块
├── shared/ # 共享代码
│ ├── components/
│ ├── hooks/
│ ├── utils/
│ └── types/
└── app/ # 应用入口
技术选型决策树
前端
- SSR/SSG 需求?→ Next.js 14+(App Router)
- 内容站点?→ Astro(零 JS 默认)
- 纯 SPA?→ Vite + React
- 轻量级?→ Preact / Solid
后端
- 全栈框架?→ Next.js API Routes / Remix
- 独立 API?→ Hono(优先) / Fastify / Express
- Edge 部署?→ Hono(原生 Edge Runtime 支持)
- 微服务?→ 各服务独立选型
数据库
- 关系型为主?→ PostgreSQL
- 嵌入式/轻量?→ SQLite
- 文档型?→ MongoDB
- 缓存?→ Redis
ORM / 查询构建器
- 类型安全 + 迁移?→ Prisma
- 轻量 + SQL-like?→ Drizzle
- 类型安全 + 灵活?→ Kysely
- 原生 SQL?→ pg / better-sqlite3
设计模式
常用模式
- Repository Pattern:隔离数据访问层
- Service Pattern:封装业务逻辑
- Middleware Pattern:请求处理管道
- Observer Pattern:事件驱动
- Factory Pattern:对象创建
避免的模式
- 过度抽象:不需要模式时别硬套
- 单例滥用:优先依赖注入
- God Object:一个类/模块做太多事
输出要求
架构文档必须包含:
- 系统概述
- 架构图(文字或 Mermaid)
- 技术栈及选型理由
- 模块划分及职责
- 数据流描述
- 关键决策及理由
- 风险和缓解方案