Files
aibridge/docs/datainterface/README.md
T
2026-05-18 09:28:15 +08:00

159 lines
4.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# JNPF 数据接口 (DataInterface) 开发指南
## 文档索引
| 文档 | 说明 |
|------|------|
| **README.md** | 本文档,基本用法速查 |
| [基础规则](01-basic-rules.md) | 核心机制、类型、参数、SQL占位符 |
| [SQL操作](02-sql-operation.md) | SQL查询接口的创建与使用 |
| [静态数据](03-static-data.md) | 静态数据接口的配置 |
| [API操作](04-api-operation.md) | API接口调用的配置 |
| [分页配置](05-pagination.md) | 分页查询的配置与实现 |
| [参数配置](06-parameters.md) | 参数定义与传递 |
| [示例参考](07-examples.md) | 28个示例接口详细说明 |
| [常见问题](08-troubleshooting.md) | 常见错误与解决方案 |
---
## 快速开始
### 1. 核心概念
| 概念 | 说明 |
|------|------|
| **type** | 类型: 1=SQL操作, 2=静态数据, 3=API操作 |
| **action** | 动作: 1=增删改, 2=修改, 3=查询, 4=删除 |
| **hasPage** | 分页: 0=禁用, 1=启用 |
| **isPostPosition** | 鉴权: 0=否, 1=是(后置接口) |
| **dbLinkId** | 数据库连接ID,"0"=主库 |
### 2. 三种接口类型
```
type=1: SQL操作 → 执行SQL查询/增删改
type=2: 静态数据 → 返回固定JSON数据
type=3: API操作 → 调用HTTP接口
```
### 3. AIBridge 快速使用
```python
from aibridge import JNPFClient, JNPFConfig
from aibridge.modules.data_interface import DataInterfaceAPI
client = JNPFClient.from_config(JNPFConfig())
client.login()
di = DataInterfaceAPI(client)
# 执行查询
result = di.execute("接口ID", {"参数名": "值"})
for row in result:
print(row)
```
### 4. 创建SQL查询接口
```python
# 构建payload
payload = DataInterfaceAPI.build_payload(
full_name="按名称查询",
en_code="query_by_name",
sql="SELECT * FROM base_user WHERE f_real_name = {name}",
parameters=[{
"field": "name",
"fieldName": "姓名",
"dataType": "varchar",
"required": 1,
"sourceType": 1
}],
category="分类ID",
action=3,
db_link_id="0"
)
# 创建并执行
di.create(payload)
result = di.execute(di_id, {"name": "张三"})
```
---
## 关键配置速查
### SQL占位符
```sql
SELECT * FROM table WHERE field = {参数名}
```
- `{参数名}` → PreparedStatement `?`
- `{@系统变量}` → 如 `{@userId}`, `{@organizeId}`
### 参数sourceType
| 值 | 说明 |
|----|------|
| 1 | 字段(defaultValue) |
| 2 | 自定义(relationField) |
| 3 | 空值 |
| 4 | 系统参数 |
### 系统变量
| 变量 | 说明 |
|------|------|
| `@userId` | 当前用户ID |
| `@organizeId` | 当前组织ID |
| `@snowFlakeID` | 雪花ID |
| `@lotSnowID` | 批量生成雪花ID |
| `@keyword` | 关键词搜索 |
| `@pageSize` | 每页条数 |
| `@offsetSize` | 开始条数 |
---
## 源码位置
| 资源 | 路径 |
|------|------|
| 前端入口 | `前端/.../views/dataCenter/dataInterface/` |
| 前端API | `前端/.../api/systemData/dataInterface.ts` |
| 后端Controller | `后端/.../base/controller/DataInterfaceController.java` |
| 后端Service | `后端/.../base/service/impl/DataInterfaceServiceImpl.java` |
| 实体类 | `后端/.../base/entity/DataInterfaceEntity.java` |
| AIBridge模块 | `aibridge/modules/data_interface.py` |
---
## 28个示例接口参考
| # | 名称 | ID | 类型 | 说明 |
|---|------|-----|------|------|
| 1 | 当前用户 | 83ae1f5e5c26447b8c4849ead352b048 | SQL | 查询当前登录用户信息 |
| 2 | 查询当前组织 | a0c3186292df4fe2842f66dee0ea7729 | SQL | 查询用户所属组织 |
| 3 | 查询当前组织以及子组织 | fdfd02c7628a4ea4a0b125463e7933e0 | SQL | 组织及子组织查询 |
| 4 | 用户列表 | ebcc44be142e43b795c0d769abd6d25a | SQL | 用户列表查询 |
| 5-11 | 柱状图/折线图/饼图... | - | 静态 | 图表静态数据 |
| 12 | 查询当前用户以及下属 | bd993fb8dc914076a3848b0c121b17ca | SQL | 用户及下属查询 |
| 13 | 获取订单商品接口 | 360711881444294853 | API | 外部API调用示例 |
| 14-15 | 视图/树形表格 | - | SQL | 特殊SQL查询 |
| 16 | 访问jnpf接口认证示例 | 395538362724780101 | API | 内部API鉴权示例 |
| 17 | 菜单 | 398809921702874629 | SQL | 系统菜单查询 |
| 18 | 系统菜单接口 | 398826053293854213 | API | 多参数API调用 |
| 19-20 | 测试/行政区划 | - | SQL | 带参数的SQL查询 |
| 21 | API真分页 | 469125039078305029 | API | API分页实现 |
| 22 | SQL真分页 | 469125798494792965 | SQL | SQL分页查询 |
| 23 | 添加公告接口 | 469471490920740869 | API | POST API示例 |
| 24-28 | 字段列表系列 | - | SQL | 下拉/树形选择数据 |
详细示例见 [示例参考](07-examples.md)
---
## 接口验证机制区分
| 机制 | 说明 | 适用场景 |
|------|------|---------|
| **dataExceptionJson** | JS脚本验证,API接口内部验证逻辑 | 验证API返回状态、业务错误码 |
| **InterfaceOauth** | 外部系统API密钥认证授权 | 第三方应用访问控制 |
详见 [接口认证文档](../interface-oauth/README.md)。