---
title: 数据查询
description: describe / loaddata / page / loaddatabysql / nextid / nextcode
pageClass: g3-api
---

# 数据查询

六个只读接口。除了 `nextid`（纯取号，不碰数据库），其余都会落到**当前机构自己的数据库**上执行。

共用规则：

- **表名、视图名、列名都会先过标识符校验**（只允许 `[A-Za-z_][A-Za-z0-9_]*`，可带限定名如 `dbo.v_x`），不会做字符串拼接 —— 所以别指望能塞入非法标识符。
- `search_condition` 是**原样拼进 `WHERE` 的 SQL 条件片段**；拼好的整条 SQL 之后会过只读校验（禁分号、禁注释、禁写关键字），所以它只能是布尔表达式。
- `order_by` 由后端校验并加 `[]`：支持 `字段 [ASC|DESC]`，或 `CASE ... END` 表达式，多列用逗号分隔。
- 返回的行是普通对象，键是**库里的原始列名**。

## `POST` `/data/describe`

探测表或视图的列结构，用于动态列、字段同步。

<G3ApiParams>

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `table` | string | 是 | 表或视图名 |

</G3ApiParams>

<G3ApiPayload title="请求体">

```json
{
  "table": "v_b_othercompany"
}
```

</G3ApiPayload>

<G3ApiPayload title="响应" :code="0">

```json
{
  "code": 0,
  "message": "操作成功",
  "data": [
    { "name": "b_id", "type": "varchar", "nullable": false, "size": 32 },
    { "name": "b_name", "type": "nvarchar", "nullable": true, "size": 128 }
  ]
}
```

</G3ApiPayload>

`type` 是数据库原生类型名（`varchar` / `nvarchar` / `decimal` / `datetime2` / `rowversion` …）。表不存在或没有可识别字段时返回 `1000`。

## `POST` `/data/loaddata`

按视图 + 条件 + 排序 + 字段列表查询。

<G3ApiParams>

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `view_name` | string | 是 | 表或视图名 |
| `search_columns` | string[] | | 只取这些列；省略等价于 `*` |
| `search_condition` | string | | `WHERE` 片段 |
| `order_by` | string | | 排序，多列逗号分隔 |

</G3ApiParams>

<G3ApiPayload title="请求体">

```json
{
  "view_name": "v_b_othercompany",
  "search_columns": ["b_id", "b_name", "b_canuse"],
  "search_condition": "b_canuse = 1",
  "order_by": "b_id ASC, b_name DESC"
}
```

</G3ApiPayload>

<G3ApiPayload title="响应" :code="0">

```json
{
  "code": 0,
  "message": "操作成功",
  "data": [{ "b_id": "C001", "b_name": "XX 公司", "b_canuse": 1 }]
}
```

</G3ApiPayload>

> **没有行数上限。** `loaddata` 会把命中的行全部返回；列表页请用 `/data/page`。它的典型用途是取一个小字典（下拉选项）或按主键取单行。

## `POST` `/data/page`

分页查询。

<G3ApiParams>

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `view_name` | string | 是 | 表或视图名 |
| `order_by` | string | 是 | 分页必须有序（SQL Server 的 `OFFSET / FETCH` 要求） |
| `search_columns` | string[] | | 只取这些列 |
| `search_condition` | string | | `WHERE` 片段 |
| `page_no` | number | | 默认 `1`，从 1 开始 |
| `page_size` | number | | 默认 `20` |

</G3ApiParams>

<G3ApiPayload title="请求体">

```json
{
  "view_name": "v_b_othercompany",
  "search_condition": "b_canuse = 1",
  "order_by": "b_id ASC",
  "page_no": 2,
  "page_size": 20
}
```

</G3ApiPayload>

<G3ApiPayload title="响应" :code="0">

```json
{
  "code": 0,
  "message": "操作成功",
  "data": {
    "rows": [{ "b_id": "C021", "b_name": "XX 公司" }],
    "row_count": 20,
    "total": 137,
    "page_no": 2,
    "page_size": 20
  }
}
```

</G3ApiPayload>

<G3ApiParams title="data 字段">

