@devflow-cc/react

v1.2.0-beta.6

Published

4 months ago

一个功能强大的React库，用于构建数据驱动的应用程序，支持实时通信、身份验证和数据库操作

0High
0Medium
0Low

wssgryx

xsahxl

react database api authentication websocket typescript supabase-alternative

@devflow-cc/react

一个功能强大的 React 库，用于构建数据驱动的应用程序，支持实时通信、身份验证和数据库操作。

🏗️ 模块架构

DevFlow 采用模块化设计，提供清晰的功能分离：

核心模块

devflow.auth - 认证模块（登录、注册、用户信息管理）
devflow.users - 用户管理模块（管理员功能）
devflow.data - 数据操作模块（CRUD 操作）
devflow.table - 表管理模块（表结构管理）
devflow.audit - 审计日志模块（操作记录）
devflow.websocket - 实时通信模块（WebSocket）

简化接口

devflow.from() - 数据操作简化写法
devflow.schema - 表管理简化写法（兼容旧版本）

🔧 最新更新

v1.2.1

✅ 参数传递统一: 统一使用 request_body 传递所有参数，包括分页参数
✅ 后端 API 优化: 移除 Query 参数，简化后端代码逻辑
✅ 前端删除方法增强: 支持 hard_delete 参数，支持软删除和硬删除
✅ API 文档更新: 更新参数传递方式说明，确保前后端对齐

v1.2.0

✅ TypeScript 重构: 完全使用 TypeScript 重写，提供完整的类型安全
✅ 模块化架构: 将大型文件拆分为小的模块，提高代码可维护性
✅ 数据模块优化: 合并 DataModule 和 QueryBuilder，简化架构
✅ 客户端架构优化: 合并 DevFlowClient 和 Factory，简化文件结构
✅ 文件命名优化: 重命名 devflow-client.ts 为 client.ts，更简洁
✅ 文件结构优化: 重命名 http-client.ts 为 http.ts，client.ts 提升到 src 根目录
✅ Context 优化: 重命名 context 目录为 provider，提供 React Provider 支持
✅ Token 存储优化: 支持自定义 token 存储键名，默认使用 localStorage 和'devflow-token'
✅ 新增用户管理模块: 支持完整的用户 CRUD 操作
✅ 新增用户列表查询、激活/停用、角色设置功能
✅ 分离认证模块和用户管理模块: 避免功能冲突
✅ 新增管理员创建用户、重置密码等功能
✅ 优化 API 设计: 区分用户自己的操作和管理员操作
✅ 新增审计日志模块: 支持完整的审计功能
✅ 新增表管理功能: 支持表名验证和前缀配置
✅ 完善用户管理参数说明和响应格式
✅ 新增 WebSocket 实时通信功能
✅ 统一表结构管理 API 命名规范

📦 安装

npm install @devflow-cc/react

🚀 快速开始

基础使用

import { createClient, devflow } from "@devflow-cc/react";

const client = createClient({
  baseURL: "http://localhost:8000",
  apiVersion: "v1",
  timeout: 10000,
  language: "zh",
});

// 使用数据操作
const result = await client.data.from("users").eq("status", "active").select();

关于 baseURL 与 apiVersion

baseURL 仅填写服务根地址（协议+主机+端口），不要包含 /api 路径。
实际请求地址由库自动拼接：{baseURL}/api/{apiVersion}。
示例：当 baseURL = 'http://114.55.144.154' 且 apiVersion = 'v1' 时，请求会发往 http://114.55.144.154/api/v1。

// 正确
devflow.setConfig({ baseURL: "http://114.55.144.154", apiVersion: "v1" });

// 不推荐（会导致路径变为 http://.../api/v1/api/v1）
// devflow.setConfig({ baseURL: 'http://114.55.144.154/api/v1' });

运行时动态更新配置（即时生效）

devflow.setConfig() 现在会在任何配置更新后，自动重建内部 HTTP 客户端与模块，确保如 baseURL、apiVersion、headers、timeout 等变更立即生效。

// 初始化后可随时切换后端地址或版本
devflow.setConfig({ baseURL: "http://localhost:8000" });
// ... 一段时间后
devflow.setConfig({ baseURL: "http://114.55.144.154", apiVersion: "v2" });

Token 存储配置

