@stdex/create 0.0.0-stage → 1.1.0

package/templates/miniprogram/variables.json

@@ -0,0 +1,11 @@
+[
+  {
+    "name": "appid",
+    "describe": "小程序 appid"
+  },
+  {
+    "name": "appname",
+    "describe": "小程序名称",
+    "defaults": "测试小程序"
+  }
+]

package/templates/service/.env

@@ -0,0 +1 @@
+DB_URL=postgresql://localhost

package/templates/service/README.md

@@ -0,0 +1,64 @@
+服务端项目
+
+# 架构设计
+
+```yaml
+Schema: 定义业务实体
+Controller: 封装业务逻辑，包括对业务实体的查询和操作
+Task: 执行定期任务
+Route: 处理请求（检查传参、格式化响应内容、触发相应的业务逻辑...）
+Module: 通用组件或对某一特定功能的封装
+```
+
+代码中：
+
+- `prisma/` 对应 `Schema`
+- `src/controllers/` 对应 `Controller`
+- `src/tasks/` 对应 `Task`
+- `src/routes/` 对应 `Route`
+- `src/` 下的其他内容都是 `Module`
+
+routes 和 controller 都会验证数据有效性。但分工有所区别：
+
+- routes 主要验证“格式”上的有效性
+- controller 负责验证“业务逻辑”上的有效性，它假定使用者传入的数据格式一定是合法的。
+
+---
+
+# Prisma ORM 适配
+
+## 约定
+
+1. prisma 定义（schema、migrations...）放在 `prisma/`，此为 prisma 默认支持的位置。
+2. prisma 生成的 client 代码放在 `src/prisma` 以便于引用。
+3. `prisma` 命令会从环境变量或 `.env` 文件中获取数据库连接参数。
+   因此此项目设计为用 `.env` 文件维护配置，使得代码和 `prisma` 命令都能方便地读取到需要的配置值。
+
+## 本地开发
+
+1. 每次修改 schema 后，执行 `prisma db push`，把修改同步到数据库中。此操作会顺便重新生成 client 代码。
+   或者执行 `prisma generate` 只生成 client 代码，不同步数据库（针对本机开发没有对应的数据库或不希望写入数据库的情况）。
+2. 每次修改 TypedSQL 后，执行 `prisma generate --sql` 更新 SQL 类型定义。
+3. 开发完成后，执行 `prisma migrate dev` 来生成一个 `migration`。
+   注意：因为之前执行了 `prisma db push`，生成 migrate 时会因为表结构冲突要求重置整个数据库、清除数据，相关问题：<https://github.com/prisma/prisma/discussions/16141>。
+   目前能想到的解决办法是备份数据（不备份表结构），等生成 migrations 后再导入回来。
+
+前两项操作已定义成 `pnpm db-push` 或 `pnpm db-generate`，
+第三项已定义成 `pnpm db-save`。
+
+## 生产环境运行
+
+初始化或每次数据库有变动时：
+
+1. 执行 `pnpm prisma generate` 生成 client 代码。
+2. 执行 `pnpm prisma migrate deploy` 来应用 migrations。
+
+此操作已整合成 `pnpm db-deploy` 命令。
+
+---
+
+# 缓存使用流程
+
+1. 确定要缓存的内容，通过 `getCacheInstance()` 建立缓存管理器。
+2. 读取缓存时，若对应内容不存在，获取数据并存入缓存
+3. 相关数据更新时，清除缓存，待下一次读取时重新写入

package/templates/service/_gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+node_modules/
+dist/
+logs/
+.env

package/templates/service/eslint.config.js

@@ -0,0 +1,2 @@
+import configs from '@stdex/presets-eslint-node'
+export default configs

package/templates/service/package.json