| 字段 | 说明 |
|---|---|
| `rows` | 当前页数据 |
| `row_count` | **当前页**的行数（等于 `rows.length`） |
| `total` | 命中总行数 |
| `page_no` / `page_size` | 回显请求里的分页参数 |

</G3ApiParams>

> `row_count` 不是总行数，**总行数是 `total`**。算总页数用 `total`，别用 `row_count`。
>
> `page_no` 或 `page_size` 小于 1、或不是整数，都会得到 `1000`（`page_no 必须是大于 0 的整数`）。

翻到最后一页之后（`page_no` 超出范围）`rows` 为空，但 `total` 仍然正确 —— 所以判断「没数据」和「翻过了头」要靠 `total`。

## `POST` `/data/loaddatabysql`

配置表达不出来的复杂只读查询走这里。

<G3ApiParams>

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `sql` | string | 是 | 必须以 `SELECT` 或 `WITH` 开头 |

</G3ApiParams>

<G3ApiPayload title="请求体">

```json
{
  "sql": "SELECT TOP 10 b_id, b_name FROM v_b_othercompany ORDER BY b_id"
}
```

</G3ApiPayload>

<G3ApiPayload title="响应" :code="0">

```json
{
  "code": 0,
  "message": "操作成功",
  "data": [{ "b_id": "C001", "b_name": "XX 公司" }]
}
```

</G3ApiPayload>

被拒的情况（都是 `1000`）：不是 `SELECT` / `WITH` 开头、包含 `;`、包含注释（`--` 或 `/* */`）、出现 `insert` `update` `delete` `drop` `truncate` `alter` `exec` `grant` 等关键字。

> 判定前会先把**字符串字面量整体掩掉**，所以在 `WHERE b_name = 'insert'` 这类写法里，字面量里的关键字不会误判。反过来也说明：不能在字面量之外藏写操作。

## `POST` `/data/nextid`

取雪花 ID。

<G3ApiParams>

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `count` | number | | 默认 `1`；`<= 1` 时 `data` 是单个 id，否则是数组 |

</G3ApiParams>

请求体**可以整个省略** —— 不带 body 或传 `{}` 是等价的，`count` 都取默认的 `1`：

<G3ApiPayload title="请求体">

```json
{}
```

</G3ApiPayload>

<G3ApiPayload title="响应" :code="0">

```json
{
  "code": 0,
  "message": "操作成功",
  "data": "1873456789012345678"
}
```

</G3ApiPayload>

`count: 3` 时：

<G3ApiPayload title="响应" :code="0">

```json
{
  "code": 0,
  "message": "操作成功",
  "data": [
    "1873456789012345678",
    "1873456789012345679",
    "1873456789012345680"
  ]
}
```

</G3ApiPayload>

> 返回的是**字符串**（见 [快速开始](/api/getting-started) 里的序列化约定），不要转成数字。

## `POST` `/data/nextcode`

按模块配置的自动编码规则取业务编码（规则来自 `s_autocode`：前缀、日期格式、序号位数、分隔符、重置周期等）。

<G3ApiParams>

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `moduleId` | string | 是 | 模块编码（注意是 camelCase 的 `moduleId`） |
| `count` | number | | 默认 `1`；`<= 1` 时返回单个字符串，否则返回数组 |

</G3ApiParams>

<G3ApiPayload title="请求体">

```json
{
  "moduleId": "othercompany",
  "count": 1
}
```

</G3ApiPayload>

<G3ApiPayload title="响应" :code="0">

```json
{
  "code": 0,
  "message": "操作成功",
  "data": "HT20261012001"
}
```

</G3ApiPayload>

行为要点：

- **会占用号段** —— 服务端取号后立即把序号写回 `s_autocode`，所以连续调用得到的是不同编码。别拿它做「探测一下看看格式」的试调，试出来的号就废了。
- 生成时会**检查目标表里该编码是否已存在**，已被占用（比如人工插过一条）就自动往后顺延，所以不一定严格等于「当前序号 + 1」。
- 模块没有配置启用的编码规则、或没配保存表 → `1000`（`当前模块未配置启用的自动编码规则` / `模块未配置保存表，无法生成自动编号`）。
- 生成的编码超过目标字段长度 → `1000`（`自动编号长度超过目标字段长度`）。