@dtdyq/restbase 1.0.0

package/server.ts

@@ -0,0 +1,201 @@
+/**
+ * server.ts — 入口文件
+ *
+ * 职责：
+ *   1. 安全检查
+ *   2. 初始化数据库（失败终止）
+ *   3. 创建 Hono 应用 / CORS 中间件
+ *   4. requestId 中间件（自动生成或读取 X-Request-Id）
+ *   5. API 限流中间件（令牌桶算法，每秒每 API）
+ *   6. 最外层日志中间件（INFO: requestId/method/path/ms；DEBUG: +headers/body/response/SQL）
+ *   7. 全局错误兜底（任何异常统一返回 HTTP 200 + 标准 JSON）
+ *   8. 健康检查接口
+ *   9. 鉴权中间件（JWT + Basic Auth）
+ *   10. 注册 auth / CRUD 路由 / 元数据接口
+ *   11. 静态文件托管（可选）
+ *   12. 启动 Bun HTTP 服务
+ *
+ * 启动命令:  bun run server.ts
+ */
+import {Hono} from "hono";
+import {requestId} from "hono/request-id";
+import {cors} from "hono/cors";
+import {serveStatic} from "hono/bun";
+import {type ApiRes, type AppEnv, AppError, cfg, ok, reqStore} from "./types.ts";
+import {log} from "./logger.ts";
+import {getTableMetaByName, getTablesMeta, initDb, syncTablesMeta} from "./db.ts";
+import {authMiddleware, registerAuthRoutes} from "./auth.ts";
+import {registerCrudRoutes} from "./crud.ts";
+
+/* ═══════════ 1. 安全检查 ═══════════ */
+
+if (cfg.jwtSecret === "restbase") {
+    log.warn("AUTH_JWT_SECRET is using default value! Set a strong secret in production.");
+}
+
+/* ═══════════ 2. 初始化数据库 ═══════════ */
+
+try {
+    await initDb();
+} catch (err) {
+    log.fatal({err}, "Database init failed");
+    process.exit(1);
+}
+
+/* ═══════════ 2. 创建 Hono 应用 ═══════════ */
+
+const app = new Hono<AppEnv>();
+
+/* ═══════════ 3. CORS 中间件 ═══════════ */
+
+app.use("*", cors({
+    origin: "*",                     // 允许所有来源（生产环境可改为具体域名）
+    allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+    allowHeaders: ["Content-Type", "Authorization", "X-Request-Id"],
+    exposeHeaders: ["X-Request-Id"],
+    maxAge: 86400,                   // preflight 缓存 24 小时
+}));
+
+/* ═══════════ 4. Request ID 中间件 ═══════════ */
+/* 优先读取请求头 X-Request-Id，没有则自动生成 UUID */
+
+app.use("*", requestId());
+
+/* ═══════════ 5. API 限流中间件（滑动窗口，每秒每 IP） ═══════════ */
+
+if (cfg.apiLimit > 0) {
+    /** API 路径 → { tokens: 剩余令牌, lastRefill: 上次填充时间戳 } */
+    const buckets = new Map<string, { tokens: number; lastRefill: number }>();
+
+    app.use("/api/*", async (c, next) => {
+        const key = `${c.req.method} ${c.req.path}`;
+        const now = Date.now();
+        let bucket = buckets.get(key);
+
+        if (!bucket) {
+            bucket = {tokens: cfg.apiLimit, lastRefill: now};
+            buckets.set(key, bucket);
+        }
+
+        /* 按经过的时间补充令牌（令牌桶算法） */
+        const elapsed = (now - bucket.lastRefill) / 1000;
+        bucket.tokens = Math.min(cfg.apiLimit, bucket.tokens + elapsed * cfg.apiLimit);
+        bucket.lastRefill = now;
+
+        if (bucket.tokens < 1) {
+            c.res = new Response(
+                JSON.stringify({code: "RATE_LIMITED", message: `Rate limit exceeded (${cfg.apiLimit} req/s)`}, null, 2),
+                {status: 200, headers: {"Content-Type": "application/json", "Retry-After": "1"}},
+            );
+            return;
+        }
+
+        bucket.tokens -= 1;
+        return next();
+    });
+
+    log.info({limit: cfg.apiLimit}, `API rate limit: ${cfg.apiLimit} req/s per API`);
+}
+
+/* ═══════════ 6. 日志中间件（最外层） ═══════════ */
+
+app.use("*", async (c, next) => {
+    const start = Date.now();
+    const requestId = c.get("requestId");
+
+    /* 将 requestId 注入 AsyncLocalStorage，下游（如 db.run）可自动获取 */
+    await reqStore.run({requestId}, async () => {
+        /* DEBUG: 打印请求详情 */
+        if (cfg.logLevel === "DEBUG") {
+            const headers: Record<string, string> = {};
+            c.req.raw.headers.forEach((v, k) => (headers[k] = v));
+            log.debug({requestId, method: c.req.method, path: c.req.path, headers}, "← request");
+            if (c.req.method !== "GET" && c.req.method !== "HEAD") {
+                try {
+                    log.debug({requestId, body: await c.req.raw.clone().text()}, "← body");
+                } catch { /* ignore */
+                }
+            }
+        }
+
+        await next();
+
+        /* JSON 响应默认格式化（pretty print） */
+        const ct = c.res.headers.get("Content-Type");
+        if (ct?.includes("application/json")) {
+            const body = await c.res.json();
+            c.res = new Response(JSON.stringify(body, null, 2), c.res);
+        }
+
+        const ms = Date.now() - start;
+
+        /* INFO / DEBUG: 打印请求摘要（含 requestId） */
+        if (cfg.logLevel !== "ERROR") {
+            log.info({requestId, method: c.req.method, path: c.req.path, ms}, "→ response");
+        }
+
+        /* DEBUG: 打印响应体 */
+        if (cfg.logLevel === "DEBUG") {
+            try {
+                log.debug({requestId, body: await c.res.clone().text()}, "→ body");
+            } catch { /* ignore */
+            }
+        }
+    });
+});
+
+/* ═══════════ 7. 全局错误兜底（始终 HTTP 200） ═══════════ */
+
+app.onError((err, c) => {
+    if (err instanceof AppError) {
+        return c.json({code: err.code, message: err.message} as ApiRes);
+    }
+    /* 非业务错误：打印堆栈，返回通用错误码 */
+    log.error({err}, "Unhandled error");
+    return c.json({
+        code: "SYS_ERROR",
+        message: err.message || "Internal server error",
+    } as ApiRes);
+});
+
+/* ═══════════ 8. 健康检查（公开） ═══════════ */
+
+app.get("/api/health", (c) => c.json(ok({status: "healthy"})));
+
+/* ═══════════ 9. 鉴权中间件 ═══════════ */
+
+app.use("/api/*", authMiddleware);
+
+/* ═══════════ 10. 注册路由 ═══════════ */
+
+registerAuthRoutes(app);
+registerCrudRoutes(app);
+
+/* ═══════════ 11. 元数据接口 ═══════════ */
+
+app.get("/api/meta/tables", (c) => c.json(ok(getTablesMeta())));
+
+app.get("/api/meta/tables/:name", (c) => {
+    const data = getTableMetaByName(c.req.param("name"));
+    return c.json(ok(data));
+});
+
+app.get("/api/meta/sync", async (c) => {
+    const data = await syncTablesMeta();
+    return c.json(ok(data));
+});
+
+/* ═══════════ 12. 静态文件托管（可选） ═══════════ */
+
+if (cfg.staticDir) {
+    /* 静态资源 */
+    app.use("/*", serveStatic({root: cfg.staticDir}));
+    /* SPA fallback：所有未匹配路由返回 index.html */
+    app.use("/*", serveStatic({root: cfg.staticDir, path: "index.html"}));
+    log.info({dir: cfg.staticDir}, "Static file serving enabled");
+}
+
+/* ═══════════ 13. 启动服务 ═══════════ */
+
+export const server = Bun.serve({port: cfg.port, fetch: app.fetch});
+log.info({port: cfg.port}, `Server started http://localhost:${cfg.port}`);

