@yuer678/create-kb 0.3.0

package/templates/api/README.md

@@ -0,0 +1,50 @@
+# {{projectName}}-api
+
+Express 5 + TypeScript + Zod 的参考后端服务。
+
+> 本目录的 `src/` 与 `test/` 由 `scripts/sync-api-template.mjs` 从 **`packages/api`**（`@yuer678/kb-api`）
+> 自动生成，请勿直接修改；需要调整请改 `packages/api` 的源码后运行 `pnpm sync:api-template`。
+> 只有 `src/index.ts`（启动入口）是模板自带的。
+
+## 快速开始
+
+```bash
+pnpm install
+pnpm dev        # 开发模式（热重载），http://localhost:3000
+pnpm test       # 运行测试（vitest + supertest）
+```
+
+端口默认 `3000`，可用环境变量 `PORT` 覆盖。
+
+## 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/` | 列出可用接口 |
+| GET | `/health` · `/api/health` | 健康检查（带前缀/不带前缀都有，方便容器探活） |
+| GET | `/api/users` | 用户列表：`?page=&pageSize=&keyword=&sortBy=&order=` |
+| GET | `/api/users/:id` | 用户详情 |
+| POST | `/api/users` | 创建用户（zod 校验） |
+| DELETE | `/api/users/:id` | 删除用户 |
+| GET | `/api/regions` | 下一级区域：`?parent=<value>`（树形懒加载） |
+| GET | `/api/regions/tree` | 完整区域树（440 节点） |
+| GET | `/api/options` | 候选项列表：`?keyword=&page=&pageSize=` |
+
+## 结构
+
+```
+src/
+├── app.ts          # 创建 app（与启动分离，便于 supertest 直接测）
+├── server.ts       # startServer()：listen 并 resolve 出 Server
+├── index.ts        # 模板入口（端口 3000）
+├── query.ts        # 搜索 → 排序 → 分页 的统一流水线
+├── middleware/     # zod 校验 / 错误处理
+├── routes/         # health / users / regions / options
+└── data/           # 内存种子数据（换成数据库时只替换这一层）
+test/               # supertest 集成测试
+```
+
+## 换成真实数据库
+
+`src/data/*` 暴露的是「读列表 / 查单个 / 新建 / 删除」这几个访问器，路由只依赖它们。
+把 `data/` 换成 Prisma / Drizzle / 原生 SQL 的实现即可，路由与校验层无需改动。

package/templates/api/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "start": "tsx src/index.ts",
+    "build": "tsc --noEmit",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "express": "^5.1.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^24.0.0",
+    "supertest": "^7.1.0",
+    "@types/supertest": "^6.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.0"
+  },
+  "overrides": {
+    "js-yaml": "^4.3.2",
+    "fast-uri": "^3.1.0",
+    "vite": "^6.3.5",
+    "electron": "^39.8.10"
+  },
+  "pnpm": {
+    "overrides": {
+      "js-yaml": "^4.1.1",
+      "fast-uri": "^3.1.0",
+      "vite": "^6.3.5"
+    }
+  }
+}

package/templates/api/src/app.ts

