@lark-apaas/devtool-kits 0.1.0-alpha.7 → 0.1.0-alpha.8

package/README.md

@@ -1,31 +1,110 @@
 # Fullstack Toolkits
 
-A comprehensive toolkit for NestJS applications, providing middleware utilities and development tools.
+面向 NestJS 全栈项目的综合工具包，提供开箱即用的开发中间件、工具函数和辅助功能，帮助您快速搭建高效的开发环境。
 
-## Features
+## 功能特性
 
-- 🔧 **Development Middleware** - Dev-logs middleware for request/response logging and tracing
-- 📚 **OpenAPI Enhancement** - Enhanced OpenAPI/Swagger documentation with source code information
-- 🛠️ **Utility Functions** - Common utilities for path normalization and more
-- 🔍 **Path Matching** - Powerful path pattern matching for OpenAPI/Swagger/NestJS routes
+本 SDK 导出三大核心模块，让您可以快速集成到项目中：
 
-## Installation
+### 📦 开箱即用的中间件 (Middlewares)
+- **Dev Logs 中间件** - 查看和查询应用日志，支持 Trace ID 追踪和路径过滤
+- **Collect Logs 中间件** - 收集客户端日志并自动存储到文件
+- **OpenAPI 中间件** - 增强 OpenAPI 文档，自动添加源代码引用信息
+
+### 🛠️ 实用工具函数 (Utils)
+- **路径规范化** - 自动处理路径格式，确保一致性
+
+### 🔌 通用脚本 (Helpers)
+- **Drizzle Schema 后处理** - 自动优化 Drizzle Kit 生成的 schema 文件
+  - 中文表名转拼音标识符
+  - 自动替换自定义类型（user_profile、file_attachment）
+  - 添加系统字段注释（_created_at、_updated_at 等）
+  - 优化 import 语句和代码格式
+
+## 安装
 
 ```bash
 npm install @apaas/fullstack-toolkits
-# or
+# 或
 yarn add @apaas/fullstack-toolkits
 ```
 
-## Usage
+## 快速开始
+
+只需三步，即可为您的项目添加强大的开发工具：
+
+```typescript
+import {
+  registerMiddlewares,
+  createDevLogsMiddleware,
+  createCollectLogsMiddleware,
+  createOpenapiMiddleware
+} from '@apaas/fullstack-toolkits';
+
+// 在 rspack/webpack 或 Vite 开发服务器中注册
+registerMiddlewares(devServer.app, [
+  createDevLogsMiddleware({ logDir: './logs' }),
+  createCollectLogsMiddleware({ logDir: './logs' }),
+  createOpenapiMiddleware({ openapiFilePath: './openapi.json' }),
+], {
+  basePath: '/api',
+  isDev: true,
+  rootDir: __dirname
+});
+```
+
+完成！现在您可以：
+- 📊 访问 `GET /api/dev/logs/trace/recent` 查看最近的 API 调用
+- 📝 通过 `POST /api/dev/logs/collect` 收集客户端日志
+- 📚 访问 `GET /api/dev/openapi.json` 获取增强的 API 文档
+
+## 导出内容
+
+### 中间件 (Middlewares)
+```typescript
+import {
+  createDevLogsMiddleware,      // 日志查询中间件
+  createCollectLogsMiddleware,  // 日志收集中间件
+  createOpenapiMiddleware,      // OpenAPI 增强中间件
+} from '@apaas/fullstack-toolkits';
+```
+
+### 工具函数 (Utils)
+```typescript
+import {
+  matchesPathPattern,    // 路径模式匹配
+  extractPathParams,     // 提取路径参数
+  normalizeBasePath,     // 路径规范化
+} from '@apaas/fullstack-toolkits';
+```
+
+### 辅助函数 (Helpers)
+```typescript
+import {
+  registerMiddlewares,       // 统一注册中间件
+  postprocessDrizzleSchema,  // 后处理 Drizzle Schema 文件
+} from '@apaas/fullstack-toolkits';
+```
+
+### 类型定义 (Types)
+```typescript
+import type {
+  Middleware,            // 中间件联合类型
+  RouteMiddleware,       // 路由中间件类型
+  GlobalMiddleware,      // 全局中间件类型
+  MiddlewareContext,     // 中间件上下文类型
+} from '@apaas/fullstack-toolkits';
+```
 
