@dtdyq/restbase 1.0.0 → 2.0.0

package/README.md

@@ -15,28 +15,81 @@
 
 ## 快速开始
 
+### 方式一：全局安装（推荐）
+
+```bash
+bun install -g @dtdyq/restbase
+```
+
+安装后在任意目录使用 `restbase` 命令。所有配置通过 `.env` 文件读取：
+
+```bash
+# 生成 .env 配置模板
+restbase env
+
+# 前台启动（读取当前目录 .env）
+restbase run
+
+# 后台启动（daemon 模式）
+restbase start
+
+# 查看运行中的实例（含健康状态）
+restbase status
+
+# 查看某个实例的实时日志
+restbase log <pid>
+
+# 停止
+restbase stop <pid>        # 停止指定实例
+restbase stop all          # 停止所有实例
+```
+
+更新到最新版：
+
+```bash
+bun install -g @dtdyq/restbase@latest
+```
+
+### 方式二：从源码运行
+
 ```bash
 bun install
-bun run server.ts
+bun run src/server.ts
 ```
 
+### 验证
+
 ```bash
-# 健康检查
+# 健康检查（返回实例状态 + 资源占用）
 curl http://localhost:3333/api/health
+# → { "code": "OK", "data": { "status": "healthy", "port": 3333, "pid": 12345, "uptime": 60, "memory": {...}, "cpu": {...} } }
 
 # Basic Auth 查询
 curl -u admin:admin http://localhost:3333/api/data/products
 ```
 
+### 前端客户端
+
+独立 npm 包，零依赖：
+
+```bash
+bun add @dtdyq/restbase-client
+```
+
+```ts
+import RestBase, { gt } from "@dtdyq/restbase-client";
+
+const rb = new RestBase();  // 同源部署不传参
+await rb.auth.login("admin", "admin");
+const data = await rb.table("products").query().where(gt("price", 100)).data();
+```
+
+详见 [client/README.md](client/README.md)。
+
 ## 构建与部署
 
 ```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 run build              # 编译为当前平台独立二进制
 
 # 运行二进制（无需 Bun 运行时）
 ./restbase
@@ -46,6 +99,7 @@ bun run build:windows      # Windows x64
 
 | 变量                        | 说明                         | 默认值                 |
 |:--------------------------|:---------------------------|:--------------------|
+| `SVR_NAME`                | 实例名称（`status` 中显示）         | 空                   |
 | `SVR_PORT`                | 服务端口                       | `3333`              |
 | `SVR_STATIC`              | 静态文件目录（前端托管）               | 空                   |
 | `SVR_API_LIMIT`           | API 限流（每秒每接口请求数）           | `100`               |
@@ -65,7 +119,7 @@ bun run build:windows      # Windows x64
 ## 测试
 
 ```bash
-bun test rest.test.ts    # 137+ 用例
+bun test src/rest.test.ts    # 137+ 用例
 ```
 
 ## 文档
@@ -73,30 +127,66 @@ bun test rest.test.ts    # 137+ 用例
 | 文档                                               | 内容                                                |
 |:-------------------------------------------------|:--------------------------------------------------|
 | [documents/server.md](documents/server.md)       | 服务端详细文档 — 配置、全部 API 接口说明与示例、日志、部署                 |
-| [documents/client.md](documents/client.md)       | 前端客户端文档 — 安装、API 速查、QueryBuilder 链式调用、类型安全 SELECT |
+| [client/README.md](client/README.md)             | 前端客户端文档 — 安装、API 速查、QueryBuilder 链式调用、类型安全 SELECT |
 | [documents/db_design.md](documents/db_design.md) | 数据库设计指南 — 表结构规范、约束、索引、设计模式与检查清单                   |
 | [documents/design.md](documents/design.md)       | 需求与设计文档 — 架构设计、技术规格、完整接口定义                        |
 
+## CLI 命令
+
+```
+restbase <command> [arguments]
+
+Commands:
+  run              前台启动服务（读取当前目录 .env）
+  start            后台启动（daemon 模式）
+  stop <pid|all>   停止后台实例
+  status           查看运行中的实例（含健康检查）
+  log <pid>        实时查看实例日志
+  env              在当前目录生成 .env 配置模板
+  version          显示版本号
+  help             显示帮助
+```
+
+所有配置通过 `.env` 文件管理，可在 `.env` 中设置 `SVR_NAME` 为实例命名。
+
+实例元数据和默认日志存放在 `~/.restbase/`：
+
+```
+~/.restbase/
+├── instances/          # 实例元数据（name/port/pid/logPath）
+│   ├── 12345.json
+│   └── 23456.json
+└── logs/               # daemon 默认日志目录
+    ├── 3333.log
+    ├── 3333.out
+    └── 8080.log
+```
+
 ## 文件结构
 
 ```
 restbase/
-├── server.ts            # 入口
-├── types.ts             # 配置 + 类型
-├── db.ts                # 数据库
-├── auth.ts              # 鉴权
-├── crud.ts              # CRUD 路由
-├── query.ts             # SQL 生成
-├── logger.ts            # 日志
+├── bin/
+│   └── restbase.ts         # CLI 入口（run/start/stop/status）
+├── src/
+│   ├── server.ts           # 服务启动
+│   ├── types.ts            # 配置 + 类型 + Zod Schema
+│   ├── db.ts               # 数据库
+│   ├── auth.ts             # 鉴权
+│   ├── crud.ts             # CRUD 路由
+│   ├── query.ts            # SQL 生成
+│   ├── logger.ts           # 日志
+│   └── rest.test.ts        # 集成测试
 ├── client/
-│   └── restbase-client.ts   # 前端客户端
+│   ├── restbase-client.ts  # 前端客户端（独立 npm 包 @dtdyq/restbase-client）
+│   ├── README.md           # 客户端文档
+│   └── package.json
 ├── documents/
-│   ├── design.md        # 需求设计文档
-│   ├── server.md        # 服务端文档
-│   └── client.md        # 客户端文档
-├── init.sql             # 初始化 SQL
-├── rest.test.ts         # 集成测试
-├── .env / .env.test     # 环境配置
+│   ├── design.md           # 需求设计文档
+│   ├── server.md           # 服务端文档
+│   └── db_design.md        # 数据库设计指南
+├── init.sql                # 初始化 SQL
+├── .env / .env.test        # 环境配置
 └── package.json
 ```