@@ -0,0 +1,84 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+import express from 'express'
+import type { Express, RequestHandler } from 'express'
+import { createHealthRouter } from './routes/health'
+import { usersRouter } from './routes/users'
+import { regionsRouter } from './routes/regions'
+import { optionsRouter } from './routes/options'
+import { errorHandler, notFoundHandler } from './middleware/error'
+import type { ApiInfo } from './types'
+
+export interface CreateAppOptions {
+  /** 服务名，会出现在根路由、健康检查与启动日志里 */
+  name?: string
+  version?: string
+  /** 插在所有业务路由前的自定义中间件，方便加日志/鉴权/耗时统计 */
+  middleware?: RequestHandler[]
+  /** 是否放开跨域，默认开启，便于本地联调 */
+  cors?: boolean
+}
+
+export const API_PREFIX = '/api'
+export const DEFAULT_API_NAME = 'kb-api'
+export const DEFAULT_API_VERSION = '0.1.0'
+
+const ENDPOINTS = [
+  'GET    /api/health',
+  'GET    /api/users?page=&pageSize=&keyword=&sortBy=&order=',
+  'GET    /api/users/:id',
+  'POST   /api/users',
+  'DELETE /api/users/:id',
+  'GET    /api/regions?parent=<value>',
+  'GET    /api/regions/tree',
+  'GET    /api/options?keyword=&page=&pageSize=',
+]
+
+/** 手写 CORS，避免为一个 mock 服务再引一个依赖；预检请求直接 204 返回 */
+function corsMiddleware(enabled: boolean): RequestHandler {
+  return (req, res, next) => {
+    if (!enabled) {
+      next()
+      return
+    }
+    res.setHeader('Access-Control-Allow-Origin', req.headers.origin ?? '*')
+    res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,PATCH,DELETE,OPTIONS')
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type,Authorization')
+    res.setHeader('Vary', 'Origin')
+    if (req.method === 'OPTIONS') {
+      res.status(204).end()
+      return
+    }
+    next()
+  }
+}
+
+/** 创建 Express 应用（与启动逻辑分离，便于 supertest 直接测） */
+export function createApp(options: CreateAppOptions = {}): Express {
+  const info: ApiInfo = {
+    name: options.name ?? DEFAULT_API_NAME,
+    version: options.version ?? DEFAULT_API_VERSION,
+  }
+
+  const app = express()
+  app.use(express.json())
+  app.use(corsMiddleware(options.cors ?? true))
+  for (const middleware of options.middleware ?? []) app.use(middleware)
+
+  app.get('/', (_req, res) => {
+    res.json({ name: info.name, version: info.version, prefix: API_PREFIX, endpoints: ENDPOINTS })
+  })
+
+  const healthRouter = createHealthRouter(info)
+  // 探活同时提供无前缀路径，方便容器/网关直接探测
+  app.use('/health', healthRouter)
+  app.use(`${API_PREFIX}/health`, healthRouter)
+  app.use(`${API_PREFIX}/users`, usersRouter)
+  app.use(`${API_PREFIX}/regions`, regionsRouter)
+  app.use(`${API_PREFIX}/options`, optionsRouter)
+
+  app.use(notFoundHandler)
+  app.use(errorHandler)
+  return app
+}

package/templates/api/src/data/options.ts

@@ -0,0 +1,17 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+export interface OptionItem {
+  key: string
+  label: string
+  disabled?: boolean
+}
+
+export const OPTIONS_TOTAL = 240
+
+/** 240 条候选项，每 17 条埋一个 disabled，用来演示穿梭框的禁用态 */
+export const options: OptionItem[] = Array.from({ length: OPTIONS_TOTAL }, (_, index) => ({
+  key: `opt-${index + 1}`,
+  label: `候选项 ${String(index + 1).padStart(3, '0')}`,
+  disabled: index % 17 === 0,
+}))

package/templates/api/src/data/regions.ts

@@ -0,0 +1,71 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+export interface RegionNode {
+  value: string
+  label: string
+  /** 末级标记：Cascader 异步模式直接消费这个字段 */
+  leaf: boolean
+  children?: RegionNode[]
+}
+
+/** 懒加载返回的节点摘要（不带 children，懒加载才有意义） */
+export interface RegionSummary {
+  value: string
+  label: string
+  leaf: boolean
+}
+
+const AREA_COUNT = 8
+const CITY_PER_AREA = 6
+const BLOCK_PER_CITY = 8
+
+/** 全合成数据（8 大区 × 6 城市 × 8 区块 = 440 个节点），刻意不带真实行政区划含义 */
+function buildRegions(): RegionNode[] {
+  const areas: RegionNode[] = []
+  for (let a = 1; a <= AREA_COUNT; a += 1) {
+    const areaId = `a${a}`
+    const cities: RegionNode[] = []
+    for (let c = 1; c <= CITY_PER_AREA; c += 1) {
+      const cityId = `${areaId}-c${c}`
+      const blocks: RegionNode[] = []
+      for (let b = 1; b <= BLOCK_PER_CITY; b += 1) {
+        blocks.push({ value: `${cityId}-b${b}`, label: `区块 ${b}`, leaf: true })
+      }
+      cities.push({ value: cityId, label: `城市 ${c}`, leaf: false, children: blocks })
+    }
+    areas.push({ value: areaId, label: `大区 ${a}`, leaf: false, children: cities })
+  }
+  return areas
+}
+
+const store = buildRegions()
+
+const index = new Map<string, RegionNode>()
+function indexNodes(nodes: RegionNode[]): void {
+  for (const node of nodes) {
+    index.set(node.value, node)
+    if (node.children) indexNodes(node.children)
+  }
+}
+indexNodes(store)
+
+/** 节点总数（8 + 48 + 384） */
+export const REGION_NODE_COUNT = index.size
+
+/** 完整嵌套树，供 Tree 的虚拟滚动演示 */
+export const regionTree: RegionNode[] = store
+
+export function toSummary(node: RegionNode): RegionSummary {
+  return { value: node.value, label: node.label, leaf: node.leaf }
+}
+
+/** 取某个节点的下一级；parent 为空时返回顶层。节点不存在或已是末级时返回 undefined */
+export function childrenOf(parent: string | null): RegionNode[] | undefined {
+  if (!parent) return store
+  return index.get(parent)?.children
+}
+
+export function findRegion(value: string): RegionNode | undefined {
+  return index.get(value)
+}

