65 lines
3.0 KiB
Markdown
65 lines
3.0 KiB
Markdown
# fullstack-starter
|
||
|
||
强约定的单二进制全栈 starter。Bun + TanStack Start（React 19 SSR）+ ORPC（契约优先）+ Drizzle + PostgreSQL，编译为单个可执行文件部署。
|
||
|
||
> Agent 笔记与非显而易见的不变量见 [AGENTS.md](./AGENTS.md)。改结构前先读。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
bun install
|
||
bun run db:push # 开发期：同步 schema 不生成 migration 文件
|
||
bun run dev # http://localhost:3000
|
||
```
|
||
|
||
RPC 入口：`/api/rpc` · OpenAPI 文档：`/api/docs` · Spec：`/api/spec.json` · 存活探针：`/health`。
|
||
|
||
## 脚本
|
||
|
||
| 命令 | 作用 |
|
||
| --- | --- |
|
||
| `bun run dev` | Vite 开发服务器，3000 端口（strict） |
|
||
| `bun run build` | 构建到 `.output/` |
|
||
| `bun run compile` | `bun build --compile` 生成单二进制 `out/server-<target>` |
|
||
| `bun run cli <cmd>` | 源码态运行 CLI 子命令（`serve`、`migrate`） |
|
||
| `bun run typecheck` | `tsc --noEmit` |
|
||
| `bun run test` | `bun test`（同目录 `*.test.ts`） |
|
||
| `bun run fix` | Biome lint + format + 整理 imports |
|
||
| `bun run db:push` | 仅开发期 schema 同步（不写 migration 文件） |
|
||
| `bun run db:generate` | 把 SQL migration 写到 `./drizzle/` 并重生 `migrations.gen.ts` |
|
||
| `bun run db:embed` | 仅从 `./drizzle/` 重生 `src/server/db/migrations.gen.ts`（手改 SQL 后用） |
|
||
| `bun run db:migrate` | 通过 drizzle-kit 本地应用 migration（开发便利） |
|
||
| `bun run db:studio` | Drizzle Studio |
|
||
|
||
跨平台编译：`bun run compile:{linux,darwin,windows}[:arch]`。
|
||
|
||
## 新增一个功能（以 `post` 为例）
|
||
|
||
契约优先、纯增量。按以下顺序建/改文件：
|
||
|
||
1. `src/server/db/schema/post.ts` — 定义 `postTable`，展开 `...generatedFields`。
|
||
2. `src/server/db/schema/index.ts` — `export * from './post'`。
|
||
3. `src/server/api/contracts/post.contract.ts` — 通过 `drizzle-zod` 从表派生 Zod schema。
|
||
4. `src/server/api/contracts/index.ts` — 把 `post` 加进 `contract` 对象。
|
||
5. `src/server/api/routers/post.router.ts` — 实现 `os.post.*.handler(...)`。
|
||
6. `src/server/api/routers/index.ts` — 把 `post` 加进 `router` 对象。
|
||
7. `src/client/queries/post.ts` — 导出 `useInvalidatePosts`（或更细粒度 helper），用于失效受影响的 list key。
|
||
8. `src/routes/<page>.tsx` — 用 `useSuspenseQuery` + loader `ensureQueryData`；mutation 的 `onSuccess` 调用上一步的 helper。
|
||
9. `bun run db:generate` — 写 SQL migration 到 `./drizzle/` 并嵌入 `src/server/db/migrations.gen.ts`。
|
||
|
||
## 部署
|
||
|
||
永远 **先 migrate 再 serve**。Migration 已嵌入二进制，二进制是你唯一发布的产物。
|
||
|
||
```bash
|
||
./server migrate # 用 $DATABASE_URL 应用嵌入式 migration
|
||
./server # 启动 HTTP 服务器（默认子命令）
|
||
```
|
||
|
||
`compose.yaml` 把这个模式编排了出来：一次性 `migrate` 服务，`app` 通过 `service_completed_successfully` 等它完成。Kubernetes 上：把 `./server migrate` 放进 initContainer 或 Helm `pre-upgrade` Job。
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|