@dtdyq/restbase 1.0.0

package/README.md

@@ -0,0 +1,105 @@
+# RestBase
+
+> 零代码通用 REST 服务 — 连接 SQLite / MySQL，自动将数据表通过 REST API 暴露。
+
+## 特性
+
+- **零代码 CRUD** — 自动分析表结构，生成完整 REST 接口
+- **租户隔离** — `owner` 字段自动按用户隔离数据，支持 NULL 公开模式
+- **双鉴权** — JWT + Basic Auth 开箱即用
+- **两套查询** — URL 参数（CLI 调试）+ POST Body（前端推荐），支持复杂 WHERE / SELECT / ORDER / GROUP / 分页
+- **类型安全客户端** — 零依赖 TypeScript 客户端，链式 API，编译期推导 SELECT 返回类型
+- **静态文件托管** — 可选挂载前端打包产物，API 与前端同端口
+- **结构化日志** — pino + 文件滚动 + 请求追踪 ID
+- **单文件部署** — `bun build --compile` 编译为独立二进制，支持交叉编译
+
+## 快速开始
+
+```bash
+bun install
+bun run server.ts
+```
+
+```bash
+# 健康检查
+curl http://localhost:3333/api/health
+
+# Basic Auth 查询
+curl -u admin:admin http://localhost:3333/api/data/products
+```
+
+## 构建与部署
+
+```bash
+bun run build              # 当前平台
+bun run build:linux        # Linux x64
+bun run build:linux-arm    # Linux ARM64
+bun run build:mac          # macOS x64
+bun run build:mac-arm      # macOS ARM64
+bun run build:windows      # Windows x64
+
+# 运行二进制（无需 Bun 运行时）
+./restbase
+```
+
+## 环境变量
+
+| 变量                        | 说明                         | 默认值                 |
+|:--------------------------|:---------------------------|:--------------------|
+| `SVR_PORT`                | 服务端口                       | `3333`              |
+| `SVR_STATIC`              | 静态文件目录（前端托管）               | 空                   |
+| `SVR_API_LIMIT`           | API 限流（每秒每接口请求数）           | `100`               |
+| `DB_URL`                  | 数据库连接串                     | `sqlite://:memory:` |
+| `DB_AUTH_TABLE`           | 用户表名                       | `users`             |
+| `DB_AUTH_FIELD`           | owner 字段名                  | `owner`             |
+| `DB_AUTH_FIELD_NULL_OPEN` | owner=NULL 视为公开            | `false`             |
+| `DB_INIT_SQL`             | 启动时执行的 SQL 文件              | 空                   |
+| `AUTH_JWT_SECRET`         | JWT 密钥                     | `restbase`          |
+| `AUTH_JWT_EXP`            | JWT 过期秒数                   | `43200`             |
+| `AUTH_BASIC_OPEN`         | 开启 Basic Auth              | `true`              |
+| `LOG_LEVEL`               | `ERROR` / `INFO` / `DEBUG` | `INFO`              |
+| `LOG_CONSOLE`             | 控制台输出                      | `true`              |
+| `LOG_FILE`                | 日志文件路径                     | 空                   |
+| `LOG_RETAIN_DAYS`         | 日志保留天数                     | `7`                 |
+
+## 测试
+
+```bash
+bun test rest.test.ts    # 137+ 用例
+```
+
+## 文档
+
+| 文档                                               | 内容                                                |
+|:-------------------------------------------------|:--------------------------------------------------|
+| [documents/server.md](documents/server.md)       | 服务端详细文档 — 配置、全部 API 接口说明与示例、日志、部署                 |
+| [documents/client.md](documents/client.md)       | 前端客户端文档 — 安装、API 速查、QueryBuilder 链式调用、类型安全 SELECT |
+| [documents/db_design.md](documents/db_design.md) | 数据库设计指南 — 表结构规范、约束、索引、设计模式与检查清单                   |
+| [documents/design.md](documents/design.md)       | 需求与设计文档 — 架构设计、技术规格、完整接口定义                        |
+
+## 文件结构
+
+```
+restbase/
+├── server.ts            # 入口
+├── types.ts             # 配置 + 类型
+├── db.ts                # 数据库
+├── auth.ts              # 鉴权
+├── crud.ts              # CRUD 路由
+├── query.ts             # SQL 生成
+├── logger.ts            # 日志
+├── client/
+│   └── restbase-client.ts   # 前端客户端
+├── documents/
+│   ├── design.md        # 需求设计文档
+│   ├── server.md        # 服务端文档
+│   └── client.md        # 客户端文档
+├── init.sql             # 初始化 SQL
+├── rest.test.ts         # 集成测试
+├── .env / .env.test     # 环境配置
+└── package.json
+```
+
+## License
+
+MIT

package/auth.ts