package/types.ts

@@ -0,0 +1,186 @@
+/**
+ * types.ts — 全局配置、类型定义、统一响应、Zod 校验、AppError
+ *
+ * 所有 .env 变量均有默认值（约定大于配置）
+ */
+import {z} from "zod";
+import {AsyncLocalStorage} from "node:async_hooks";
+
+/* ═══════════ .env 配置 ═══════════ */
+
+const _db = Bun.env.DB_URL ?? "sqlite://:memory:";
+
+export const cfg = {
+    /** 服务端口 */
+    port: Number(Bun.env.SVR_PORT) || 3333,
+    /** 静态文件目录（相对路径，为空则不托管） */
+    staticDir: Bun.env.SVR_STATIC ?? "",
+    /** API 限流：每秒每个 API 接口允许的最大请求数（0 = 不限流） */
+    apiLimit: Number(Bun.env.SVR_API_LIMIT) || 100,
+    /** 数据库连接字符串 */
+    db: _db,
+    /** 是否 SQLite（非 mysql:// 则视为 SQLite） */
+    isSqlite: !_db.startsWith("mysql"),
+    /** 用户认证表名 */
+    authTable: Bun.env.DB_AUTH_TABLE ?? "users",
+    /** 数据表中的 owner 字段名 */
+    ownerField: Bun.env.DB_AUTH_FIELD ?? "owner",
+    /** owner 字段为 NULL 时视为公开数据（查询自动追加 OR owner IS NULL），默认 false */
+    ownerNullOpen: (Bun.env.DB_AUTH_FIELD_NULL_OPEN ?? "false") === "true",
+    /** JWT 密钥 */
+    jwtSecret: Bun.env.AUTH_JWT_SECRET ?? "restbase",
+    /** JWT 过期秒数（默认 12 小时） */
+    jwtExp: Number(Bun.env.AUTH_JWT_EXP) || 43200,
+    /** 是否开启 Basic Auth（默认 true） */
+    basicAuth: (Bun.env.AUTH_BASIC_OPEN ?? "true") !== "false",
+    /** 日志等级 */
+    logLevel: (Bun.env.LOG_LEVEL ?? "INFO").toUpperCase() as "ERROR" | "INFO" | "DEBUG",
+    /** 是否输出到控制台（默认 true） */
+    logConsole: (Bun.env.LOG_CONSOLE ?? "true") !== "false",
+    /** 日志文件路径（不配置则不写文件） */
+    logFile: Bun.env.LOG_FILE ?? "",
+    /** 日志文件保留天数（默认 7） */
+    logRetainDays: Number(Bun.env.LOG_RETAIN_DAYS) || 7,
+    /** 初始化 SQL 文件路径（相对路径，启动时执行） */
+    initSql: Bun.env.DB_INIT_SQL ?? "",
+};
+
+/**
+ * 生成 owner 过滤条件 SQL 片段
+ * - 默认: `"owner" = $N`
+ * - ownerNullOpen=true: `("owner" = $N OR "owner" IS NULL)`
+ */
+export function ownerCond(paramIdx: number | string): string {
+    const ph = typeof paramIdx === "string" ? paramIdx : `$${paramIdx}`;
+    const base = `${q(cfg.ownerField)} = ${ph}`;
+    if (cfg.ownerNullOpen) {
+        return `(${base} OR ${q(cfg.ownerField)} IS NULL)`;
+    }
+    return base;
+}
+
+/* ═══════════ 请求上下文（AsyncLocalStorage） ═══════════ */
+
+export const reqStore = new AsyncLocalStorage<{ requestId: string }>();
+
+/* ═══════════ SQL 标识符引用 ═══════════ */
+
+/** SQLite 用双引号，MySQL 用反引号 */
+export const q = (id: string) => (cfg.isSqlite ? `"${id}"` : `\`${id}\``);
+
+/* ═══════════ Hono 环境泛型 ═══════════ */
+
+export type AppEnv = { Variables: { userId: number; username: string; requestId: string } };
+
+/* ═══════════ 统一 JSON 响应结构 ═══════════ */
+
+export interface ApiRes {
+    code: string;
+    message?: string;
+    data?: unknown;
+    pageNo?: number;
+    pageSize?: number;
+    total?: number;
+}
+
+export const ok = (data?: unknown): ApiRes => ({code: "OK", data: data ?? null});
+
+export const paged = (
+    rows: unknown[],
+    pageNo: number,
+    pageSize: number,
+    total: number,
+): ApiRes => ({code: "OK", data: rows, pageNo, pageSize, total});
+
+/* ═══════════ 业务错误（HTTP 始终返回 200） ═══════════ */
+
+export class AppError extends Error {
+    code: string;
+
+    constructor(code: string, message: string) {
+        super(message);
+        this.name = "AppError";
+        this.code = code;
+    }
+}
+
+/* ═══════════ Zod 校验 hook（失败时返回 200 + 统一格式） ═══════════ */
+
+export const zodHook = (result: any, _c: any) => {
+    if (!result.success) {
+        const msg = result.error.issues.map((i: any) => i.message).join("; ");
+        return new Response(
+            JSON.stringify({code: "VALIDATION_ERROR", message: msg}, null, 2),
+            {status: 200, headers: {"Content-Type": "application/json"}},
+        );
+    }
+};
+
+/* ═══════════ Zod Schemas ═══════════ */
+
+export const authBodySchema = z.object({
+    username: z.string().min(1, "username is required"),
+    password: z.string().min(1, "password is required"),
+});
+
+/* ── Body 输入类型（递归部分需手动声明类型） ── */
+
+/** where 条件单元 */
+export type BodyWhereItem =
+    | [string, unknown]                             // [field, value] 默认 eq
+    | [string, string, unknown]                     // [field, op, value]
+    | { field: string; op: string; value?: unknown } // 对象格式
+    | { op: "and" | "or"; cond: BodyWhereInput[] }; // 逻辑组合
+
+/** where 顶层：单条件 或 条件数组 */
+export type BodyWhereInput = BodyWhereItem | BodyWhereItem[];
+
+export const bodyWhereItemSchema: z.ZodType<BodyWhereItem> = z.lazy(() =>
+    z.union([
+        z.tuple([z.string(), z.unknown()]),
+        z.tuple([z.string(), z.string(), z.unknown()]),
+        z.object({ field: z.string(), op: z.string(), value: z.unknown().optional() }),
+        z.object({ op: z.enum(["and", "or"]), cond: z.array(bodyWhereInputSchema) }),
+    ]),
+);
+
+export const bodyWhereInputSchema: z.ZodType<BodyWhereInput> = z.lazy(() =>
+    z.union([
+        bodyWhereItemSchema,
+        z.array(bodyWhereItemSchema),
+    ]),
+);
+
+/** select 项 */
+export const bodySelectItemSchema = z.union([
+    z.string().min(1),
+    z.object({ field: z.string().min(1), alias: z.string().optional(), func: z.string().optional() }),
+]);
+export type BodySelectItem = z.infer<typeof bodySelectItemSchema>;
+
+/** order 项 */
+export const bodyOrderItemSchema = z.union([
+    z.string().min(1),
+    z.object({ field: z.string().min(1), dir: z.enum(["asc", "desc"]).optional() }),
+]);
+export type BodyOrderItem = z.infer<typeof bodyOrderItemSchema>;
+
+/** POST /api/query/:table — 完整查询 Body */
+export const bodyQuerySchema = z.object({
+    select: z.array(bodySelectItemSchema).optional(),
+    where: bodyWhereInputSchema.optional(),
+    order: z.array(bodyOrderItemSchema).optional(),
+    group: z.array(z.string()).optional(),
+    pageNo: z.number().int().min(1).optional(),
+    pageSize: z.number().int().min(1).max(1000).optional(),
+});
+export type BodyQuery = z.infer<typeof bodyQuerySchema>;
+
+/** POST /api/delete/:table — 删除 Body（直接是 where 条件） */
+export const bodyDeleteSchema = bodyWhereInputSchema;
+
+/** POST|PUT /api/data/:table — 创建/更新 Body（单对象或对象数组） */
+export const bodyDataSchema = z.union([
+    z.record(z.string(), z.unknown()),
+    z.array(z.record(z.string(), z.unknown())).min(1),
+]);