package/templates/api/src/data/users.ts

@@ -0,0 +1,76 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+export interface User {
+  id: number
+  name: string
+  company: string
+  city: string
+  email: string
+  role: string
+  score: number
+  createdAt: string
+}
+
+const SURNAMES = ['李', '王', '张', '刘', '陈', '杨', '黄', '赵', '周', '吴', '徐', '孙', '马', '朱', '胡', '郭']
+const GIVEN_NAMES = ['明', '华', '静', '敏', '伟', '芳', '强', '磊', '洋', '艳', '勇', '军', '杰', '娟', '涛', '超']
+const COMPANIES = ['星尘科技', '云图数据', '南栀软件', '澜川网络', '青梧智能', '归墟信息', '未名云', '鸣石科技']
+const CITIES = ['北京', '上海', '广州', '深圳', '杭州', '成都', '武汉', '西安', '南京', '苏州']
+export const USER_ROLES = ['管理员', '编辑', '访客'] as const
+
+/** 参与 keyword 模糊匹配的字段 */
+export const USER_SEARCH_FIELDS = ['name', 'company', 'city', 'email'] as const
+/** 允许排序的字段白名单 */
+export const USER_SORT_KEYS = ['id', 'name', 'company', 'city', 'role', 'score', 'createdAt'] as const
+
+export const USERS_TOTAL = 500
+
+function formatDate(offsetDays: number): string {
+  const base = Date.UTC(2026, 0, 1)
+  return new Date(base + offsetDays * 86_400_000).toISOString().slice(0, 10)
+}
+
+/** 500 条确定性数据：用下标做取模而不是随机数，保证分页与测试可复现 */
+const store: User[] = Array.from({ length: USERS_TOTAL }, (_, index) => ({
+  id: index + 1,
+  name: `${SURNAMES[index % SURNAMES.length]}${GIVEN_NAMES[(index * 7) % GIVEN_NAMES.length]}`,
+  company: COMPANIES[index % COMPANIES.length],
+  city: CITIES[(index * 3) % CITIES.length],
+  email: `user${index + 1}@example.com`,
+  role: USER_ROLES[index % USER_ROLES.length],
+  score: (index * 37) % 100,
+  createdAt: formatDate(index),
+}))
+
+/** 只读视图，路由层拿它做查询 */
+export function listUsers(): User[] {
+  return store
+}
+
+export function findUser(id: number): User | undefined {
+  return store.find((user) => user.id === id)
+}
+
+let nextId = USERS_TOTAL + 1
+
+export function createUser(payload: Pick<User, 'name'> & Partial<User>): User {
+  const user: User = {
+    id: nextId++,
+    name: payload.name,
+    company: payload.company ?? COMPANIES[0],
+    city: payload.city ?? CITIES[0],
+    email: payload.email ?? `user${nextId - 1}@example.com`,
+    role: payload.role ?? USER_ROLES[2],
+    score: payload.score ?? 0,
+    createdAt: formatDate(0),
+  }
+  store.push(user)
+  return user
+}
+
+export function removeUser(id: number): boolean {
+  const index = store.findIndex((user) => user.id === id)
+  if (index < 0) return false
+  store.splice(index, 1)
+  return true
+}