@@ -0,0 +1,44 @@
+{
+  "private": true,
+  "name": "project",
+  "description": "服务端项目",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "build": "rm -rf dist && tsc-with-alias --project tsconfig.build.json",
+    "watch": "rm -rf dist && tsc-with-alias --watch --project tsconfig.build.json",
+    "dev": "rm -rf dist && tsc-with-alias --watch --project tsconfig.build.json --nodemon=dist/index.js",
+    "start": "node dist/index.js",
+    "lint": "tsc --noEmit && eslint './src/'",
+    "db-generate": "prisma generate --sql",
+    "db-push": "prisma db push",
+    "db-save": "prisma migrate dev",
+    "db-deploy": "prisma generate && prisma migrate deploy"
+  },
+  "dependencies": {
+    "@stdex/utils": "latest",
+    "@prisma/adapter-pg": "latest",
+    "@prisma/client": "latest",
+    "dayjs": "latest",
+    "dotenv": "latest",
+    "lodash": "latest",
+    "pg": "latest",
+    "redis": "latest",
+    "starlight-server": "latest"
+  },
+  "devDependencies": {
+    "@stdex/presets-eslint-node": "latest",
+    "@stdex/presets-prettier": "latest",
+    "@stdex/presets-typescript": "latest",
+    "@types/lodash": "latest",
+    "@types/node": "latest",
+    "@types/pg": "latest",
+    "concurrently": "latest",
+    "eslint": "latest",
+    "nodemon": "latest",
+    "prisma": "latest",
+    "tsc-alias": "latest",
+    "typescript": "^6.0.3"
+  },
+  "prettier": "@stdex/presets-prettier/prettierrc"
+}

package/templates/service/prisma/schema.prisma

@@ -0,0 +1,40 @@
+// 数据库设计约定见 README.md
+
+// -------------------------------
+// 数据库配置
+// -------------------------------
+
+datasource db {
+  provider   = "postgresql"
+  extensions = [citext]
+}
+
+generator client {
+  provider        = "prisma-client"
+  previewFeatures = ["postgresqlExtensions", "typedSql"]
+  output          = "../src/prisma/"
+}
+
+// -------------------------------
+// 业务实体
+// -------------------------------
+
+model School {
+  id   String @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
+  name String @unique @db.Citext
+
+  students Student[]
+
+  @@map("schools")
+}
+
+model Student {
+  id         String    @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
+  name       String    @db.Citext
+  deleteTime DateTime? @map("delete_time") @db.Timestamptz()
+
+  school   School @relation(fields: [schoolId], references: [id])
+  schoolId String @map("school_id") @db.Uuid
+
+  @@map("students")
+}

package/templates/service/prisma/sql/demoTypedSql.sql

@@ -0,0 +1 @@
+SELECT * FROM schools;

package/templates/service/prisma.config.ts

@@ -0,0 +1,12 @@
+import 'dotenv/config'
+import { defineConfig } from 'prisma/config'
+
+export default defineConfig({
+  schema: 'prisma/schema.prisma',
+  migrations: {
+    path: 'prisma/migrations',
+  },
+  datasource: {
+    url: process.env.DB_URL,
+  },
+})

package/templates/service/setup.js

@@ -0,0 +1,4 @@
+export async function setup({ command }) {
+  await command('npx prisma generate')
+  console.log('注意：TypedSQL 需正确配置数据库连接参数后手动初始化')
+}

package/templates/service/src/cache.ts

@@ -0,0 +1,28 @@
+/**
+ * 维护基于 redis 的数据缓存
+ */
+import { type CacheOptions, Cache, initRedisLogging } from '@stdex/utils/env-service/redis-cache.js'
+import { createClient, type RedisClientType } from 'redis'
+import config from '@/config.js'
+import { rootLogger } from '@/logger.js'
+
+export const redis: RedisClientType = createClient({
+  url: config.REDIS_URL,
+  disableOfflineQueue: true, // 若在 Redis 连接断开时执行命令，立刻失败，而不是等待重新连接
+})
+
+export async function initRedis() {
+  initRedisLogging(redis)
+  await redis.connect()
+}
+
+/**
+ * 生成管理某项缓存的实例
+ * 使用规范见 README.md 里的“缓存使用流程”
+ */
+export function getCacheInstance<T>(topic: string, options?: Partial<CacheOptions>) {
+  return new Cache<T>(redis, config.REDIS_KEY_PREFIX + topic, {
+    logger: rootLogger.getChild('cache'),
+    ...(options ?? {}),
+  })
+}

package/templates/service/src/config.ts

