create-hazejs 0.0.0-stage → 0.1.2

package/templates/api/app/validate/auth.ts

@@ -0,0 +1,20 @@
+import * as v from 'valibot'
+
+export const RegisterSchema = v.object({
+  name: v.pipe(v.string('名称必填'), v.trim(), v.minLength(1, '名称不能为空')),
+  email: v.pipe(v.string('邮箱必填'), v.email('邮箱格式不正确')),
+  password: v.pipe(v.string('密码必填'), v.minLength(8, '密码至少 8 位')),
+})
+
+export const LoginSchema = v.object({
+  email: v.pipe(v.string('邮箱必填'), v.email('邮箱格式不正确')),
+  password: v.pipe(v.string('密码必填'), v.minLength(1, '密码必填')),
+})
+
+export const AvatarSchema = v.object({
+  avatar: v.pipe(
+    v.file('请选择图片'),
+    v.mimeType(['image/png', 'image/jpeg', 'image/webp'], '只支持 png / jpeg / webp'),
+    v.maxSize(2 * 1024 * 1024, '图片不能超过 2MB'),
+  ),
+})

package/templates/api/app/validate/greeting.ts

@@ -0,0 +1,5 @@
+import * as v from 'valibot'
+
+export const GreetSchema = v.object({
+  name: v.pipe(v.string('name 必填'), v.trim(), v.minLength(1, 'name 不能为空'), v.maxLength(50, 'name 最多 50 个字符')),
+})

package/templates/api/app/validate/user.ts

@@ -0,0 +1,12 @@
+import * as v from 'valibot'
+
+export const UserIdParams = v.object({
+  id: v.pipe(v.string(), v.transform(Number), v.integer('用户 ID 必须是整数')),
+})
+
+export const CreateUserSchema = v.object({
+  name: v.pipe(v.string('名称必填'), v.trim(), v.minLength(1, '名称不能为空')),
+  email: v.pipe(v.string('邮箱必填'), v.email('邮箱格式不正确')),
+})
+
+export const UpdateUserSchema = v.partial(CreateUserSchema)

package/templates/api/config/app.ts

@@ -0,0 +1,7 @@
+import { defineConfig, env } from '@hazejs/core'
+
+// 读取环境变量时使用函数形式，确保在 .env 加载之后求值。
+// app.debug 默认仅在开发环境开启（错误页、堆栈）；如需强制开启，可在此设置 debug: env('APP_DEBUG', false)
+export default defineConfig(() => ({
+  name: env('APP_NAME', '{{name}}'),
+}))

package/templates/api/config/auth.ts

@@ -0,0 +1,23 @@
+import { defineAuthConfig, env } from '@hazejs/core'
+import { modelUserProvider } from '@hazejs/orm'
+import { User } from '~/app/model/User'
+
+/**
+ * 认证：guards 决定“怎么认”（jwt：Authorization: Bearer；session：会话 Cookie），
+ * providers 决定“用户从哪来”。路由上用 .middleware('auth') / 'auth:web,api' 保护。
+ */
+export default defineAuthConfig(() => ({
+  default: 'api',
+  guards: {
+    // 密钥默认为 APP_KEY；也可配置 algorithm: 'ES256' 与 privateKey / publicKey
+    api: {
+      driver: 'jwt',
+      provider: 'users',
+      expiresIn: env('JWT_TTL', '2h'),
+    },
+    // 浏览器同源场景可改用 session：{ driver: 'session', provider: 'users' }
+  },
+  providers: {
+    users: modelUserProvider(() => User, { username: 'email', password: 'password' }),
+  },
+}))

package/templates/api/config/cache.ts