DevFlow 默认将 token 存储在 localStorage 中，键名为 devflow-token。你可以通过 tokenKey 配置自定义键名：

错误处理配置

DevFlow 提供了强大的错误处理机制，支持自定义错误处理器和自动重试功能：

import { createClient } from "@devflow-cc/react";

// 自定义错误处理器
const customErrorHandler = (error) => {
  console.error("请求错误:", {
    message: error.detail,
    code: error.error_code,
    status: error.status_code,
    timestamp: error.timestamp,
  });

  // 根据错误类型执行不同处理逻辑
  switch (error.status_code) {
    case 401:
      // 处理未授权错误
      console.log("需要重新登录");
      break;
    case 403:
      // 处理权限不足错误
      console.log("权限不足");
      break;
    case 500:
      // 处理服务器错误
      console.log("服务器错误，请稍后重试");
      break;
    default:
      console.log("其他错误");
  }
};

const client = createClient({
  baseURL: "http://localhost:8000",
  apiVersion: "v1",
  timeout: 10000,
  language: "zh",
  errorHandler: {
    onError: customErrorHandler,
    retry: 3, // 自动重试3次
  },
});

// 动态更新错误处理器
client.config.setErrorHandler((error) => {
  console.log("新的错误处理器:", error.detail);
}, 2);

// 清除错误处理器
client.config.clearErrorHandler();

错误处理特性：

✅ 自定义错误处理器: 可以设置自定义的错误处理函数
✅ 自动重试机制: 支持配置重试次数，使用指数退避策略
✅ 错误分类处理: 根据 HTTP 状态码执行不同的处理逻辑
✅ 动态更新: 可以在运行时动态更新错误处理器
✅ 错误信息国际化: 支持多语言错误消息

// 创建客户端时配置
const client = createClient({
  baseURL: "http://localhost:8000",
  tokenKey: "myapp-auth-token", // 自定义token键名
});

// 或者动态更新配置
devflow.setConfig({
  tokenKey: "custom-token-key",
});

React Provider 使用

import { DevFlowProvider, useDevFlow } from "@devflow-cc/react";

function App() {
  return (
    <DevFlowProvider
      config={{
        baseURL: "http://localhost:8000",
        tokenKey: "myapp-token",
      }}
    >
      <MyComponent />
    </DevFlowProvider>
  );
}

function MyComponent() {
  const { client } = useDevFlow();

  const handleLogin = async () => {
    const result = await client.auth.signInWithPassword({
      username: "user",
      password: "password",
    });
  };

  return <button onClick={handleLogin}>登录</button>;
}

2. 身份验证

// 登录
const { data, error } = await devflow.auth.signInWithPassword({
  username: "your-username",
  password: "your-password",
});

if (data) {
  console.log("登录成功:", data.user);
} else {
  console.error("登录失败:", error);
}

// 注册
const { data, error } = await devflow.auth.signUp({
  username: "new-user",
  email: "[email protected]",
  password: "password123",
  full_name: "New User",
});

// 获取当前用户信息
const { data, error } = await devflow.auth.getUser();

// 更新自己的用户信息
const { data, error } = await devflow.auth.updateUser({
  full_name: "Updated Name",
  bio: "Updated bio",
});

// 修改密码
const { data, error } = await devflow.auth.changePassword({
  current_password: "oldpassword",
  new_password: "newpassword",
});

3. 用户管理（管理员功能）

// 获取用户列表
const { items, total, page, page_size } = await devflow.users.getUsers({
  page: 1,
  page_size: 20,
  search: "john",
  is_active: true,
  role: "user",
});

// 获取用户详情
const { data, error } = await devflow.users.getUser("user-id");

// 管理员创建用户
const { data, error } = await devflow.users.createUser({
  username: "newuser",
  email: "[email protected]",
  password: "password123",
  full_name: "New User",
  is_active: true,
});

// 管理员更新用户
const { data, error } = await devflow.users.updateUser("user-id", {
  full_name: "Updated Name",
  is_active: false,
  bio: "Updated bio",
});

// 删除用户
const { error } = await devflow.users.deleteUser("user-id");

// 激活用户
const { data, error } = await devflow.users.activateUser("user-id");

// 停用用户
const { data, error } = await devflow.users.deactivateUser("user-id");

// 设置用户角色
const { data, error } = await devflow.users.setUserRoles("user-id", [
  "admin",
  "user",
]);