@@ -0,0 +1,49 @@
+import path from 'node:path'
+import { getDirectoryPath } from '@stdex/utils/env-node/index.js'
+import { EnvReader } from '@stdex/utils/env-service/index.js'
+
+/**
+ * 环境信息
+ */
+const dirpath = getDirectoryPath(import.meta.url)
+export const appRoot = path.resolve(dirpath, '../')
+
+/**
+ * 业务常量
+ */
+export const constants = {
+  // 此处定义业务常量
+}
+
+/**
+ * 设置
+ * 通过 .env 文件覆盖设置
+ */
+const envReader = new EnvReader({
+  path: [path.join(appRoot, '.env')],
+})
+const config = envReader.batchGet({
+  // ---------- 基础设置 ----------
+
+  // 是否开启调试模式，会影响日志记录
+  DEBUG: false,
+
+  // 是否额外开启 Prisma 的调试日志（仅限 DEBUG 为 true 时生效）
+  DB_DEBUG: false,
+
+  // 监听端口
+  PORT: 8000,
+
+  // 日志文件存放路径
+  LOGS_DIR: path.join(appRoot, 'logs'),
+
+  // ---------- 服务连接 ----------
+
+  // postgresql://[[username][:password]@][host][:port][/db-name]
+  DB_URL: '',
+
+  // redis[s]://[[username][:password]@][host][:port][/db-number]
+  REDIS_URL: '',
+  REDIS_KEY_PREFIX: '',
+})
+export default config

package/templates/service/src/controllers/common.ts

@@ -0,0 +1,43 @@
+import {
+  type ControllersFrom,
+  type AnyController,
+  Controller,
+  initializeControllers,
+} from '@stdex/utils/env-service/index.js'
+import { getTransactionContextedPrismaClient, type AppPrismaClient } from '@/database.js'
+import { type Logger, rootLogger } from '@/logger.js'
+
+export interface Context {
+  /**
+   * controller 会绑定一个由 getTransactionContextedPrismaClient() 返回的 PrismaClient，它会自动关联当前进行的事务。
+   * 应始终使用它而不是全局的 PrismaClient 以保证在正确的事务内执行操作。
+   */
+  db: AppPrismaClient
+
+  baseLogger: Logger
+}
+
+export class AppController<
+  AllControllers extends Record<string, AnyController<Context>>,
+> extends Controller<Context, AllControllers> {
+  protected readonly db: AppPrismaClient
+  protected readonly logger: Logger
+
+  constructor(controllers: AllControllers, context: Context, name?: string) {
+    super(controllers, context, name)
+    this.db = context.db
+    this.logger = context.baseLogger.getChild(this.name)
+  }
+}
+
+export type { ControllersFrom }
+
+export function initializeAppControllers<T extends Record<string, unknown>>(
+  controllerClasses: T,
+  db?: AppPrismaClient,
+  baseLogger?: Logger,
+) {
+  db ??= getTransactionContextedPrismaClient()
+  baseLogger ??= rootLogger.getChild('controller')
+  return initializeControllers<Context, T>(controllerClasses, { db, baseLogger })
+}

package/templates/service/src/controllers/demo-school.ts

@@ -0,0 +1,7 @@
+import { AppController, type Controllers } from './index.js'
+
+export class DemoSchoolController extends AppController<Controllers> {
+  async list() {
+    return this.db.school.findMany({})
+  }
+}

package/templates/service/src/controllers/demo-student.ts

@@ -0,0 +1,7 @@
+import { AppController, type Controllers } from './index.js'
+
+export class DemoStudentController extends AppController<Controllers> {
+  async list() {
+    return this.db.student.findMany({})
+  }
+}

package/templates/service/src/controllers/index.ts

@@ -0,0 +1,15 @@
+import {
+  AppController,
+  initializeAppControllers,
+  type ControllersFrom,
+  type Context,
+} from './common.js'
+import { DemoSchoolController } from './demo-school.js'
+import { DemoStudentController } from './demo-student.js'
+
+export { AppController, initializeAppControllers }
+export type Controllers = ControllersFrom<Context, typeof controllerClasses>
+export const controllerClasses = {
+  student: DemoStudentController,
+  school: DemoSchoolController,
+}

package/templates/service/src/database.ts