-### Middleware Registration
+## 详细使用
 
-The toolkit supports two types of middlewares:
-- **Route Middlewares**: Mount at specific paths (e.g., `/dev/logs`, `/openapi.json`)
-- **Global Middlewares**: Apply to all requests without path mounting
+### 在不同开发服务器中集成
 
-Use the `registerMiddlewares` function to register both types:
+工具包支持两种类型的中间件：
+- **路由中间件**：挂载到特定路径（例如 `/dev/logs`、`/dev/openapi.json`）
+- **全局中间件**：应用于所有请求，无需挂载路径
+
+**用于 Rspack / Webpack 开发服务器：**
 
 ```typescript
 import {
@@ -34,17 +113,11 @@ import {
   createOpenapiMiddleware
 } from '@apaas/fullstack-toolkits';
 
-// For rspack/webpack dev server
 export default {
   devServer: {
     setupMiddlewares: (middlewares, devServer) => {
       if (devServer.app) {
         registerMiddlewares(devServer.app, [
-          // Global middlewares execute first (in array order)
-          createCorsMiddleware({ origin: '*' }),
-          createRequestLoggerMiddleware(),
-
-          // Route middlewares mount at specific paths
           createDevLogsMiddleware({ logDir: './logs' }),
           createOpenapiMiddleware({
             openapiFilePath: './openapi.json',
@@ -60,8 +133,11 @@ export default {
     }
   }
 }
+```
+
+**用于 Vite 开发服务器：**
 
-// For Vite dev server
+```typescript
 export default {
   plugins: [
     {
@@ -84,230 +160,352 @@ export default {
 }
 ```
 
-**Important Notes:**
-- Middleware execution order matches the array order
-- Place global middlewares before route middlewares
-- Global middlewares apply to all requests
-- Route middlewares only handle requests matching their mount path
+**重要提示：**
+- 中间件执行顺序与数组顺序一致
+- 全局中间件应放在路由中间件之前
+- 路由中间件仅处理匹配其挂载路径的请求
 
-### Global Middleware Examples
+## 中间件详细说明
+### Dev Logs 中间件
 
-Create custom global middlewares using the `GlobalMiddleware` interface:
+查看和查询带 Trace ID 支持的应用日志。
 
-```typescript
-import type { GlobalMiddleware } from '@apaas/fullstack-toolkits';
-
-// Example: CORS middleware
-function createCorsMiddleware(options?: { origin?: string }): GlobalMiddleware {
-  return {
-    name: 'cors',
-    createHandler: () => {
-      return (req, res, next) => {
-        res.setHeader('Access-Control-Allow-Origin', options?.origin || '*');
-        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
-        next();
-      };
-    }
-  };
-}
+**功能特性：**
+- 根据 Trace ID 查询日志条目
+- 分页浏览最近的追踪调用
+- 按 API 路径模式和 HTTP 方法过滤日志
+- 支持 OpenAPI/Swagger 路径模式
+- 分页读取日志文件
 
-// Example: Request logger
-function createRequestLoggerMiddleware(): GlobalMiddleware {
-  return {
-    name: 'request-logger',
-    enabled: (context) => context.isDev, // Only in dev mode
-    createHandler: () => {
-      return (req, res, next) => {
-        console.log(`[${new Date().toISOString()}] ${req.method} ${req.path}`);
-        next();
-      };
-    }
-  };
-}
-```
+**路由：**
+- `GET /dev/logs/app/trace/:traceId` - 根据 Trace ID 获取日志条目
+- `GET /dev/logs/trace/recent` - 获取最近的追踪调用（支持分页和过滤）
+- `GET /dev/logs/files/:fileName` - 分页获取日志文件内容
+
+**查询参数：**
 