package/templates/api/src/index.ts

@@ -0,0 +1,9 @@
+import { startServer } from './server'
+
+/** 模板入口：端口默认 3000（与 docker-compose、web 代理保持一致），可用 PORT 覆盖 */
+const port = Number(process.env.PORT ?? 3000)
+
+startServer({ port, name: '{{projectName}}-api' }).catch((error: unknown) => {
+  console.error('[api] 启动失败:', error)
+  process.exitCode = 1
+})

package/templates/api/src/middleware/error.ts

@@ -0,0 +1,28 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+import type { Request, Response, NextFunction } from 'express'
+
+/** 统一的 404 响应，挂在所有路由之后 */
+export function notFoundHandler(req: Request, res: Response) {
+  res.status(404).json({ code: 404, message: `接口不存在: ${req.method} ${req.path}` })
+}
+
+/** 统一错误响应，Express 5 会自动捕获 async 路由里抛出的异常并转到这里 */
+export function errorHandler(err: unknown, _req: Request, res: Response, _next: NextFunction) {
+  const message = err instanceof Error ? err.message : String(err)
+  const status = err instanceof HttpError ? err.status : 500
+  if (status >= 500) console.error('[api] 未捕获异常:', err)
+  res.status(status).json({ code: status, message: status >= 500 ? '服务器内部错误' : message })
+}
+
+/** 路由里可以直接 throw new HttpError(404, '未找到') */
+export class HttpError extends Error {
+  readonly status: number
+
+  constructor(status: number, message: string) {
+    super(message)
+    this.name = 'HttpError'
+    this.status = status
+  }
+}

package/templates/api/src/middleware/validate.ts

@@ -0,0 +1,22 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+import type { Request, Response, NextFunction, RequestHandler } from 'express'
+import type { ZodType } from 'zod'
+
+/** zod 校验中间件：校验通过后把解析结果挂回 req.body，失败返回 400 与字段级错误 */
+export function validate(schema: ZodType): RequestHandler {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const result = schema.safeParse(req.body)
+    if (!result.success) {
+      res.status(400).json({
+        code: 400,
+        message: '参数校验失败',
+        errors: result.error.flatten().fieldErrors,
+      })
+      return
+    }
+    req.body = result.data
+    next()
+  }
+}

package/templates/api/src/query.ts