@@ -0,0 +1,52 @@
+import {
+  getPrismaLoggingOptions,
+  adaptPrismaLogging,
+  exists,
+  findAndCount,
+  softDelete,
+  withTransaction,
+  adaptPrismaDebugLogging,
+  getTransactionContextedPrismaClient as rawGetTransactionContextedPrismaClient,
+  type GetPrismaClientInTransaction,
+} from '@stdex/utils/env-service/prisma/index.js'
+import { PrismaPg } from '@prisma/adapter-pg'
+import config from '@/config.js'
+import { rootLogger } from '@/logger.js'
+import { PrismaClient } from '@/prisma/client.js'
+
+/**
+ * 导出相关类型和工具函数
+ */
+export * from '@/prisma/client.js'
+export type AppPrismaClient = typeof prisma
+export type PrismaClientInTransaction = GetPrismaClientInTransaction<AppPrismaClient>
+
+const logger = rootLogger.getChild('prisma')
+
+/**
+ * 初始化基础 PrismaClient 实例
+ */
+if (config.DEBUG && config.DB_DEBUG) {
+  adaptPrismaDebugLogging(logger)
+}
+
+const adapter = new PrismaPg({ connectionString: config.DB_URL })
+export const barePrisma = new PrismaClient({
+  adapter,
+  ...getPrismaLoggingOptions(config.DEBUG ? 'debug' : 'info'),
+})
+
+adaptPrismaLogging(barePrisma, rootLogger.getChild('prisma'))
+
+/**
+ * 应用扩展
+ */
+export const prisma = barePrisma
+  .$extends(softDelete)
+  .$extends(withTransaction)
+  .$extends(exists)
+  .$extends(findAndCount)
+
+export function getTransactionContextedPrismaClient() {
+  return rawGetTransactionContextedPrismaClient(prisma)
+}

package/templates/service/src/index.ts

@@ -0,0 +1,15 @@
+import { startHTTPServer } from 'starlight-server'
+import { initRedis } from '@/cache.js'
+import config from '@/config.js'
+import { rootLogger } from '@/logger.js'
+import { router } from '@/routes/index.js'
+
+import './tasks/index.js'
+
+await initRedis()
+
+startHTTPServer({
+  handler: router.handle,
+  logger: rootLogger.getChild('http'),
+  port: config.PORT,
+})

package/templates/service/src/logger.ts

@@ -0,0 +1,11 @@
+import { logger as rootLogger } from '@stdex/utils/env-node/logging/index.js'
+import { Logger, initLogger } from 'starlight-server'
+import config from '@/config.js'
+
+export { Logger, rootLogger }
+
+initLogger(rootLogger, {
+  level: config.DEBUG ? 'debug' : 'info',
+  debugLib: '*',
+  file: { dir: config.LOGS_DIR },
+})

package/templates/service/src/routes/demo-school.ts

@@ -0,0 +1,9 @@
+import { router } from '@/routes/router.js'
+
+router.register({
+  path: '/schools',
+  async handler({ db, response }) {
+    const schools = db.school.findMany({})
+    response.success(schools)
+  },
+})

package/templates/service/src/routes/index.ts

@@ -0,0 +1,3 @@
+export * from './router.js'
+
+import './demo-school.js'

package/templates/service/src/routes/router.ts

@@ -0,0 +1,42 @@
+import { Router } from 'starlight-server'
+import {
+  initializeAppControllers,
+  controllerClasses,
+  type Controllers,
+} from '@/controllers/index.js'
+import { getTransactionContextedPrismaClient, type AppPrismaClient } from '@/database.js'
+import { rootLogger } from '@/logger.js'
+export const logger = rootLogger.getChild('API')
+
+/**
+ * -----------------------------
+ * 初始化、自定义 router
+ * -----------------------------
+ */
+
+declare module 'starlight-server' {
+  interface Context {
+    db: AppPrismaClient
+    controllers: Controllers
+  }
+}
+
+export const router = new Router()
+router.setCors(true)
+router.setExecutor(async (basicContext, route) => {
+  // 初始化业务对象
+  // 此为和 controllers 里共用的 contexted prisma client。
+  // 应始终使用它而不是全局的 PrismaClient 以保证在正确的事务内执行操作。
+  const db = getTransactionContextedPrismaClient()
+  const controllers = initializeAppControllers(controllerClasses, db)
+
+  // 初始化 route context 并调用 route handler
+  await route.handler({ ...basicContext, db, controllers })
+})
+
+router.register({
+  path: '/check-health',
+  handler({ response }) {
+    response.text('ok')
+  },
+})

package/templates/service/src/tasks/common.ts