-See `src/middlewares/examples.ts` for more global middleware examples.
+**用于 `/app/trace/:traceId`：**
+- `limit` - 返回条目的最大数量（默认：200，最大：1000）
 
-### Dev Logs Middleware
+**用于 `/trace/recent`：**
+- `page` - 页码（默认：1）
+- `pageSize` - 每页条目数（默认：10，最大：100）
+- `path` - 按 API 路径模式过滤（支持通配符）
+- `method` - 按 HTTP 方法过滤（GET、POST 等）
 
-Provides request/response logging with trace ID support.
+**用于 `/files/:fileName`：**
+- `page` - 页码（默认：1）
+- `pageSize` - 每页行数（默认：200，最大：2000）
 
-**Features:**
-- View log entries by trace ID
-- Browse recent trace calls with pagination
-- Filter logs by API path patterns
-- Support for OpenAPI/Swagger path patterns
+**响应示例：**
 
-**Routes:**
-- `GET /dev/logs/app/trace/:traceId` - Get log entries by trace ID
-- `GET /dev/logs/trace/recent` - Get recent trace calls (with pagination and path filtering)
-- `GET /dev/logs/files/:fileName` - Get log file content
+```typescript
+// GET /dev/logs/app/trace/abc123?limit=100
+{
+  file: "logs/app.log",
+  traceId: "abc123",
+  count: 5,
+  entries: [
+    { /* 日志条目 1 */ },
+    { /* 日志条目 2 */ }
+  ]
+}
 
-**Example:**
+// GET /dev/logs/trace/recent?page=1&pageSize=10&path=/api/users/*&method=POST
+{
+  file: "logs/trace.log",
+  page: 1,
+  pageSize: 10,
+  total: 150,
+  totalPages: 15,
+  path: "/api/users/*",
+  method: "POST",
+  count: 10,
+  calls: [
+    { /* 追踪调用 1 */ },
+    { /* 追踪调用 2 */ }
+  ]
+}
+
+// GET /dev/logs/files/app.log?page=1&pageSize=200
+{
+  file: "logs/app.log",
+  page: 1,
+  pageSize: 200,
+  total: 5000,
+  totalPages: 25,
+  lines: [
+    "日志行 1",
+    "日志行 2"
+  ]
+}
+```
+
+**使用示例：**
 ```typescript
+// 注册中间件
 createDevLogsMiddleware({
-  logDir: './logs', // Optional, defaults to 'logs'
+  logDir: './logs',  // 可选，默认为 'logs' 或 context.logDir
 })
+
+// 客户端使用示例
+// 获取指定 Trace ID 的日志
+fetch('/dev/logs/app/trace/abc123?limit=100')
+  .then(res => res.json())
+  .then(data => console.log(data.entries));
+
+// 按路径和方法过滤获取最近的 API 调用
+fetch('/dev/logs/trace/recent?page=1&pageSize=20&path=/api/users/*&method=POST')
+  .then(res => res.json())
+  .then(data => console.log(data.calls));
+
+// 分页读取日志文件
+fetch('/dev/logs/files/app.log?page=1&pageSize=200')
+  .then(res => res.json())
+  .then(data => console.log(data.lines));
 ```
 
-### OpenAPI Middleware
 
-Enhances OpenAPI/Swagger documentation with source code information.
+### Collect Logs 中间件
 
-**Features:**
-- Automatically enhance OpenAPI paths with controller source locations
-- Transform paths to include basePath
-- Caching support for better performance
+从客户端收集日志并存储到日志文件中。
 
-**Routes:**
-- `GET /dev/openapi.json` - Get enhanced OpenAPI documentation
+**功能特性：**
+- 通过 HTTP POST 收集客户端日志
+- 以 JSON Lines 格式存储日志
+- 自动创建日志目录
+- 可自定义日志文件名
 