@@ -0,0 +1,106 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+export type SortOrder = 'asc' | 'desc'
+
+export interface PageQuery {
+  page: number
+  pageSize: number
+  keyword: string
+  sortBy: string | null
+  order: SortOrder
+}
+
+export interface PageResult<T> {
+  list: T[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+export interface ListQueryOptions {
+  /** 参与 keyword 模糊匹配的字段 */
+  searchFields?: readonly string[]
+  /** 允许排序的字段白名单，未列出的字段会被忽略（避免任意字段排序） */
+  sortKeys?: readonly string[]
+}
+
+export const DEFAULT_PAGE_SIZE = 10
+export const MAX_PAGE_SIZE = 500
+
+function toPositiveInt(value: unknown, fallback: number): number {
+  const num = Number(value)
+  if (!Number.isFinite(num)) return fallback
+  const int = Math.floor(num)
+  return int > 0 ? int : fallback
+}
+
+function readField(row: unknown, field: string): unknown {
+  return (row as Record<string, unknown>)[field]
+}
+
+function compareValues(a: unknown, b: unknown): number {
+  if (a === b) return 0
+  if (a === null || a === undefined) return -1
+  if (b === null || b === undefined) return 1
+  if (typeof a === 'number' && typeof b === 'number') return a - b
+  return String(a).localeCompare(String(b), 'zh-Hans-CN')
+}
+
+/** 解析 ?page=&pageSize=&keyword=&sortBy=&order=，非法值一律回退到默认值 */
+export function parsePageQuery(query: Record<string, unknown> = {}): PageQuery {
+  return {
+    page: toPositiveInt(query.page, 1),
+    pageSize: Math.min(toPositiveInt(query.pageSize, DEFAULT_PAGE_SIZE), MAX_PAGE_SIZE),
+    keyword: typeof query.keyword === 'string' ? query.keyword.trim() : '',
+    sortBy: typeof query.sortBy === 'string' && query.sortBy ? query.sortBy : null,
+    order: query.order === 'desc' ? 'desc' : 'asc',
+  }
+}
+
+export function searchRows<T>(
+  rows: readonly T[],
+  keyword: string,
+  fields: readonly string[],
+): T[] {
+  if (!keyword) return [...rows]
+  const needle = keyword.toLowerCase()
+  return rows.filter((row) =>
+    fields.some((field) => String(readField(row, field) ?? '').toLowerCase().includes(needle)),
+  )
+}
+
+export function sortRows<T>(
+  rows: readonly T[],
+  sortBy: string | null,
+  order: SortOrder,
+  allowedKeys?: readonly string[],
+): T[] {
+  if (!sortBy) return [...rows]
+  if (allowedKeys && !allowedKeys.includes(sortBy)) return [...rows]
+  const factor = order === 'desc' ? -1 : 1
+  return [...rows].sort((a, b) => compareValues(readField(a, sortBy), readField(b, sortBy)) * factor)
+}
+
+export function toPageResult<T>(rows: readonly T[], query: PageQuery): PageResult<T> {
+  const start = (query.page - 1) * query.pageSize
+  return {
+    list: rows.slice(start, start + query.pageSize),
+    total: rows.length,
+    page: query.page,
+    pageSize: query.pageSize,
+  }
+}
+
+/** 搜索 → 排序 → 分页 的标准流水线，列表接口都用它，保证行为一致 */
+export function queryList<T>(
+  source: readonly T[],
+  query: PageQuery,
+  options: ListQueryOptions = {},
+): PageResult<T> {
+  const searched = options.searchFields
+    ? searchRows(source, query.keyword, options.searchFields)
+    : [...source]
+  const sorted = sortRows(searched, query.sortBy, query.order, options.sortKeys)
+  return toPageResult(sorted, query)
+}

package/templates/api/src/routes/health.ts

@@ -0,0 +1,21 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+import { Router } from 'express'
+import type { ApiInfo } from '../types'
+
+/** GET /health —— 探活接口，返回服务标识与运行时长 */
+export function createHealthRouter(info: ApiInfo): Router {
+  const router = Router()
+
+  router.get('/', (_req, res) => {
+    res.json({
+      status: 'ok',
+      name: info.name,
+      version: info.version,
+      uptime: Math.round(process.uptime()),
+    })
+  })
+
+  return router
+}

package/templates/api/src/routes/options.ts

@@ -0,0 +1,19 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+import { Router } from 'express'
+import { parsePageQuery, queryList } from '../query'
+import { options } from '../data/options'
+
+// 显式标注类型：否则 dts 生成会因 pnpm 的 .pnpm 路径而报 TS2742（类型不可命名）
+export const optionsRouter: Router = Router()
+
+/**
+ * GET /options?keyword=&page=&pageSize=
+ * 240 条候选项的分页 + 搜索，供 Transfer 的搜索过滤与分页演示取数。
+ * 返回的 total 是过滤后的条数，前端可直接用它算总页数。
+ */
+optionsRouter.get('/', (req, res) => {
+  const query = parsePageQuery(req.query as Record<string, unknown>)
+  res.json(queryList(options, query, { searchFields: ['label'], sortKeys: ['key', 'label'] }))
+})

package/templates/api/src/routes/regions.ts

@@ -0,0 +1,31 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+import { Router } from 'express'
+import { HttpError } from '../middleware/error'
+import { REGION_NODE_COUNT, childrenOf, findRegion, regionTree, toSummary } from '../data/regions'
+
+// 显式标注类型：否则 dts 生成会因 pnpm 的 .pnpm 路径而报 TS2742（类型不可命名）
+export const regionsRouter: Router = Router()
+
+/** GET /regions/tree —— 完整嵌套树（440 个节点），供 Tree 虚拟滚动使用 */
+regionsRouter.get('/tree', (_req, res) => {
+  res.json({ list: regionTree, total: REGION_NODE_COUNT })
+})
+
+/**
+ * GET /regions?parent=<value>
+ * 只返回下一级节点摘要（不带 children），节点不存在时 404。
+ * Cascader 的 lazyLoad 直接消费返回的 leaf 字段判断末级。
+ */
+regionsRouter.get('/', (req, res) => {
+  const parent = typeof req.query.parent === 'string' && req.query.parent ? req.query.parent : null
+  if (parent && !findRegion(parent)) throw new HttpError(404, `节点不存在: ${parent}`)
+
+  const children = childrenOf(parent) ?? []
+  res.json({
+    parent,
+    list: children.map(toSummary),
+    leaf: children.length === 0,
+  })
+})

package/templates/api/src/routes/users.ts

@@ -0,0 +1,57 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+import { Router } from 'express'
+import { z } from 'zod'
+import { validate } from '../middleware/validate'
+import { HttpError } from '../middleware/error'
+import { parsePageQuery, queryList } from '../query'
+import {
+  USER_SEARCH_FIELDS,
+  USER_SORT_KEYS,
+  createUser,
+  findUser,
+  listUsers,
+  removeUser,
+} from '../data/users'
+
+const createUserSchema = z.object({
+  name: z.string().min(1).max(50),
+  company: z.string().max(50).optional(),
+  city: z.string().max(30).optional(),
+  email: z.string().max(80).optional(),
+  role: z.string().max(20).optional(),
+  score: z.number().int().min(0).max(100).optional(),
+})
+
+// 显式标注类型：否则 dts 生成会因 pnpm 的 .pnpm 路径而报 TS2742（类型不可命名）
+export const usersRouter: Router = Router()
+
+/**
+ * GET /users?page=&pageSize=&keyword=&sortBy=&order=
+ * 标准的分页 + 排序 + 搜索，直接对接 Table 的服务端模式（sortable: 'custom'）
+ */
+usersRouter.get('/', (req, res) => {
+  const query = parsePageQuery(req.query as Record<string, unknown>)
+  res.json(
+    queryList(listUsers(), query, {
+      searchFields: USER_SEARCH_FIELDS,
+      sortKeys: USER_SORT_KEYS,
+    }),
+  )
+})
+
+usersRouter.get('/:id', (req, res) => {
+  const user = findUser(Number(req.params.id))
+  if (!user) throw new HttpError(404, `用户不存在: ${req.params.id}`)
+  res.json(user)
+})
+
+usersRouter.post('/', validate(createUserSchema), (req, res) => {
+  res.status(201).json(createUser(req.body))
+})
+
+usersRouter.delete('/:id', (req, res) => {
+  if (!removeUser(Number(req.params.id))) throw new HttpError(404, `用户不存在: ${req.params.id}`)
+  res.status(204).end()
+})

package/templates/api/src/server.ts

@@ -0,0 +1,31 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+import type { Server } from 'node:http'
+import { createApp, DEFAULT_API_NAME } from './app'
+import type { CreateAppOptions } from './app'
+
+export interface StartServerOptions extends CreateAppOptions {
+  /** 监听端口，默认读环境变量 PORT，否则 8082 */
+  port?: number
+  /** 监听地址，默认 127.0.0.1（本地 mock 不对外暴露） */
+  host?: string
+}
+
+export const DEFAULT_PORT = 8082
+
+/** 启动服务，listen 成功后 resolve 出 Server，便于脚本里追加逻辑或优雅退出 */
+export function startServer(options: StartServerOptions = {}): Promise<Server> {
+  const name = options.name ?? DEFAULT_API_NAME
+  const port = options.port ?? Number(process.env.PORT ?? DEFAULT_PORT)
+  const host = options.host ?? '127.0.0.1'
+  const app = createApp(options)
+
+  return new Promise((resolve, reject) => {
+    const server = app.listen(port, host, () => {
+      console.log(`[${name}] 已启动: http://${host}:${port}/api`)
+      resolve(server)
+    })
+    server.on('error', reject)
+  })
+}