# 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)。