-**Example:**
+**路由：**
+- `POST /dev/logs/collect` - 从客户端收集日志
+
+**请求体：**
 ```typescript
-createOpenapiMiddleware({
-  openapiPath: './openapi.json',
-  enableEnhancement: true,
-})
+{
+  level: string;        // 日志级别（info、warn、error 等）
+  message: string;      // 日志消息
+  time: string;         // ISO 时间戳字符串
+  source?: string;      // 可选的日志来源标识
+  user_id: string;      // 用户 ID
+  tenant_id: string;    // 租户 ID
+  app_id: string;       // 应用 ID
+}
 ```
 
-### Path Matching Utility
-
-Powerful path pattern matching for OpenAPI/Swagger/NestJS routes.
-
-**Supported Patterns:**
-- Exact matching: `/api/users` === `/api/users`
-- Path parameters: `/api/users/{id}` matches `/api/users/123`
-- Single wildcard: `/api/*/users` matches `/api/v1/users`
-- Recursive wildcard: `/files/**` matches `/files/a/b/c`
-- Prefix matching: `/api/users` matches `/api/users/123`
-
-**Example:**
+**响应：**
 ```typescript
-import { matchesPathPattern, extractPathParams } from '@apaas/fullstack-toolkits';
+// 成功
+{
+  success: true
+}
 
-// Match path patterns
-matchesPathPattern('/api/users/123', '/api/users/{id}'); // true
-matchesPathPattern('/api/v1/users', '/api/*/users'); // true
-matchesPathPattern('/files/a/b/c', '/files/**'); // true
+// 错误
+{
+  message: string;
+  error: { name?: string; message: string }
+}
+```
 
-// Extract path parameters
-extractPathParams('/api/users/123', '/api/users/{id}');
-// Returns: { id: '123' }
+**使用示例：**
+```typescript
+// 注册中间件
+createCollectLogsMiddleware({
+  logDir: './logs',           // 可选，默认为 'logs'
+  fileName: 'client.log',     // 可选，默认为 'client.log'
+})
 
-extractPathParams('/api/users/123/posts/456', '/api/users/{userId}/posts/{postId}');
-// Returns: { userId: '123', postId: '456' }
+// 客户端使用示例
+fetch('/dev/logs/collect', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    level: 'error',
+    message: 'Something went wrong',
+    time: new Date().toISOString(),
+    source: 'frontend',
+    user_id: 'user123',
+    tenant_id: 'tenant456',
+    app_id: 'app789'
+  })
+});
 ```
 
-### Utility Functions
+**日志文件格式：**
+日志以 JSON Lines 格式存储（每行一个 JSON 对象）：
+```
+{"level":"error","message":"Something went wrong","time":"2025-10-23T10:30:00.000Z","source":"frontend","user_id":"user123","tenant_id":"tenant456","app_id":"app789"}
+{"level":"info","message":"User logged in","time":"2025-10-23T10:31:00.000Z","user_id":"user123","tenant_id":"tenant456","app_id":"app789"}
+```
 
-```typescript
-import { normalizeBasePath } from '@apaas/fullstack-toolkits';
 
-// Normalize base path (adds leading slash, removes trailing slash)
-normalizeBasePath('api'); // '/api'
-normalizeBasePath('/api/'); // '/api'
-normalizeBasePath('api/v1'); // '/api/v1'
-```
+### OpenAPI 中间件
 
-## API Reference
+提供带源代码引用的增强版 OpenAPI/Swagger 文档。
 
-### Middleware Types
+**功能特性：**
+- 自动为 OpenAPI 路径添加控制器源代码位置
+- 为每个端点添加文件路径和行号
+- 根据上下文转换路径以包含 basePath
+- 内置缓存以提升性能
+- 支持静态和动态 OpenAPI 规范
 
-#### `RouteMiddleware`
-Route-based middleware that mounts at a specific path.
+**路由：**
+- `GET /dev/openapi.json` - 获取增强版 OpenAPI 规范
 