@@ -0,0 +1,23 @@
+import { defineCacheConfig, env } from '@hazejs/core'
+
+/**
+ * 缓存：Cache.remember('key', '10m', () => ...)、Cache.increment()、Cache.lock()。
+ * 多实例部署时设置 CACHE_STORE=redis（REDIS_URL），限流（config/throttle.ts）与 Session 也会共享计数 / 数据。
+ */
+export default defineCacheConfig(() => ({
+  default: env('CACHE_STORE', 'memory'),
+  // 多个应用共用一个 Redis 时用前缀区分
+  prefix: env('CACHE_PREFIX', '{{name}}:'),
+  stores: {
+    memory: { driver: 'memory' },
+    // 需要安装 ioredis
+    redis: {
+      driver: 'redis',
+      url: env('REDIS_URL', 'redis://127.0.0.1:6379'),
+    },
+    // Edge / Serverless：Upstash（HTTP，需要安装 @upstash/redis）
+    // upstash: { driver: 'upstash', url: env('UPSTASH_REDIS_REST_URL', ''), token: env('UPSTASH_REDIS_REST_TOKEN', '') },
+    // Cloudflare Workers：KV 绑定（最终一致，适合缓存与 Session，不适合精确限流）
+    // kv: { driver: 'kv', binding: 'CACHE' },
+  },
+}))

package/templates/api/config/cors.ts

@@ -0,0 +1,11 @@
+import { defineCorsConfig, env } from '@hazejs/core'
+
+// 跨域：CORS_ORIGIN 为逗号分隔的来源列表，默认允许任意来源（不携带 Cookie）
+export default defineCorsConfig(() => {
+  const origin = env('CORS_ORIGIN', '*')
+  return {
+    origin: origin === '*'
+      ? '*'
+      : origin.split(',').map(item => item.trim()),
+  }
+})

package/templates/api/config/database.ts

@@ -0,0 +1,17 @@
+import { env } from '@hazejs/core'
+import { defineDatabaseConfig } from '@hazejs/orm'
+
+/**
+ * 数据库连接。driver：sqlite（libsql）| turso（HTTP）| d1（Cloudflare）| postgres | pglite | mysql
+ * 切换数据库：安装对应驱动（postgres / mysql2），修改 driver 与 url，并改用对应方言的表结构。
+ */
+export default defineDatabaseConfig(() => ({
+  default: 'main',
+  connections: {
+    main: {
+      driver: 'sqlite',
+      url: env('DATABASE_URL', 'file:./data/app.db'),
+      logging: env('DB_LOGGING', false),
+    },
+  },
+}))

package/templates/api/config/filesystem.ts

@@ -0,0 +1,32 @@
+import { defineFilesystemConfig, env } from '@hazejs/core'
+
+/**
+ * 文件存储：Storage.put('reports/a.csv', csv)、Storage.disk('public').putFile('avatars', file)、
+ * 上传文件 `await file.store('avatars', 'public')`。
+ * public 磁盘的文件经 /storage/<path> 访问；私有文件用 Storage.temporaryUrl(path, '10m') 生成签名链接。
+ */
+export default defineFilesystemConfig(() => ({
+  default: env('FILESYSTEM_DISK', 'local'),
+  disks: {
+    local: { driver: 'local', root: 'storage/app' },
+    public: {
+      driver: 'local',
+      root: 'storage/app/public',
+      url: '/storage',
+      serve: true,
+    },
+    // AWS S3 与 S3 兼容服务（R2 的 S3 接口、MinIO、RustFS 等），需要 pnpm add @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
+    s3: {
+      driver: 's3',
+      bucket: env('S3_BUCKET', ''),
+      region: env('S3_REGION', 'us-east-1'),
+      endpoint: env('S3_ENDPOINT', '') || undefined,
+      accessKeyId: env('S3_ACCESS_KEY_ID', ''),
+      secretAccessKey: env('S3_SECRET_ACCESS_KEY', ''),
+      // 公共读的桶 / CDN 地址；私有桶用 temporaryUrl() 预签名
+      url: env('S3_URL', '') || undefined,
+    },
+    // Cloudflare Workers：R2 绑定（wrangler.json 的 r2_buckets）
+    // r2: { driver: 'r2', binding: 'BUCKET', url: 'https://files.example.com' },
+  },
+}))

