From c6027590a7aa3dd69cceaa6ff82ddbdbc6b8acfc Mon Sep 17 00:00:00 2001 From: imbytecat Date: Sat, 25 Apr 2026 15:30:36 +0800 Subject: [PATCH] =?UTF-8?q?docs(readme):=20=E5=85=A8=E6=96=87=E4=B8=AD?= =?UTF-8?q?=E6=96=87=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 保持原结构与技术准确性，仅做语言切换。技术术语（RPC、OpenAPI、migrate、Drizzle Studio 等）保留英文。 --- README.md | 68 +++++++++++++++++++++++++++---------------------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 9895afa..61d89ed 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,63 @@ # fullstack-starter -Opinionated single-binary fullstack starter. Bun + TanStack Start (React 19 SSR) + ORPC (contract-first) + Drizzle + PostgreSQL, deployed as one compiled executable. +强约定的单二进制全栈 starter。Bun + TanStack Start（React 19 SSR）+ ORPC（契约优先）+ Drizzle + PostgreSQL，编译为单个可执行文件部署。 -> Agent notes and non-obvious invariants live in [AGENTS.md](./AGENTS.md). Read it before making structural changes. +> Agent 笔记与非显而易见的不变量见 [AGENTS.md](./AGENTS.md)。改结构前先读。 -## Quick start +## 快速开始 ```bash cp .env.example .env bun install -bun run db:push # dev: sync schema without migration files +bun run db:push # 开发期：同步 schema 不生成 migration 文件 bun run dev # http://localhost:3000 ``` -RPC endpoint: `/api/rpc` · OpenAPI docs: `/api/docs` · Spec: `/api/spec.json` · Liveness: `/health`. +RPC 入口：`/api/rpc` · OpenAPI 文档：`/api/docs` · Spec：`/api/spec.json` · 存活探针：`/health`。 -## Scripts +## 脚本 -| Command | What it does | +| 命令 | 作用 | | --- | --- | -| `bun run dev` | Vite dev server on port 3000 (strict) | -| `bun run build` | Build to `.output/` | -| `bun run compile` | Single-binary `out/server-` via `bun build --compile` | -| `bun run cli ` | Run a CLI subcommand in source (`serve`, `migrate`) | +| `bun run dev` | Vite 开发服务器，3000 端口（strict） | +| `bun run build` | 构建到 `.output/` | +| `bun run compile` | `bun build --compile` 生成单二进制 `out/server-` | +| `bun run cli ` | 源码态运行 CLI 子命令（`serve`、`migrate`） | | `bun run typecheck` | `tsc --noEmit` | -| `bun run test` | `bun test` (colocated `*.test.ts`) | -| `bun run fix` | Biome lint + format + organize imports | -| `bun run db:push` | Dev-only schema sync (no migration files) | -| `bun run db:generate` | Write SQL migrations to `./drizzle` and regenerate `migrations.gen.ts` | -| `bun run db:embed` | Regenerate `src/server/db/migrations.gen.ts` from `./drizzle` (run if you hand-edit migrations) | -| `bun run db:migrate` | Apply migrations locally via drizzle-kit (dev convenience) | +| `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 | -Cross-compile: `bun run compile:{linux,darwin,windows}[:arch]`. +跨平台编译：`bun run compile:{linux,darwin,windows}[:arch]`。 -## Add a feature (e.g. `post`) +## 新增一个功能（以 `post` 为例） -Contract-first, additive. Create or touch files in this order: +契约优先、纯增量。按以下顺序建/改文件： -1. `src/server/db/schema/post.ts` — define `postTable`, spread `...generatedFields`. -2. `src/server/db/schema/index.ts` — `export * from './post'`. -3. `src/server/api/contracts/post.contract.ts` — derive Zod from the table via `drizzle-zod`. -4. `src/server/api/contracts/index.ts` — add `post` to the `contract` object. -5. `src/server/api/routers/post.router.ts` — implement `os.post.*.handler(...)`. -6. `src/server/api/routers/index.ts` — add `post` to the `router` object. -7. `src/client/queries/post.ts` — export `useInvalidatePosts` (or finer-grained helpers) for affected list keys. -8. `src/routes/.tsx` — UI with `useSuspenseQuery` + loader `ensureQueryData`; call the helper from mutation `onSuccess`. -9. `bun run db:generate` — emit SQL migrations to `./drizzle` and embed them into `src/server/db/migrations.gen.ts`. +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/.tsx` — 用 `useSuspenseQuery` + loader `ensureQueryData`；mutation 的 `onSuccess` 调用上一步的 helper。 +9. `bun run db:generate` — 写 SQL migration 到 `./drizzle/` 并嵌入 `src/server/db/migrations.gen.ts`。 -## Deploy +## 部署 -Always **migrate-then-serve**. Migrations are embedded in the binary; the binary is the only artifact you ship. +永远 **先 migrate 再 serve**。Migration 已嵌入二进制，二进制是你唯一发布的产物。 ```bash -./server migrate # applies embedded migrations against $DATABASE_URL -./server # starts HTTP server (default subcommand) +./server migrate # 用 $DATABASE_URL 应用嵌入式 migration +./server # 启动 HTTP 服务器（默认子命令） ``` -`compose.yaml` models the pattern with a one-shot `migrate` service that `app` depends on (`service_completed_successfully`). On Kubernetes: run `./server migrate` as an initContainer or Helm `pre-upgrade` Job. +`compose.yaml` 把这个模式编排了出来：一次性 `migrate` 服务，`app` 通过 `service_completed_successfully` 等它完成。Kubernetes 上：把 `./server migrate` 放进 initContainer 或 Helm `pre-upgrade` Job。 ```bash docker compose up --build