@@ -0,0 +1,164 @@
+/**
+ * auth.ts — 鉴权中间件（JWT + Basic Auth）、登录 / 注册 / 用户资料
+ *
+ * 公开路径（无需鉴权）：
+ *   POST /api/auth/login
+ *   POST /api/auth/register
+ *   GET  /api/health
+ *
+ * JWT payload: { sub: username, uid: userId, iat, exp }
+ * Basic Auth:  Authorization: Basic base64(username:password)
+ */
+import type {Context, Hono, Next} from "hono";
+import {sign as jwtSign, verify as jwtVerify} from "hono/jwt";
+import {zValidator} from "@hono/zod-validator";
+import {type AppEnv, AppError, authBodySchema, cfg, ok, q, zodHook,} from "./types.ts";
+import {getTable, run} from "./db.ts";
+
+/* ═══════════ 公开路径集合 ═══════════ */
+
+const PUBLIC = new Set(["/api/auth/login", "/api/auth/register", "/api/health"]);
+
+/* ═══════════ 鉴权中间件 ═══════════ */
+
+export const authMiddleware = async (
+    c: Context<AppEnv>,
+    next: Next,
+) => {
+    if (PUBLIC.has(c.req.path)) return next();
+
+    const header = c.req.header("Authorization") ?? "";
+
+    /* ── JWT: Bearer <token> ── */
+    if (header.startsWith("Bearer ")) {
+        try {
+            const payload = await jwtVerify(header.slice(7), cfg.jwtSecret, "HS256");
+            c.set("userId", payload.uid as number);
+            c.set("username", payload.sub as string);
+            return next();
+        } catch {
+            /* JWT 失败 → 尝试 Basic Auth */
+        }
+    }
+
+    /* ── Basic Auth: Basic base64(user:pass) ── */
+    if (cfg.basicAuth && header.startsWith("Basic ")) {
+        try {
+            const decoded = atob(header.slice(6));
+            const sep = decoded.indexOf(":");
+            if (sep > 0) {
+                const username = decoded.slice(0, sep);
+                const password = decoded.slice(sep + 1);
+                const user = await findUser(username);
+                if (user && user.password === password) {
+                    c.set("userId", user.id as number);
+                    c.set("username", username);
+                    return next();
+                }
+            }
+        } catch {
+            /* ignore decode errors */
+        }
+    }
+
+    throw new AppError("AUTH_ERROR", "Unauthorized");
+};
+
+/* ═══════════ 内部工具 ═══════════ */
+
+async function findUser(username: string) {
+    const rows = await run(
+        `SELECT id, username, password
+         FROM ${q(cfg.authTable)}
+         WHERE username = $1`,
+        [username],
+    );
+    return rows.length > 0 ? (rows[0] as any) : null;
+}
+
+async function issueToken(uid: number, username: string): Promise<string> {
+    const now = Math.floor(Date.now() / 1000);
+    return jwtSign(
+        {sub: username, uid, iat: now, exp: now + cfg.jwtExp},
+        cfg.jwtSecret,
+    );
+}
+
+/* ═══════════ 注册路由 ═══════════ */
+
+export function registerAuthRoutes(app: Hono<AppEnv>) {
+    /* ── POST /api/auth/login ── */
+    app.post(
+        "/api/auth/login",
+        zValidator("json", authBodySchema, zodHook as any),
+        async (c) => {
+            const {username, password} = c.req.valid("json");
+            const user = await findUser(username);
+            if (!user || user.password !== password)
+                throw new AppError("AUTH_ERROR", "Invalid username or password");
+            return c.json(ok(await issueToken(user.id, username)));
+        },
+    );
+
+    /* ── POST /api/auth/register ── */
+    app.post(
+        "/api/auth/register",
+        zValidator("json", authBodySchema, zodHook as any),
+        async (c) => {
+            const {username, password} = c.req.valid("json");
+            if (await findUser(username))
+                throw new AppError("AUTH_ERROR", `User "${username}" already exists`);
+            await run(
+                `INSERT INTO ${q(cfg.authTable)} (username, password)
+                 VALUES ($1, $2)`,
+                [username, password],
+            );
+            const user = await findUser(username);
+            return c.json(ok(await issueToken(user.id, username)));
+        },
+    );
+
+    /* ── GET /api/auth/profile — 获取当前用户资料（去掉 id 和 password） ── */
+    app.get("/api/auth/profile", async (c) => {
+        const userId = c.get("userId");
+        const rows = await run(
+            `SELECT *
+             FROM ${q(cfg.authTable)}
+             WHERE id = $1`,
+            [userId],
+        );
+        if (rows.length === 0) throw new AppError("AUTH_ERROR", "User not found");
+        const data = {...(rows[0] as any)};
+        delete data.id;
+        delete data.password;
+        return c.json(ok(data));
+    });
+
+    /* ── POST /api/auth/profile — 增量更新当前用户资料 ── */
+    app.post("/api/auth/profile", async (c) => {
+        const userId = c.get("userId");
+        const body = (await c.req.json()) as Record<string, unknown>;
+        const meta = getTable(cfg.authTable)!;
+
+        const sets: string[] = [];
+        const vals: unknown[] = [];
+        let n = 1;
+        for (const [k, v] of Object.entries(body)) {
+            /* 只更新表中实际存在的列（id 不允许修改） */
+            if (meta.colMap.has(k) && k !== "id") {
+                sets.push(`${q(k)} = $${n++}`);
+                vals.push(v);
+            }
+        }
+        if (sets.length === 0) return c.json(ok(null));
+
+        vals.push(userId);
+        await run(
+            `UPDATE ${q(cfg.authTable)}
+             SET ${sets.join(", ")}
+             WHERE id = $${n}`,
+            vals,
+        );
+        return c.json(ok(null));
+    });
+}

package/bin/restbase.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../server.ts";

package/client/package.json

@@ -0,0 +1,22 @@
+{
+    "name": "@dtdyq/restbase-client",
+    "version": "1.0.0",
+    "description": "Type-safe, zero-dependency client for RestBase API — works in Browser / Node / Bun / Deno",
+    "keywords": ["restbase", "rest", "api", "client", "typescript", "query-builder"],
+    "license": "MIT",
+    "type": "module",
+    "main": "./restbase-client.ts",
+    "module": "./restbase-client.ts",
+    "types": "./restbase-client.ts",
+    "exports": {
+        ".": {
+            "types": "./restbase-client.ts",
+            "bun": "./restbase-client.ts",
+            "import": "./restbase-client.ts",
+            "default": "./restbase-client.ts"
+        }
+    },
+    "files": [
+        "restbase-client.ts"
+    ]
+}