package/templates/api/config/mail.ts

@@ -0,0 +1,31 @@
+import { defineMailConfig, env } from '@hazejs/core'
+
+/**
+ * 邮件：await Mail.to(user.email).send(WelcomeMail, { name })，排队发送用 .queue() / .later('10m', ...)。
+ * 开发环境默认 log（只写日志）；本地查看真实邮件可运行 Mailpit 并设置 MAIL_MAILER=smtp MAIL_PORT=1025。
+ */
+export default defineMailConfig(() => ({
+  default: env('MAIL_MAILER', 'log'),
+  from: {
+    address: env('MAIL_FROM_ADDRESS', 'hello@example.com'),
+    name: env('MAIL_FROM_NAME', '{{name}}'),
+  },
+  mailers: {
+    // 需要 pnpm add nodemailer（Cloudflare Workers 不支持 SMTP，请用下面的 HTTP 接口驱动）
+    smtp: {
+      driver: 'smtp',
+      host: env('MAIL_HOST', '127.0.0.1'),
+      port: env('MAIL_PORT', 1025),
+      username: env('MAIL_USERNAME', ''),
+      password: env('MAIL_PASSWORD', ''),
+    },
+    resend: {
+      driver: 'resend',
+      key: env('RESEND_API_KEY', ''),
+    },
+    // postmark: { driver: 'postmark', token: env('POSTMARK_TOKEN', '') },
+    // mailgun: { driver: 'mailgun', key: env('MAILGUN_SECRET', ''), domain: env('MAILGUN_DOMAIN', '') },
+    // 需要 pnpm add @aws-sdk/client-sesv2
+    // ses: { driver: 'ses', region: env('AWS_REGION', 'us-east-1') },
+  },
+}))

package/templates/api/config/middleware.ts

@@ -0,0 +1,10 @@
+import { defineMiddlewareConfig } from '@hazejs/core'
+
+// 请求 ID（x-request-id）与访问日志由框架内置，无需注册
+// 内置中间件：cors、secureHeaders、compress、throttle:60,60、bodyLimit:10mb、session、auth / auth:api、guest
+export default defineMiddlewareConfig({
+  // 全局中间件，按顺序作用于所有请求
+  global: ['cors', 'secureHeaders', 'compress'],
+  // 别名，在路由中按名引用：.middleware('auth')；用 haze make:middleware 生成
+  alias: {},
+})

package/templates/api/config/queue.ts

@@ -0,0 +1,21 @@
+import { defineQueueConfig, env } from '@hazejs/core'
+
+/**
+ * 队列：app/job 下的任务，await SendWelcomeEmail.dispatch({ userId })。
+ * memory 在本进程消费（开发 / 单实例）；生产多实例设置 QUEUE_CONNECTION=redis（需要 pnpm add bullmq ioredis），
+ * 并运行 haze queue:work（构建产物：node dist/…/worker.mjs queue）。
+ */
+export default defineQueueConfig(() => ({
+  default: env('QUEUE_CONNECTION', 'memory'),
+  connections: {
+    memory: { driver: 'memory', concurrency: 2 },
+    sync: { driver: 'sync' },
+    redis: {
+      driver: 'redis',
+      url: env('REDIS_URL', 'redis://127.0.0.1:6379'),
+      queues: ['default'],
+    },
+    // Cloudflare Workers：Queues 绑定（wrangler.json 的 queues.producers / consumers）
+    // cloudflare: { driver: 'cloudflare', binding: 'QUEUE' },
+  },
+}))

package/templates/api/config/throttle.ts

@@ -0,0 +1,12 @@
+import { defineThrottleConfig, env } from '@hazejs/core'
+
+// 限流计数存在 config/cache.ts 的存储中（CACHE_STORE=redis 时多实例共享）
+export default defineThrottleConfig(() => ({
+  store: env('CACHE_STORE', 'memory'),
+  // 命名规则：.middleware('throttle:api')
+  limiters: {
+    api: { max: 60, window: '1m' },
+    // Cloudflare Workers：使用 Rate Limiting 绑定（wrangler.json 的 ratelimits）
+    // api: { max: 60, window: '1m', binding: 'API_RATE_LIMITER' },
+  },
+}))

