anubhavg-icpl/vibe

脚手架

为常见项目类型提供项目脚手架模板和样板代码生成，并包含最佳实践默认值。

项目类型决策树

你在构建什么？
│
├─ API / 后端服务
│  ├─ REST API
│  │  ├─ Python → FastAPI（异步, OpenAPI 自动文档）
│  │  ├─ Node.js → Express 或 Fastify（Fastify 追求性能）
│  │  ├─ Go → Gin（符合人体工程学）或 Echo（中间件丰富）
│  │  └─ Rust → Axum（tower 生态, 异步优先）
│  ├─ GraphQL API
│  │  ├─ Python → Strawberry + FastAPI
│  │  ├─ Node.js → Apollo Server 或 Pothos + Yoga
│  │  ├─ Go → gqlgen（编码优先）
│  │  └─ Rust → async-graphql + Axum
│  └─ gRPC 服务
│     ├─ Python → grpcio + protobuf
│     ├─ Go → google.golang.org/grpc
│     └─ Rust → tonic
│
├─ Web 应用
│  ├─ 全栈带 SSR
│  │  ├─ React 生态 → Next.js 14+（App Router）
│  │  ├─ Vue 生态 → Nuxt 3
│  │  ├─ Svelte 生态 → SvelteKit
│  │  └─ 内容密集/多框架 → Astro
│  ├─ SPA（仅客户端）
│  │  ├─ React → Vite + React + React Router
│  │  ├─ Vue → Vite + Vue + Vue Router
│  │  └─ Svelte → Vite + Svelte + svelte-routing
│  └─ 静态站点
│     ├─ 博客/文档 → Astro 或 VitePress
│     └─ 营销/落地页 → Astro 或 Next.js（静态导出）
│
├─ CLI 工具
│  ├─ Python → Typer（简单）或 Click（复杂）
│  ├─ Node.js → Commander + Inquirer
│  ├─ Go → Cobra + Viper
│  └─ Rust → Clap（derive API）
│
├─ 库 / 包
│  ├─ npm 包 → TypeScript + tsup + Vitest
│  ├─ PyPI 包 → uv + pyproject.toml + pytest
│  ├─ Go 模块 → go mod init + go test
│  └─ Rust crate → cargo init --lib + cargo test
│
└─ 单体仓库
   ├─ JavaScript/TypeScript → Turborepo + pnpm workspaces
   ├─ 全栈 JS → Nx
   ├─ Go → Go workspaces (go.work)
   ├─ Rust → Cargo workspaces
   └─ Python → uv workspaces 或 hatch

堆栈选择矩阵

项目类型	语言	框架	数据库	ORM/查询	部署目标
REST API	Python	FastAPI	PostgreSQL	SQLAlchemy + Alembic	Docker / AWS ECS
REST API	Node.js	Fastify	PostgreSQL	Prisma 或 Drizzle	Docker / Vercel
REST API	Go	Gin	PostgreSQL	sqlx (原生) 或 GORM	Docker / Fly.io
REST API	Rust	Axum	PostgreSQL	sqlx	Docker / Fly.io
Web 应用	TypeScript	Next.js 14+	PostgreSQL	Prisma 或 Drizzle	Vercel / Docker
Web 应用	TypeScript	Nuxt 3	PostgreSQL	Prisma	Vercel / Netlify
Web 应用	TypeScript	Astro	SQLite / 无	Drizzle	Cloudflare / Netlify
CLI 工具	Python	Typer	SQLite	sqlite3 stdlib	PyPI
CLI 工具	Go	Cobra	SQLite / BoltDB	sqlx	GitHub Releases
CLI 工具	Rust	Clap	SQLite	rusqlite	crates.io
库	TypeScript	tsup	不适用	不适用	npm
库	Python	hatch/uv	不适用	不适用	PyPI

快速脚手架命令

Python (API)

# FastAPI with uv
mkdir my-api && cd my-api
uv init --python 3.12
uv add fastapi uvicorn sqlalchemy alembic psycopg2-binary pydantic-settings
uv add --dev pytest pytest-asyncio httpx ruff mypy

Node.js (Web 应用)

# Next.js 14+
npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"

# Vite + React
npm create vite@latest my-app -- --template react-ts

Go (API)

mkdir my-api && cd my-api
go mod init github.com/user/my-api
go get github.com/gin-gonic/gin
go get github.com/jmoiron/sqlx
go get github.com/lib/pq

Rust (CLI)

cargo init my-cli
cd my-cli
cargo add clap --features derive
cargo add serde --features derive
cargo add anyhow tokio --features tokio/full

单体仓库 (Turborepo)

npx create-turbo@latest my-monorepo
# 或手动创建：
mkdir my-monorepo && cd my-monorepo
npm init -y
npm install turbo --save-dev
mkdir -p apps/web apps/api packages/shared

API 项目模板

目录结构 (FastAPI 示例)