+**响应结构：**
 ```typescript
-interface RouteMiddleware {
-  name: string;
-  mountPath: string;  // Required - path to mount the router
-  routes?: RouteInfo[];
-  enabled?: (context: MiddlewareContext) => boolean;
-  createRouter: (context: MiddlewareContext) => Router;
+{
+  openapi: "3.0.0",
+  info: { /* OpenAPI 信息 */ },
+  paths: {
+    "/api/users": {
+      get: {
+        // ... 原始 OpenAPI 定义
+        "x-source": {
+          file: "src/controllers/user.controller.ts",
+          line: 42,
+          method: "getUsers",
+          controllerPath: "/users",
+          routePath: "/api/users"
+        }
+      }
+    }
+  }
 }
 ```
 
-**Example:**
+**使用示例：**
 ```typescript
-function createDevLogsMiddleware(options): RouteMiddleware {
-  return {
-    name: 'dev-logs',
-    mountPath: '/dev/logs',
-    createRouter: (context) => createRouter(options)
-  };
-}
+// 注册中间件
+createOpenapiMiddleware({
+  openapiFilePath: './openapi.json',     // 必需 - OpenAPI 文件路径
+  enableEnhancement: true,                // 可选 - 启用源码信息（默认：true）
+  serverDir: './src',                     // 可选 - 服务端目录用于扫描（默认为 context.rootDir）
+})
+
+// 客户端使用
+fetch('/dev/openapi.json')
+  .then(res => res.json())
+  .then(spec => {
+    // 使用增强后的 OpenAPI 规范
+    console.log(spec.paths);
+
+    // 访问源代码信息
+    const getUsersSource = spec.paths['/api/users'].get['x-source'];
+    console.log(`端点定义在 ${getUsersSource.file}:${getUsersSource.line}`);
+  });
 ```
 
-#### `GlobalMiddleware`
-Global middleware that applies to all requests.
+**增强详情：**
+
+中间件会扫描服务端代码库中的 NestJS 控制器，并为每个端点添加 `x-source` 元数据：
+- `file` - 控制器文件的相对路径
+- `line` - 定义端点处理器的行号
+- `method` - 处理器方法名
+- `controllerPath` - 来自 `@Controller()` 装饰器的基础路径
+- `routePath` - 包含 basePath 的完整路径
+
+**缓存机制：**
+增强后的 OpenAPI 规范基于文件哈希进行缓存。当源 OpenAPI 文件发生变化时，缓存会自动失效。
+
+### 工具函数
 
+#### Drizzle Schema 后处理
+
+自动优化 Drizzle Kit 生成的 PostgreSQL schema 文件，解决常见的代码质量问题。
+
+**主要功能：**
+- **中文表名处理** - 自动将中文表名转换为拼音标识符（如：用户表 → yonghu_biao）
+- **自定义类型替换** - 将 `unknown()` 类型自动替换为 `userProfile()` 或 `fileAttachment()`
+- **系统字段注释** - 为 `_created_at`、`_created_by`、`_updated_at`、`_updated_by` 添加注释
+- **Schema 转换** - 移除 `pgSchema` 声明，将 `schema.table()` 转换为 `pgTable()`
+- **Import 优化** - 自动添加缺失的导入，移除未使用的导入
+- **代码格式化** - 统一换行符、合并多余空行、添加文件头注释
+
+**使用示例：**
 ```typescript
-interface GlobalMiddleware {
-  name: string;
-  mountPath?: never;  // Must not have mountPath
-  enabled?: (context: MiddlewareContext) => boolean;
-  createHandler: (context: MiddlewareContext) => RequestHandler;
+import { postprocessDrizzleSchema } from '@apaas/fullstack-toolkits';
+
+// 在 Drizzle Kit generate 之后调用
+const stats = postprocessDrizzleSchema('./src/db/schema.ts');
+
+if (stats) {
+  console.log(`处理完成：`);
+  console.log(`- 替换了 ${stats.replacedUnknown} 个未知类型`);
+  console.log(`- 未匹配的自定义类型: ${stats.unmatchedUnknown.length}`);
 }
 ```
 
