architect

Architect — 系统设计

在构建系统之前先规划结构。良好的架构会让一切更轻松。糟糕的架构则会让一切都得重写。

第 0 步：了解约束条件

设计之前，请回答：

1. 规模 — 100 位用户还是 100,000 位？这决定一切。
2. 团队规模 — 独立创始人还是 10 位工程师？团队越小，系统就越应简单。
3. 预算 — 自筹资金还是已获融资？这决定使用托管服务还是自行托管。
4. 时间线 — 2 周内交付 MVP，还是 3 个月内交付 v1？
5. 合规要求 — HIPAA、SOC 2、GDPR？这些会限制架构选择。

架构模式

模式	适用场景	应避免的场景
单体架构	工程师少于 10 人、单一产品、快速迭代	多个团队需要独立部署
模块化单体架构	团队不断壮大，希望划分边界但不增加基础设施成本	需要按服务独立扩展
微服务	20 位以上工程师、领域明确、需要独立扩展	团队较小、处于早期阶段、边界不明确
无服务器	事件驱动、流量突增、希望无需运维	长时间运行的进程、规模扩大后成本敏感
事件驱动	异步工作流、解耦系统、审计追踪	简单的 CRUD、实时性要求

默认选择： 在单体架构造成问题之前，始终使用单体架构。过早采用微服务是最常见的架构错误。

数据库选择

需求	数据库	原因
通用型、关系型	PostgreSQL	ACID、支持 JSON、扩展、生态系统
键值存储、缓存	Redis / Valkey	亚毫秒级读取、TTL、发布/订阅
文档存储、灵活的模式	MongoDB	快速原型开发、嵌套文档
全文搜索	PostgreSQL FTS 或 Meilisearch	Postgres 内置功能足够好，直到它不够用为止
时序数据	TimescaleDB（Postgres 扩展）	保持使用单一数据库引擎
图关系	PostgreSQL，配合递归 CTE	除非图是核心产品，否则不要引入 Neo4j
向量 / 嵌入	pgvector（Postgres 扩展）	同样，保持使用单一数据库

规则：

• 从 Postgres 开始。只有在 Postgres 无法胜任时，才添加专用数据库。
• 始终使用托管服务（Supabase、Neon、RDS）。不要自行管理数据库。
• 在有 DBA 之前只使用一个数据库引擎。两个数据库 = 两个问题。

项目结构

先识别技术栈。 在建议项目结构之前，检查 package.json、go.mod、Gemfile、pyproject.toml、pom.xml 或 Cargo.toml。将以下原则应用于项目使用的任何技术栈。

通用规则 — 适用于所有技术栈：

• 将功能代码放在一起。不要把一个功能分散到 8 个目录中。
• 服务包含业务逻辑。路由应保持精简——验证、调用服务、返回响应。
• 每个领域一个服务，而不是每个函数一个文件。

示例：TypeScript / Next.js

src/
├── app/                    # Next.js app router — pages and layouts
│   ├── (auth)/             # Route groups for auth pages
│   ├── (dashboard)/        # Route groups for app pages
│   └── api/                # API routes
├── lib/                    # Shared utilities, config, constants
│   ├── db/                 # Database client, schema, migrations
│   ├── auth/               # Auth config and helpers
│   └── utils/              # Pure utility functions
├── services/               # Business logic — one file per domain
├── components/             # React components
│   ├── ui/                 # Primitives (button, input, card)
│   └── features/           # Feature-specific composites
└── types/                  # Shared TypeScript types

示例：Python / FastAPI

src/
├── api/
│   ├── v1/                 # Versioned endpoints
│   └── deps.py             # Shared dependencies (auth, db session)
├── core/                   # Config, security, constants
├── models/                 # ORM models
├── schemas/                # Request/response schemas
├── services/               # Business logic — one file per domain
├── repositories/           # Data access layer
└── tests/
    ├── unit/
    └── integration/

示例：Go

cmd/
├── api/                    # Application entrypoint
internal/
├── handler/                # HTTP handlers (thin — validate + call service)
├── service/                # Business logic
├── repository/             # DB access layer
├── model/                  # Domain types
└── config/                 # Config loading
pkg/                        # Shared, importable packages

示例：Ruby on Rails

app/
├── controllers/            # Thin — params, call service, render
├── models/                 # ActiveRecord + domain logic
├── services/               # Complex business logic extracted from models
├── views/                  # Templates or JSON serializers
└── jobs/                   # Background jobs (Sidekiq)
config/
db/
├── migrate/                # Migrations
└── schema.rb

对于其他技术栈（Java/Spring、.NET、Rust、Elixir）：遵循相同原则——路由保持精简，服务处理业务逻辑，仓库负责数据访问，测试与被测代码放在一起。

API 设计

决策	默认选择
协议	CRUD 使用 REST，全栈类型安全使用 tRPC，只有在多个客户端需要不同数据结构时才使用 GraphQL
版本控制	URL 路径：/api/v1/ — 简单、明确
身份验证	在 Authorization 标头中使用 Bearer 令牌
分页	信息流使用基于游标的分页，管理表使用偏移量分页
错误	{ error: { code: "NOT_FOUND", message: "User not found" } }
速率限制	默认每分钟 100 个请求，身份验证端点设置更低的限制

缓存策略

层级	工具	TTL	使用场景
浏览器	Cache-Control headers	不固定	静态资源、API 响应
CDN	Cloudflare / Vercel Edge	1-60 分钟	公开页面、图片
应用	Redis / 内存	5-60 分钟	开销较大的查询、会话数据
数据库	物化视图	写入时刷新	聚合、仪表盘

规则：

• 缓存读取，而非写入。数据变更时使缓存失效。
• 从不使用缓存开始。测出瓶颈后再添加缓存。
• 每种缓存都需要失效策略。“设置 TTL，然后听天由命”总有行不通的时候。

扩展检查清单

只有遇到问题时才进行优化：

用户数	可能的瓶颈	解决方案
0-1K	无	不要优化
1K-10K	数据库查询	添加索引，优化 N+1 查询
10K-100K	数据库连接	连接池（PgBouncer）
100K-1M	读取吞吐量	添加 Redis 缓存层
1M+	写入吞吐量	只读副本、分片、写入队列

最佳架构是能够满足当前规模 + 10× 需求的最简单架构。