my-api/
├── src/
│   └── my_api/
│       ├── __init__.py
│       ├── main.py              # FastAPI 应用, 生命周期, 中间件
│       ├── config.py            # pydantic-settings 配置
│       ├── database.py          # SQLAlchemy 引擎, 会话
│       ├── dependencies.py      # 共享 FastAPI 依赖
│       ├── routers/
│       │   ├── __init__.py
│       │   ├── health.py        # 健康检查端点
│       │   └── users.py         # 用户 CRUD 端点
│       ├── models/
│       │   ├── __init__.py
│       │   └── user.py          # SQLAlchemy 模型
│       ├── schemas/
│       │   ├── __init__.py
│       │   └── user.py          # Pydantic 请求/响应模式
│       └── services/
│           ├── __init__.py
│           └── user.py          # 业务逻辑
├── alembic/
│   ├── alembic.ini
│   ├── env.py
│   └── versions/
├── tests/
│   ├── conftest.py              # 夹具：测试数据库, 客户端, 工厂
│   ├── test_health.py
│   └── test_users.py
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── .gitignore
└── .dockerignore

目录结构 (Express/Fastify 示例)

my-api/
├── src/
│   ├── index.ts                 # 入口点, 服务器启动
│   ├── app.ts                   # Express/Fastify 应用设置
│   ├── config.ts                # 环境配置，带 zod 验证
│   ├── database.ts              # Prisma 客户端或 Drizzle 配置
│   ├── middleware/
│   │   ├── auth.ts
│   │   ├── error-handler.ts
│   │   └── request-logger.ts
│   ├── routes/
│   │   ├── health.ts
│   │   └── users.ts
│   ├── services/
│   │   └── user.service.ts
│   └── types/
│       └── index.ts
├── prisma/
│   └── schema.prisma
├── tests/
│   ├── setup.ts
│   └── routes/
│       └── users.test.ts
├── package.json
├── tsconfig.json
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── .gitignore

Web 应用项目模板

目录结构 (Next.js App Router)

my-app/
├── src/
│   ├── app/
│   │   ├── layout.tsx           # 根布局
│   │   ├── page.tsx             # 首页
│   │   ├── loading.tsx          # 全局加载 UI
│   │   ├── error.tsx            # 全局错误边界
│   │   ├── not-found.tsx        # 404 页面
│   │   ├── globals.css          # 全局样式 + Tailwind
│   │   ├── (auth)/
│   │   │   ├── login/page.tsx
│   │   │   └── register/page.tsx
│   │   ├── dashboard/
│   │   │   ├── layout.tsx
│   │   │   └── page.tsx
│   │   └── api/
│   │       └── health/route.ts
│   ├── components/
│   │   ├── ui/                  # 可复用的基础组件
│   │   └── features/            # 功能特定组件
│   ├── lib/
│   │   ├── db.ts                # 数据库客户端
│   │   ├── auth.ts              # 认证辅助函数
│   │   └── utils.ts             # 共享工具
│   └── types/
│       └── index.ts
├── public/
│   └── favicon.ico
├── tests/
│   ├── setup.ts
│   └── components/
├── next.config.ts
├── tailwind.config.ts
├── tsconfig.json
├── package.json
├── .env.local.example
└── .gitignore

CLI 工具项目模板

目录结构 (Python / Typer)

my-cli/
├── src/
│   └── my_cli/
│       ├── __init__.py
│       ├── __main__.py          # python -m my_cli 入口
│       ├── cli.py               # Typer 应用, 命令组
│       ├── commands/
│       │   ├── __init__.py
│       │   ├── init.py          # my-cli init
│       │   └── run.py           # my-cli run
│       ├── config.py            # 配置文件加载 (TOML/YAML)
│       └── utils.py
├── tests/
│   ├── conftest.py
│   └── test_commands.py
├── pyproject.toml               # [project.scripts] 入口点
├── .gitignore
└── README.md

目录结构 (Go / Cobra)

my-cli/
├── cmd/
│   ├── root.go                  # 根命令, 全局标志
│   ├── init.go                  # my-cli init
│   └── run.go                   # my-cli run
├── internal/
│   ├── config/
│   │   └── config.go            # Viper 配置加载
│   └── runner/
│       └── runner.go            # 核心逻辑
├── main.go                      # 入口点, 调用 cmd.Execute()
├── go.mod
├── go.sum
├── Makefile
└── .gitignore

库项目模板

目录结构 (npm 包)

my-lib/
├── src/
│   ├── index.ts                 # 公共 API 导出
│   ├── core.ts                  # 核心实现
│   └── types.ts                 # 公共类型定义
├── tests/
│   └── core.test.ts
├── package.json                 # "type": "module", exports 映射
├── tsconfig.json                # declaration: true, declarationMap: true
├── tsup.config.ts               # 构建配置: cjs + esm
├── vitest.config.ts
├── .npmignore
├── .gitignore
├── CHANGELOG.md
└── LICENSE

目录结构 (PyPI 包)