package/templates/api/config/websocket.ts

@@ -0,0 +1,12 @@
+import { defineWebSocketConfig, env } from '@hazejs/core'
+
+// 多实例部署时设置 WS_BROADCAST=redis：Socket.publish / peer.publish 经 Redis 转发到所有实例（需要 ioredis）
+export default defineWebSocketConfig(() => env('WS_BROADCAST', '') === 'redis'
+  ? {
+      broadcast: {
+        driver: 'redis',
+        url: env('REDIS_URL', 'redis://127.0.0.1:6379'),
+        channel: '{{name}}:ws',
+      },
+    }
+  : {})

package/templates/api/database/migrations/0000_create_users.sql

@@ -0,0 +1,9 @@
+CREATE TABLE `users` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`name` text NOT NULL,
+	`email` text NOT NULL,
+	`created_at` integer,
+	`updated_at` integer
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `users_email_unique` ON `users` (`email`);

package/templates/api/database/migrations/0001_add_user_password.sql

@@ -0,0 +1 @@
+ALTER TABLE `users` ADD `password` text;

package/templates/api/database/migrations/0002_add_user_role.sql

@@ -0,0 +1 @@
+ALTER TABLE `users` ADD `role` text DEFAULT 'member' NOT NULL;

package/templates/api/database/migrations/meta/0000_snapshot.json

