技能 Tech

技术栈

技术指导与栈选型:起点、可行替代方案、决策方法,以及面向新项目和新模块的提案模板。

概述

技术栈为每种项目类型给出一个默认推荐,作为日常工作的起点。触发分类器会判断何时这还不够:新项目或新服务、与现有技术栈不同领域的组件、技术栈迁移,或操作者的明确请求,都会产出一份技术栈提案,包含 2–3 个候选方案、明确的权衡取舍和一项推荐。L1 任务和同领域的日常工作会跳过此步骤;情况不明确时默认产出提案。由操作者做出选择,该选择会作为决策记录写入计划,并受不可变性契约约束。核心原则:简单优于复杂,性能优于便利,采用社区强大且被广泛采用的工具。

默认推荐(选型)

  • 静态落地页 — HTML、CSS、Tailwind、Alpine.js(可选)。不使用 SPA。
  • 静态多页站点 — PHP、HTML、Tailwind。SSR 模板。需要 Docker。
  • Web 前端(SEO) — Next.js、React、Tailwind、shadcn/ui、Vite、pnpm、Vitest、Playwright。
  • SPA / 仪表盘 — Vite、React 或 Vue、Tailwind、TanStack Query、Vitest。
  • 微服务 API — NestJS、Fastify、PostgreSQL、Prisma、Redis、NATS。
  • Python API — FastAPI、uvicorn、uv、ruff、pydantic、sqlalchemy、alembic、pytest。
  • AI/LLM — Python、FastAPI、uv、ruff、OpenAI/OpenRouter SDK、Redis。

每一行还列出了可行的替代方案和一项可验证的“何时重新考虑”测试;其余行涵盖高负载与网关 API、RAG 与搜索、实时、后台与事件驱动工作、媒体、monorepo、认证、原型设计以及 CLI 或系统工具。

推荐工具链

Python:uv(依赖管理)、ruff(lint + 格式化)、pytest(测试)。Node/TypeScript:pnpm、TypeScript、eslint + prettier、vitest、playwright 用于 E2E。这些是质量下限的默认值 — 偏离时需附一行理由。后端服务使用 Docker。

架构指导

这是指导而非强制要求:每条规则都附带理由,当理由不适用时你可以偏离。

  • HTML 足够时不要用 SPA
  • Node.js HTTP 默认使用 Fastify(替代方案:Hono、Express)
  • 默认缓存使用 Redis
  • 事件驱动系统使用 NATS 或 Kafka
  • PHP 仅用于 SSR/模板复用
  • 队列不是 WebSocket;WebRTC 仅用于媒体
  • 没有正当理由不使用冷门库

基础设施与备份

服务器备份使用 restic + Backblaze B2(原生后端、客户端加密、去重、快照)。数据库备份使用各引擎专用工具(pg_dump、mysqldump)通过管道传入 restic。

依赖版本策略

始终安装最新的稳定版本(适用时使用 LTS)。如果新的大版本有破坏性变更,应调整代码 — 不要降级。在脚手架搭建完成后以及每次添加依赖后,立即运行 pnpm outdated(或 uv pip list --outdated)。AI 幻觉防护:在配置文件中指定版本之前,通过 npm view 或 pip index versions 核实最新版本。