my-lib/
├── src/
│   └── my_lib/
│       ├── __init__.py          # 公共 API, __version__
│       ├── core.py
│       └── py.typed             # PEP 561 标记
├── tests/
│   ├── conftest.py
│   └── test_core.py
├── pyproject.toml               # 构建系统, 元数据, 工具配置
├── .gitignore
├── CHANGELOG.md
└── LICENSE

单体仓库模板

Turborepo + pnpm Workspaces

my-monorepo/
├── apps/
│   ├── web/                     # Next.js 前端
│   │   ├── src/
│   │   ├── package.json         # 依赖 @repo/shared
│   │   └── tsconfig.json        # 继承 ../../tsconfig.base.json
│   └── api/                     # Fastify 后端
│       ├── src/
│       ├── package.json
│       └── tsconfig.json
├── packages/
│   ├── shared/                  # 共享类型, 工具, 验证器
│   │   ├── src/
│   │   ├── package.json         # "name": "@repo/shared"
│   │   └── tsconfig.json
│   ├── ui/                      # 共享 React 组件
│   │   ├── src/
│   │   └── package.json         # "name": "@repo/ui"
│   └── config/                  # 共享配置
│       ├── eslint/
│       ├── typescript/
│       └── package.json
├── turbo.json                   # 管道: build, test, lint
├── pnpm-workspace.yaml          # packages: ["apps/*", "packages/*"]
├── package.json                 # 根 devDeps: turbo
├── tsconfig.base.json           # 共享 TypeScript 配置
├── .gitignore
└── .npmrc

Cargo Workspaces (Rust)

my-workspace/
├── crates/
│   ├── my-core/                 # 核心库
│   │   ├── src/lib.rs
│   │   └── Cargo.toml
│   ├── my-cli/                  # CLI 二进制
│   │   ├── src/main.rs
│   │   └── Cargo.toml           # 依赖 my-core
│   └── my-server/               # API 二进制
│       ├── src/main.rs
│       └── Cargo.toml
├── Cargo.toml                   # [workspace] members = ["crates/*"]
├── Cargo.lock
├── .gitignore
└── rust-toolchain.toml

常见附加项检查清单

项目设置完成？添加这些：
│
├─ 版本控制
│  ├─ [ ] .gitignore（特定语言）
│  ├─ [ ] .gitattributes（换行符, 二进制文件）
│  └─ [ ] 分支保护规则
│
├─ CI/CD
│  ├─ [ ] GitHub Actions 工作流（PR 时测试, 合并时部署）
│  ├─ [ ] 矩阵测试（操作系统, 运行时版本）
│  └─ [ ] 发布自动化
│
├─ Docker
│  ├─ [ ] 多阶段 Dockerfile
│  ├─ [ ] docker-compose.yml（应用 + 数据库 + 缓存）
│  ├─ [ ] .dockerignore
│  └─ [ ] 健康检查端点
│
├─ 代码质量
│  ├─ [ ] 代码检查工具（ESLint, Ruff, golangci-lint, Clippy）
│  ├─ [ ] 代码格式化工具（Prettier, Black/Ruff, gofmt, rustfmt）
│  ├─ [ ] 预提交钩子（Husky, pre-commit）
│  └─ [ ] 类型检查（TypeScript strict, mypy, go vet）
│
├─ 测试
│  ├─ [ ] 测试框架已配置（Vitest, pytest, go test）
│  ├─ [ ] 覆盖率报告
│  ├─ [ ] 测试数据库设置
│  └─ [ ] CI 测试管道
│
├─ 编辑器
│  ├─ [ ] .editorconfig
│  ├─ [ ] .vscode/settings.json
│  └─ [ ] .vscode/extensions.json
│
└─ 文档
   ├─ [ ] README.md（项目描述, 设置, 使用）
   ├─ [ ] CONTRIBUTING.md
   └─ [ ] API 文档（OpenAPI, godoc, rustdoc）

配置文件模板

.editorconfig（通用）

root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.{py,rs}]
indent_size = 4

[*.go]
indent_style = tab

[*.md]
trim_trailing_whitespace = false

[Makefile]
indent_style = tab

pyproject.toml (Python)

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.12"

[tool.ruff]
target-version = "py312"
line-length = 88

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"

[tool.mypy]
strict = true

tsconfig.json (TypeScript - 严格模式)

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

常见陷阱

陷阱	原因	预防措施
使用了错误的 .gitignore	使用了通用模板, 缺少特定语言的条目	针对你的技术栈使用 gitignore.io 或 GitHub 的模板
忘记了 .env.example	团队成员不知道需要哪些环境变量	在项目开始时创建包含所有变量（值为空）的 .env.example
未提交锁文件	不同环境间的依赖版本不一致	提交 package-lock.json, uv.lock, go.sum, Cargo.lock
代码中硬编码了端口/主机	本地运行正常, 但在 Docker/云环境中出错	始终从环境变量读取, 并设置合理的默认值
测试耦合到真实数据库	测试在无数据库运行时会失败, CI 设置复杂	对单元测试使用测试容器或内存 SQLite
缺少健康检查端点	部署编排器无法验证服务是否就绪	添加 /health 端点并……

[翻译部分已截断]