-**Example:**
-```typescript
-function createCorsMiddleware(): GlobalMiddleware {
-  return {
-    name: 'cors',
-    createHandler: () => (req, res, next) => {
-      res.setHeader('Access-Control-Allow-Origin', '*');
-      next();
-    }
-  };
+**配合 Drizzle Kit 使用：**
+```json
+// package.json
+{
+  "scripts": {
+    "db:generate": "drizzle-kit generate && node -e \"require('@apaas/fullstack-toolkits').postprocessDrizzleSchema('./src/db/schema.ts')\""
+  }
 }
 ```
 
-#### `Middleware`
-Union type of route-based and global middlewares.
-
+**处理前后对比：**
 ```typescript
-type Middleware = RouteMiddleware | GlobalMiddleware;
-```
+// 处理前
+export const 用户表 = workspace_xxx.table("user_table", {
+  // TODO: failed to parse database type 'user_profile'
+  profile: unknown("profile"),
+  _created_at: timestamp("_created_at"),
+});
 
-#### `MiddlewareContext`
-```typescript
-interface MiddlewareContext {
-  basePath: string;
-  isDev: boolean;
-  rootDir: string;
-  [key: string]: any;
-}
-```
+// 处理后
+/** auto generated, do not edit */
+import { pgTable, timestamp } from "drizzle-orm/pg-core"
+import { userProfile } from "./types"
 
-### Core Functions
+export const yonghu_biao = pgTable("user_table", {
+  profile: userProfile("profile"),
+  // System field: Creation time (auto-filled, do not modify)
+  _created_at: timestamp("_created_at"),
+});
+```
 
-#### `registerMiddlewares(server, middlewares, options?): Promise<void>`
-Register middlewares for Express-compatible servers or Vite dev server.
+#### 路径匹配
 
-**Parameters:**
-- `server` - Express app or Vite middleware instance
-- `middlewares` - Array of middleware objects (route or global)
-- `options` - Optional context configuration
+强大的路径模式匹配功能，适用于 OpenAPI/Swagger/NestJS 路由。
 
-**Returns:** Promise that resolves when all middlewares are registered
+**支持的模式：**
+- 精确匹配：`/api/users` === `/api/users`
+- 路径参数：`/api/users/{id}` 匹配 `/api/users/123`
+- 单层通配符：`/api/*/users` 匹配 `/api/v1/users`
+- 递归通配符：`/files/**` 匹配 `/files/a/b/c`
+- 前缀匹配：`/api/users` 匹配 `/api/users/123`
 
-**Example:**
+**使用示例：**
 ```typescript
-await registerMiddlewares(devServer.app, [
-  createCorsMiddleware(),
-  createDevLogsMiddleware({ logDir: './logs' })
-], {
-  basePath: '/api',
-  isDev: true,
-  rootDir: __dirname
-});
+import { matchesPathPattern, extractPathParams } from '@apaas/fullstack-toolkits';
+
+// 匹配路径模式
+matchesPathPattern('/api/users/123', '/api/users/{id}'); // true
+matchesPathPattern('/api/v1/users', '/api/*/users'); // true
+
+// 提取路径参数
+extractPathParams('/api/users/123', '/api/users/{id}');
+// 返回：{ id: '123' }
+
+extractPathParams('/api/users/123/posts/456', '/api/users/{userId}/posts/{postId}');
+// 返回：{ userId: '123', postId: '456' }
 ```
 
-### Utility Functions
+#### 路径规范化
 
-#### `normalizeBasePath(basePath): string`
-Normalize base path to ensure it starts with '/' and has no trailing slash.
+```typescript
+import { normalizeBasePath } from '@apaas/fullstack-toolkits';
+
+// 规范化基础路径（添加前导斜杠，移除尾部斜杠）
+normalizeBasePath('api'); // '/api'
+normalizeBasePath('/api/'); // '/api'
+normalizeBasePath('api/v1'); // '/api/v1'
+```
 
-## License
+## 许可证
 
 MIT
+