第3章：代码编写工程实践

核心价值: 一人维护全栈，最大的风险是"只有你自己懂的代码"。工程实践让 AI 可以接手你的代码，也让你 6 个月后还能看懂自己写的东西。

3.1 架构决策：简单 > 完美

一人公司的架构原则

原则 1：现在付出的复杂度，未来由你独自维护

Market Vault 的选择理由：

• FastAPI 单体 → 1 个容器，1 人可维护
• PostgreSQL → 不引入 MongoDB/ElasticSearch，SQL 足够
• Redis 纯缓存 → 不用作消息队列（目前规模不需要）
• Bunny CDN → 不自建存储，运营成本外包

3.2 代码分层：让 AI 在正确的层工作

标准 FastAPI 分层（Market Vault 模式）

app/
├── api/v1/         ← 路由层：只做参数验证
│   └── snapshots.py
├── services/       ← 业务逻辑：所有 DB 写入/查询
│   └── snapshot_service.py
├── models/         ← SQLAlchemy ORM 模型
│   └── snapshot.py
├── schemas/        ← Pydantic 请求/响应 schema
│   └── snapshot.py
└── core/           ← 横切关注点（安全、限流、CDN）
    ├── security.py
    └── limits.py

3.3 数据库：正确使用 SQLAlchemy 2 (async)

关键模式

正确的 async ORM 查询：

# ✅ 基础查询
result = await db.execute(
    select(User).where(User.email == email)
)
user = result.scalar_one_or_none()

# ✅ 关联查询（避免 N+1）
result = await db.execute(
    select(Snapshot)
    .options(selectinload(Snapshot.ads))
    .where(Snapshot.project_id == project_id)
)

3.4 测试策略：一人团队的最低标准

测试优先级金字塔

        ┌─────────┐
        │  E2E    │  ← 最少（贵、慢），只覆盖核心流程
        ├─────────┤
        │  集成   │  ← 重点！API + DB 整体流程
        ├─────────┤
        │  单元   │  ← 仅对纯函数/复杂算法
        └─────────┘

3.5 CI/CD：一人团队的自动化

GitHub Actions 最小配置

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install -r backend/requirements.txt
      - run: cd backend && make lint
      - run: cd backend && make test

3.6 监控与可观测性

最小监控栈

小结与行动项

本章学到:

1. 架构以"维护成本"为核心指标选型
2. 严格的代码分层让 AI 在正确的地方工作
3. 测试金字塔：集成测试是一人团队的主力
4. CI/CD 自动化让你不害怕频繁发布
5. 监控从 Sentry 开始，5 分钟接入

行动项:

• 检查代码是否违反分层规则
• 补充集成测试
• 接入 Sentry

上一章 → 第2章：AI Agent 协作开发
下一章 → 第4章：安全边界设计