// 重置用户密码
const { data, error } = await devflow.users.resetUserPassword(
  "user-id",
  "newpassword"
);

4. 审计日志模块

// 获取审计日志列表
const { data, error } = await devflow.audit.getLogs({
  user_id: "user-id",
  action: "user_login",
  resource_type: "user",
  status: "success",
  page: 1,
  page_size: 20,
});

// 获取我的审计日志
const { data, error } = await devflow.audit.getMyLogs({
  days: 30,
  action: "data_insert",
  page: 1,
  page_size: 20,
});

// 获取用户活动摘要
const { data, error } = await devflow.audit.getActivitySummary({
  user_id: "user-id",
  days: 30,
});

// 获取系统审计统计
const { data, error } = await devflow.audit.getSystemStats({
  days: 7,
});

5. 数据操作

DevFlow 提供了两种数据操作方式：

方式一：简化写法（推荐）

// 基础查询
const { items, total, page, pageSize } = await devflow
  .from("users")
  .eq("status", "active")
  .order("created_at", "desc")
  .select(["id", "name", "email"]);

// 分页查询
const { items, total, page, pageSize } = await devflow
  .from("users")
  .eq("status", "active")
  .order("created_at", "desc")
  .page(1, 10)
  .select();

// 获取单条记录
const { data, error } = await devflow.from("users").get("user-id");

// 插入数据
const { data, error } = await devflow.from("users").insert({
  username: "newuser",
  email: "[email protected]",
  full_name: "New User",
});

// 更新数据
const { data, error } = await devflow.from("users").eq("id", "user-id").update({
  full_name: "Updated Name",
});

// 删除数据（软删除）
const { data, error } = await devflow
  .from("users")
  .eq("status", "deleted")
  .delete();

// 删除数据（硬删除）
const { data, error } = await devflow
  .from("users")
  .eq("status", "deleted")
  .delete(false, true); // confirmAll=false, hardDelete=true

方式二：模块化写法

// 使用数据模块
const { items, total } = await devflow.data
  .from("users")
  .eq("status", "active")
  .select(["id", "name", "email"]);

// 插入数据
const { data, error } = await devflow.data.from("users").insert({
  username: "newuser",
  email: "[email protected]",
});

// 更新数据
const { data, error } = await devflow.data
  .from("users")
  .eq("id", "user-id")
  .update({
    full_name: "Updated Name",
  });

// 删除数据（软删除）
const { data, error } = await devflow.data
  .from("users")
  .eq("status", "deleted")
  .delete();

// 删除数据（硬删除）
const { data, error } = await devflow.data
  .from("users")
  .eq("status", "deleted")
  .delete(false, true); // confirmAll=false, hardDelete=true

操作方法（终止方法）：

insert() - 插入数据
update() - 更新数据
delete(confirmAll?, hardDelete?) - 删除数据（支持软删除和硬删除）
select() - 查询数据
get() - 获取单条记录

6. 表结构管理

// 创建表
const { data, error } = await devflow.table.createTable({
  name: "products",
  columns: [
    { name: "id", type: "uuid", primary_key: true },
    { name: "name", type: "varchar", length: 255, not_null: true },
    { name: "price", type: "decimal", precision: 10, scale: 2 },
    { name: "category_id", type: "uuid", foreign_key: "categories.id" },
  ],
});

// 获取表列表
const { data, error } = await devflow.table.getTables({
  page: 1,
  page_size: 20,
  search: "user",
});

// 获取表信息
const { data, error } = await devflow.table.getTableInfo("users");

// 更新表结构
const { data, error } = await devflow.table.updateTable("users", {
  add_columns: [{ name: "avatar", type: "varchar", length: 500 }],
  modify_columns: [{ name: "email", type: "varchar", length: 100 }],
});

// 删除表
const { data, error } = await devflow.table.deleteTable("temp_table");

// 获取表统计信息
const { data, error } = await devflow.table.getTableStats("users");

// 验证表名是否合法
const { data, error } = await devflow.table.validateTableName("my_table");

// 获取表前缀配置信息
const { data, error } = await devflow.table.getTablePrefixInfo();

7. WebSocket 实时通信

