Dataway

中文 · English

内嵌于 Java 应用的数据 API 开发框架，集数据查询、转换、聚合与接口发布于一体。

Website · Documentation · Blog · AI 文档索引

📖 简介 | Introduction

Dataway 提供从脚本开发到 API 发布的完整能力。开发者使用 SQL 或 DataQL 编写数据处理逻辑，在控制台完成编辑、调试和发布，应用通过 HTTP 或 Java 调用已发布的接口。

框架内置 DataQL 语言与执行引擎，支持查询数据库、调用 Java 服务、转换数据结构和聚合多个来源的结果。适用于报表看板、列表与详情查询、表单提交及服务聚合，减少重复的数据访问和接口代码。

✨ 核心特性 | Features

⚙️ 框架特点 (Framework Characteristics)

内嵌应用：以 JAR 接入现有 Java 项目，支持 Spring、Solon、Hasor。
统一执行：SQL 与 DataQL 共用 API 管理、参数处理、拦截和结果输出流程。
复用宿主：接入应用的数据源、业务服务、登录身份和事务管理。
按需组合：引擎可独立使用，控制台可独立部署，元数据存储和结果处理器均可替换。

🔋 基础能力 (Capabilities)

API 管理：
- 可视化操作：编辑、调试、测试、发布和停用接口，查看发布历史。
- 程序化管理：通过 Java 接口或管理 HTTP API 维护定义和版本。
- 草稿与发布版分离，修改在再次发布后生效；版本检查用于检测并发更新冲突。
数据查询与转换：
- DataQL 语言：使用表达式、函数和转换模板筛选字段、计算值、构造嵌套结果。
- SQL 执行器：支持查询、更新、动态 SQL、分页、类型处理和事务。
- 数据源接入：按名称访问多个数据源，组合数据库与应用服务的结果。
请求与响应：
- 请求参数：接收 URL 参数、JSON、表单和上传文件，通过 Web 函数读写 Header 与 Cookie。
- 结果处理器：输出结构化结果、原始值、CSV、文本和验证码图片，支持二进制响应与自定义处理器。
- 控制台按响应类型预览 JSON、文本、表格和图像，并提供文件下载。
接口调用与文档：
- 通过 HTTP 访问已发布 API，或使用 ApiService 从 Java 按路径、标识直接调用。
- 文档生成：生成 OpenAPI 3.x 和 Swagger 2.0 文档，配合 Swagger UI 展示和调用接口。
身份与扩展：
- 身份鉴权：接入应用登录体系，按身份控制 API 访问和管理操作。
- 管理拦截器与 API 拦截器：接入审计、校验、缓存等应用逻辑。
- 引擎扩展：注册 Java 函数、应用对象、代码片段和自定义作用域。
元数据存储：
- JDBC 或 Nacos 保存接口定义、草稿和发布记录。
- 支持表与字段映射、宿主事务整合和自定义存储提供者。

💡 为何选择 Dataway？ | Why Dataway

减少重复开发：通过 SQL 和脚本实现常见数据接口，在控制台完成参数调试与结果预览。
按业务组织结果：一次 API 调用可查询多个数据源、调用应用服务，并按前端需要转换和聚合数据。
接入现有工程：保留应用的登录、数据源和事务配置，通过框架适配器接入现有 Web 容器。
按需扩展能力：使用 UDF、代码片段、拦截器和结果处理器扩展处理流程，Java 引擎也可独立运行。

🚀 使用介绍

1. 引入依赖

以 Spring Boot 项目为例，引入框架整合、JDBC 元数据存储和 SQL 执行扩展：

<!-- Spring 框架整合，包含核心与控制台资源 -->
<dependency>
    <groupId>net.hasor</groupId>
    <artifactId>dataway-spring</artifactId>
    <version>5.0.0</version>
</dependency>
<!-- 保存接口定义和发布记录 -->
<dependency>
    <groupId>net.hasor</groupId>
    <artifactId>dataway-meta-jdbc</artifactId>
    <version>5.0.0</version>
</dependency>
<!-- SQL 执行能力 -->
<dependency>
    <groupId>net.hasor</groupId>
    <artifactId>dataql-sqlproc</artifactId>
    <version>5.0.0</version>
</dependency>

通过 DatawayConfig 配置身份识别、数据库连接和脚本扩展，通过 ApiDataAccessLayer 接入元数据存储。完整配置见快速开始；Spring 示例提供数据初始化、登录、控制台和 Swagger UI。

2. 实战代码

SQL 查询接口

创建 POST /person-query，选择 DataQL 脚本类型。以下脚本使用 ds1 数据源，将请求参数 id 绑定到 SQL：

hint FRAGMENT_SQL_DATA_SOURCE = "ds1"
var query = @@selectSql(id)<%
    SELECT id AS "id", name AS "name", balance AS "balance"
    FROM example_people
    WHERE id = #{id}
%>;
return query(${id});

保存并发布后，使用 Spring 示例的登录接口获取 Cookie，再调用 API：

curl -c cookies.txt -X POST http://127.0.0.1:8080/session/login \
  -d 'username=admin&password=example-password'

curl -b cookies.txt http://127.0.0.1:8080/api/person-query \
  -H 'Content-Type: application/json' \
  -d '{"id":1}'

默认使用 Structure 处理器包装响应，value 中包含查询结果：

{"id": 1, "name": "Alice", "balance": 100}

数据结构转换

使用 DataQL 转换模板选取字段、计算新值。people 也可以替换为 SQL 查询或应用函数的返回结果：

var people = [
    {"name": "Alice", "age": 25},
    {"name": "Bob", "age": 30}
];

return people => [{
    "name",
    "nextAge": age + 1
}];

脚本返回：

[
    {"name": "Alice", "nextAge": 26},
    {"name": "Bob", "nextAge": 31}
]

Java 调用接口

从框架容器获取 Dataway 实例后，使用 ApiService 调用已发布且启用的 API。路径使用定义中的路径，不包含 HTTP 入口的 /api 前缀：

import java.util.Map;
import net.hasor.dataway.model.ResultInfo;
import net.hasor.dataway.service.script.ApiService;

ApiService api = dataway.getApiService();
Map<String, Object> parameters = Map.of("id", 1);
ResultInfo result = api.invokeByPath("POST", "/person-query", parameters);

System.out.println(result.getData());

Java 调用共用 API 拦截器、参数处理和结果处理器，也可通过 invokeById 按 API 标识调用。

📚 文档与资源 | Resources

官方网站、快速开始、文档指南。
框架整合：Spring、Solon、Hasor。
示例工程：Spring + JDBC、Solon + JDBC、Hasor + JDBC、Spring + Nacos。
语言与引擎：DataQL 语言手册、独立使用引擎、数据处理样例。
博客文章、AI 文档索引。
开发指南：仓库结构、环境准备、编译测试与文档维护。

📄 许可证 | License

Dataway 使用 Apache License 2.0 许可协议。

FilesExpand file tree

README.md

Latest commit

History