159 lines
4.9 KiB
Markdown
159 lines
4.9 KiB
Markdown
# 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)。
|