@@ -0,0 +1,71 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "1b28388a-9186-40de-9d67-bb08f562b58c",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "users": {
+      "name": "users",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "users_email_unique": {
+          "name": "users_email_unique",
+          "columns": [
+            "email"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/templates/api/database/migrations/meta/0001_snapshot.json

@@ -0,0 +1,78 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "1138ad71-fa8c-4b78-a94a-5dbce374d676",
+  "prevId": "1b28388a-9186-40de-9d67-bb08f562b58c",
+  "tables": {
+    "users": {
+      "name": "users",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password": {
+          "name": "password",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "users_email_unique": {
+          "name": "users_email_unique",
+          "columns": [
+            "email"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/templates/api/database/migrations/meta/0002_snapshot.json

@@ -0,0 +1,86 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "d41d3fc5-5742-40b2-9f99-4f4870f40ebf",
+  "prevId": "1138ad71-fa8c-4b78-a94a-5dbce374d676",
+  "tables": {
+    "users": {
+      "name": "users",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "password": {
+          "name": "password",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'member'"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "users_email_unique": {
+          "name": "users_email_unique",
+          "columns": [
+            "email"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/templates/api/database/migrations/meta/_journal.json

@@ -0,0 +1,27 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1793072281689,
+      "tag": "0000_create_users",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1793084099573,
+      "tag": "0001_add_user_password",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1793086076027,
+      "tag": "0002_add_user_role",
+      "breakpoints": true
+    }
+  ]
+}

package/templates/api/database/schema/users.ts

@@ -0,0 +1,17 @@
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+
+// 表结构定义（drizzle）：此文件只依赖 drizzle-orm，不要使用 ~ 别名（drizzle-kit 需要直接读取）
+// 修改后运行 haze db:generate 生成迁移，再 haze db:migrate
+export const users = sqliteTable('users', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  name: text('name').notNull(),
+  email: text('email').notNull().unique(),
+  // 密码哈希（Hash.make()），通过 /api/auth/register 注册的用户才有
+  password: text('password'),
+  // 角色：admin 可以管理所有用户（app/policy/UserPolicy.ts）
+  role: text('role', {
+    enum: ['member', 'admin'],
+  }).notNull().default('member'),
+  createdAt: integer('created_at', { mode: 'timestamp' }),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }),
+})

package/templates/api/database/seeders/01-users.ts

@@ -0,0 +1,15 @@
+import { Hash } from '@hazejs/core'
+import { User } from '~/app/model/User'
+
+/** haze db:seed：按文件名顺序执行 database/seeders 下的文件 */
+export default async function seed(): Promise<void> {
+  if (await User.where('email', 'admin@example.com').exists())
+    return
+  // 开发用账号，上线前请修改密码
+  await User.create({
+    name: 'Admin',
+    email: 'admin@example.com',
+    password: await Hash.make('password'),
+    role: 'admin',
+  })
+}

package/templates/api/haze.config.ts

@@ -0,0 +1,5 @@
+import { defineHazeConfig } from '@hazejs/vite'
+
+export default defineHazeConfig({
+  port: 3000,
+})

package/templates/api/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "{{name}}",
+  "type": "module",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "haze dev",
+    "build": "haze build",
+    "start": "haze start",
+    "preview": "haze preview",
+    "queue": "haze queue:work",
+    "schedule": "haze schedule:work",
+    "test": "haze test",
+    "routes": "haze route:list",
+    "typecheck": "tsc --noEmit",
+    "typegen": "haze typegen",
+    "db:generate": "haze db:generate",
+    "db:migrate": "haze db:migrate",
+    "db:seed": "haze db:seed"
+  },
+  "dependencies": {
+    "@hazejs/core": "{{version}}",
+    "@hazejs/orm": "{{version}}",
+    "@libsql/client": "^0.18.0",
+    "drizzle-orm": "^0.45.4",
+    "valibot": "^1.1.0"
+  },
+  "devDependencies": {
+    "@hazejs/cli": "{{version}}",
+    "@hazejs/testing": "{{version}}",
+    "@hazejs/vite": "{{version}}",
+    "@types/node": "^24.0.0",
+    "drizzle-kit": "^0.31.11",
+    "typescript": "~6.0.3",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
+  }
+}

package/templates/api/route/api.ts

@@ -0,0 +1,22 @@
+import { defineRoutes } from '@hazejs/core'
+import { AuthController } from '~/app/controller/AuthController'
+import { GreetingController } from '~/app/controller/GreetingController'
+import { UserController } from '~/app/controller/UserController'
+import { GreetSchema } from '~/app/validate/greeting'
+import { UserIdParams } from '~/app/validate/user'
+
+export default defineRoutes((r) => {
+  r.group({ prefix: '/api', as: 'api.' }, (r) => {
+    r.get('/hello', [GreetingController, 'index']).name('hello')
+    r.post('/hello', [GreetingController, 'store']).validate({ body: GreetSchema })
+    r.resource('/users', UserController).validateMember({ params: UserIdParams })
+
+    r.group({ prefix: '/auth', as: 'auth.' }, (r) => {
+      r.post('/register', [AuthController, 'register']).name('register')
+      // 登录限流：同一 IP 每分钟最多 10 次
+      r.post('/login', [AuthController, 'login']).middleware('throttle:10,60').name('login')
+      r.get('/me', [AuthController, 'me']).middleware('auth').name('me')
+      r.post('/avatar', [AuthController, 'avatar']).middleware(['auth', 'bodyLimit:3mb']).name('avatar')
+    })
+  })
+})

package/templates/api/route/ws.ts

@@ -0,0 +1,18 @@
+import { defineRoutes } from '@hazejs/core'
+
+/**
+ * WebSocket：ws://<host>/api/ws。升级请求同样经过中间件，需要登录时加 .middleware('auth')。
+ * 服务端任意位置用 Socket.publish('users', data) 推送给订阅者（多实例见 config/websocket.ts）
+ */
+export default defineRoutes((r) => {
+  r.ws('/api/ws', {
+    open(peer) {
+      peer.subscribe('users')
+      peer.send(JSON.stringify({ type: 'connected' }))
+    },
+    message(peer, message) {
+      if (message.text() === 'ping')
+        peer.send(JSON.stringify({ type: 'pong' }))
+    },
+  })
+})