Cloudflare Workers 应用 — 上下文包

An API and web application running entirely on Cloudflare Workers — no Node.js
server, no container. The HTTP router is Hono. Persistent state uses Cloudflare
D1 (SQLite at the edge) for relational data, KV for session/cache, and R2 for
file storage. Deployed and configured via Wrangler. TypeScript compiled with
esbuild through Wrangler's bundler.

Cloudflare Workers (V8 isolates — NOT Node.js)
Hono v4 (lightweight router, runs on Workers)
Cloudflare D1 (SQLite — accessed via env.DB binding)
Cloudflare KV (key-value — accessed via env.KV binding)
Cloudflare R2 (object storage — accessed via env.BUCKET binding)
Drizzle ORM with drizzle-orm/d1 adapter
TypeScript (strict)
Wrangler v3 (CLI: dev, deploy, d1, kv, r2)

src/
  index.ts            # Worker entry point — exports default { fetch }
  routes/             # Hono route handlers, one file per resource
  middleware/         # Auth, CORS, rate-limit middleware
  lib/
    db.ts             # Drizzle D1 client factory (receives env.DB)
    schema.ts         # Drizzle table definitions
    kv.ts             # KV helpers (typed get/put wrappers)
    r2.ts             # R2 helpers (upload, signed URL, delete)
  types/
    env.d.ts          # Cloudflare Env interface with all bindings typed
migrations/           # D1 SQL migrations (generated by drizzle-kit)
wrangler.toml         # Worker config — bindings, routes, compatibility date
drizzle.config.ts

- The Workers runtime is NOT Node.js. Never import Node built-ins (fs, path,
  crypto from "node:crypto" is allowed but most others are not).
- All bindings (D1, KV, R2, secrets) are accessed via the typed Env interface
  — never use global variables or process.env.
- D1 queries use Drizzle ORM. Raw SQL is only acceptable in migrations.
- KV is eventually consistent — do not use it as a lock or transaction.
- Secrets are set with `wrangler secret put SECRET_NAME`, never in wrangler.toml.
- Hono routes return Response objects or use c.json() / c.text() helpers.
- Wrangler compatibility_date must stay at its current pinned value unless
  explicitly upgrading and testing all affected APIs.
- D1 schema changes require: `npx drizzle-kit generate` then
  `wrangler d1 migrations apply DB --remote`.

- Do not use setTimeout, setInterval, or long-lived connections — Workers have
  a 30-second CPU time limit per request.
- Do not spawn child processes or access the file system.
- Do not import packages that depend on Node.js internals without confirming
  they have a Workers-compatible build.
- Do not add environment variables via wrangler.toml [vars] for secrets —
  use `wrangler secret put` instead.
- Do not change compatibility_date without updating compatibility_flags and
  running the full test suite.
- D1 does not support all SQLite features — avoid triggers, virtual tables,
  and RETURNING on UPDATE in older compatibility dates.
- Workers have a 1 MB script size limit (after compression). Keep dependencies
  minimal; check bundle size with `wrangler deploy --dry-run`.

# Cloudflare Workers App
Runtime: Cloudflare Workers (V8 isolates, not Node.js)
Router: Hono v4
Database: D1 via Drizzle ORM (src/lib/db.ts, src/lib/schema.ts)
Cache/Session: KV (src/lib/kv.ts)
File storage: R2 (src/lib/r2.ts)
Config: wrangler.toml — all bindings declared here
Secrets: wrangler secret put (never wrangler.toml)
Deploy: wrangler deploy
Dev: wrangler dev (local D1 + KV emulation)