// 建立WebSocket连接
const ws = devflow.websocket.connect({
  token: "your-jwt-token",
  onMessage: (data) => {
    console.log("收到实时数据:", data);
  },
  onError: (error) => {
    console.error("WebSocket错误:", error);
  },
  onClose: () => {
    console.log("WebSocket连接已关闭");
  },
});

// 订阅表变更
ws.subscribe("users", (data) => {
  console.log("users表数据变更:", data);
});

// 取消订阅
ws.unsubscribe("users");

// 关闭连接
ws.close();

🏗️ 架构设计

模块化结构

src/
├── core/                 # 核心模块
│   ├── config.ts        # 配置管理
│   └── http-client.ts   # HTTP客户端
├── modules/             # 功能模块
│   ├── auth.ts         # 认证模块
│   ├── users.ts        # 用户管理模块
│   ├── audit.ts        # 审计日志模块
│   ├── query-builder.ts # 数据查询构建器
│   ├── table.ts        # 表管理模块
│   └── websocket.ts    # WebSocket模块
├── client/             # 客户端
│   ├── devflow-client.ts # 主客户端类
│   └── factory.ts      # 工厂函数和单例
├── types/              # 类型定义
│   └── index.ts        # 所有类型定义
└── index.ts            # 主入口文件

核心特性

TypeScript 支持: 完整的类型安全，提供优秀的开发体验
模块化设计: 每个功能模块独立，便于维护和扩展
智能过滤: 自动忽略空值条件，提高代码简洁性
标准字段管理: 自动管理标准字段，避免用户误操作
国际化支持: 内置多语言支持
错误处理: 统一的错误处理机制
实时通信: WebSocket 实时数据推送
审计日志: 完整的操作审计功能

🧪 测试

# 运行所有测试
npm test

# 运行单元测试
npm run test:unit

# 运行集成测试
npm run test:integration

# 运行端到端测试
npm run test:e2e

# 运行真实API测试
npm run test:real-api

📦 构建

# 开发模式构建
npm run dev

# 生产模式构建
npm run build

# 类型检查
npm run type-check

🤝 贡献

欢迎提交 Issue 和 Pull Request！

🚀 新功能

TypeScript 重构: 完全使用 TypeScript 重写，提供完整的类型安全
模块化架构: 将大型文件拆分为小的模块，提高代码可维护性
用户管理模块: 添加完整的用户 CRUD 操作
审计日志模块: 添加完整的审计功能
表管理模块: 添加完整的表结构管理功能
WebSocket 模块: 添加实时通信功能

📊 测试统计

总测试用例: 111 个
语句覆盖率: 98.37%
分支覆盖率: 92.85%
函数覆盖率: 95.74%
行覆盖率: 99.14%

🔧 重要 API 变更

统一 API 设计: 所有操作方法都采用前置调用方式，条件在前，操作在后
select 作为终止方法: 将 select() 改为终止方法，移除 query() 方法
链式调用规则: insert(), update(), delete(), select(), get() 必须在链式调用最后调用
错误消息格式: 统一错误消息格式，包含 HTTP 状态码

📄 许可证

MIT License

🔗 相关链接

�� 支持

如果你遇到任何问题或有疑问，请：

查看问题反馈
创建新的 Issue
联系作者: [email protected]

📋 标准字段列表

id - 主键 ID（自动生成）
created_by - 创建者 ID（自动设置）
created_at - 创建时间（自动设置）
updated_by - 更新者 ID（自动设置）
updated_at - 更新时间（自动设置）
deleted_by - 删除者 ID（软删除时自动设置）
deleted_at - 删除时间（软删除时自动设置）

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@devflow-cc/react

🏗️ 模块架构

核心模块

简化接口

🔧 最新更新

v1.2.1

v1.2.0

📦 安装

🚀 快速开始

基础使用

关于 baseURL 与 apiVersion

运行时动态更新配置（即时生效）

Token 存储配置

错误处理配置

React Provider 使用

2. 身份验证

3. 用户管理（管理员功能）

4. 审计日志模块

5. 数据操作

方式一：简化写法（推荐）

方式二：模块化写法

6. 表结构管理

7. WebSocket 实时通信

🏗️ 架构设计

模块化结构

核心特性

🧪 测试

📦 构建

🤝 贡献

🚀 新功能

📊 测试统计

🔧 重要 API 变更

📄 许可证

🔗 相关链接

�� 支持

📋 标准字段列表