@@ -0,0 +1,24 @@
+import { TaskManager } from '@stdex/utils/env-service/index.js'
+import {
+  type Controllers,
+  controllerClasses,
+  initializeAppControllers,
+} from '@/controllers/index.js'
+import { getTransactionContextedPrismaClient, type AppPrismaClient } from '@/database.js'
+
+interface Context {
+  db: AppPrismaClient
+  controllers: Controllers
+}
+class AppTaskManager extends TaskManager<Context> {
+  getContext(name: string) {
+    const db = getTransactionContextedPrismaClient()
+    const controllersLogger = this.baseLogger.getChild(name).getChild('controllers')
+    const controllers = initializeAppControllers(controllerClasses, db, controllersLogger)
+    return {
+      db,
+      controllers,
+    }
+  }
+}
+export const tasks = new AppTaskManager()

package/templates/service/src/tasks/demo-school.ts

@@ -0,0 +1,6 @@
+import { tasks } from './common.js'
+
+tasks.run('check-schools', 1000 * 60, async ({ db }, logger) => {
+  const count = await db.school.count({})
+  logger.info(`学校数量：${count}`)
+})

package/templates/service/src/tasks/index.ts

@@ -0,0 +1 @@
+import './demo-school.js'

package/templates/service/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./node_modules/@stdex/presets-typescript/tsconfig-build",
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["./src/"]
+}

package/templates/service/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./node_modules/@stdex/presets-typescript/tsconfig-build",
+  "compilerOptions": {
+    "rootDir": "./",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["./src/", "./prisma.config.ts"]
+}

package/templates/site/_gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+node_modules/
+dist/

package/templates/site/_pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+onlyBuiltDependencies:
+  - '@swc/core'
+  - esbuild
+  - unrs-resolver

package/templates/site/eslint.config.js

@@ -0,0 +1,19 @@
+import configs from '@stdex/presets-eslint-react'
+export default [
+  ...configs,
+  {
+    rules: {
+      // 适配 Emotion CSS
+      'react/no-unknown-property': ['error', { ignore: ['css'] }], // 适配 Emotion CSS
+
+      // 适配 @stdex/utils 中的 useAsyncEffect
+      'ts-react-hooks/exhaustive-deps': [
+        'warn',
+        {
+          additionalHooks: '(useAsyncEffect)',
+          allowAsyncHooks: '(useAsyncEffect)',
+        },
+      ],
+    },
+  },
+]

package/templates/site/package.json

@@ -0,0 +1,38 @@
+{
+  "private": true,
+  "name": "project",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "tsc --noEmit && eslint './src/'"
+  },
+  "prettier": "@stdex/presets-prettier/prettierrc",
+  "dependencies": {
+    "@stdex/utils": "latest",
+    "@ant-design/cssinjs": "latest",
+    "@ant-design/icons": "latest",
+    "@emotion/react": "latest",
+    "antd": "latest",
+    "dayjs": "latest",
+    "lodash": "latest",
+    "react": "latest",
+    "react-dom": "latest",
+    "react-router": "latest"
+  },
+  "devDependencies": {
+    "@stdex/presets-eslint-react": "latest",
+    "@stdex/presets-prettier": "latest",
+    "@stdex/presets-typescript": "latest",
+    "@swc/plugin-emotion": "latest",
+    "@types/lodash": "latest",
+    "@types/node": "latest",
+    "@types/react": "latest",
+    "@types/react-dom": "latest",
+    "@vitejs/plugin-react-swc": "latest",
+    "eslint": "latest",
+    "vite": "latest",
+    "vite-plugin-svgr": "latest"
+  }
+}

package/templates/site/src/app/header.tsx

@@ -0,0 +1,31 @@
+import ImageLogo from '@/assets/logo.png'
+import { DevStatus } from '@/components/DevStatus'
+
+export function AppHeader() {
+  return <div css={s.wrap}>
+    <img css={s.logo} src={ImageLogo} />
+    <div css={s.siteName}>演示项目</div>
+    <DevStatus />
+  </div>
+}
+
+const s = {
+  wrap: css`
+    align-items: center;
+    display: flex;
+    padding: 8px 24px;
+  `,
+
+  logo: css`
+    height: 42px;
+    width: 42px;
+    margin-right: 20px;
+  `,
+
+  siteName: css`
+    flex: 1;
+    font-size: 16px;
+    letter-spacing: 1px;
+    white-space: nowrap;
+  `,
+}