技术实践

数据库如何生成 REST API?配置流程、权限与调用示例

用双租户商品查询示例,走通表结构、字段配置、服务端权限、参数化查询、游标分页与 curl 验证,说明数据库转 API 的实施边界。

从一条合作方商品查询开始

数据库转 API,适合先从数据范围明确的只读查询做起。例如,让合作方查询自己租户的可售商品,获得商品编号、名称与价格。实施时需要把表结构、输入、输出和权限一起确定,才能减少反复修改接口的工作。

本文用同一份脱敏数据走完配置、调用和验证。以下 SQL、PHP、接口路径及响应均为通用技术演示,用于说明接口设计;PHP 只实现查询核心。认证由已有服务端流程提供,HTTP 路由与部署需由项目完成,本文不代表 YesAPI Pro 的实际操作界面或内置接口。

第一步:准备两组数据,确定开放字段

在隔离的测试库创建下表。tenant_id 是内部租户编号;public_id 是创建后保持不变的公开业务编号,不能充当访问权限。price_cent 的单位为人民币分,避免让调用方猜测金额单位。

CREATE TABLE products (
  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
  tenant_id INT UNSIGNED NOT NULL,
  public_id CHAR(8) CHARACTER SET ascii COLLATE ascii_bin NOT NULL UNIQUE,
  name VARCHAR(80) NOT NULL,
  price_cent INT UNSIGNED NOT NULL,
  cost_cent INT UNSIGNED NOT NULL,
  is_available TINYINT UNSIGNED NOT NULL DEFAULT 1,
  INDEX idx_product_feed (tenant_id, is_available, public_id)
);

INSERT INTO products
  (tenant_id, public_id, name, price_cent, cost_cent, is_available)
VALUES
  (101, 'prd_1001', '陶瓷杯', 2990, 1600, 1),
  (101, 'prd_1002', '笔记本', 1290,  600, 1),
  (101, 'prd_1003', '签字笔', 1990,  900, 1),
  (101, 'prd_1004', '收纳盒', 3990, 2100, 0),
  (202, 'prd_2001', '保温杯', 4590, 2600, 1);

配置数据源时,让 API 服务使用仅具备目标数据读取权限的数据库账号;连接地址与数据库凭证保存在服务端。测试建表账号与接口查询账号应分开。调用方通过 HTTPS 访问 API,不获取数据库连接信息。

接着确定字段映射。查询和序列化都使用明确的允许列表,避免新增内部列后被自动返回:

数据库字段 API 返回字段 约定
public_id public_id 稳定的字符串编号,例如 prd_1001
name name 商品名称
price_cent price_cent 非负整数,人民币分;2990 表示 29.90 元
id、tenant_id、cost_cent、is_available 不返回 用于内部管理、权限或筛选

对这个接口,固定加入 is_available = 1。租户 101 能查询前三件商品,不能看到已下架的 prd_1004 或租户 202 的商品。

第二步:先写接口约定,再配置参数

本例定义 GET /v1/products,成功响应使用 application/json。只接受下列查询参数;未知参数、数组参数和重复参数名均拒绝。HTTP 接入层负责拒绝重复参数名,避免解析时覆盖原值。

参数 类型与范围 默认行为
limit 十进制整数字符串,1 至 100 省略时每页 2 条,便于观察示例
after 空字符串或符合 prd_ 加 4 位数字的编号 省略或为空时从第一页开始
public_id 可选,符合 prd_ 加 4 位数字的编号 提供时精确筛选一件商品

排序固定为 public_id ASC,与表中 ascii_bin 的比较规则保持一致。调用方不能传入表名、返回字段、SQL 或排序表达式。

这里使用 keyset 游标分页:下一次把响应的 next_cursor 原样放入 after。服务端查询 public_id > after,最多读取 limit + 1 条。多出的那一条只用于判断 has_more;游标取本页实际返回的最后一条,这样下一页不会跳过商品。没有更多数据时,next_cursor 为 null。

这是按每次请求时的数据返回的列表,不保证多页查询共享同一份快照。分页期间商品上架、下架或更名,可能改变后续结果;需要完整一致导出的业务,应另行设计快照或导出任务。public_id 必须保持不变。

第三步:从服务端身份确定租户与权限

在执行 SQL 前,已有认证流程需要校验调用凭证、应用状态和接口权限,再从服务端保存的应用关系中得到租户编号。本例的测试上下文如下,应用名仅用于说明:

通过认证的应用 服务端租户编号 服务端授予的权限
app_demo_a 101 products.read
app_demo_b 202 products.read
app_demo_a_denied 101 无 products.read 权限

请求中的 tenant_id、自定义租户请求头或未经验证的令牌内容,都不能覆盖这份映射。每次查询都带上可信上下文中的 tenant_id,即使调用方知道其他租户的 public_id,也只能得到自己有权查看的数据。权限应在每个受保护的端点执行,可参考 OWASP REST 安全建议。

HTTP 接入层按以下顺序处理:验证凭证;确认 products.read 权限;校验参数;调用查询核心;序列化响应。缺少或失效的凭证返回 401,应用已通过认证但没有该权限时返回 403。

第四步:配置查询,或实现同等的参数化逻辑

如果使用低代码工具,应逐项配置数据源、固定筛选条件、参数规则、返回字段和权限上下文。关键验收点是:租户条件能够绑定服务端身份,且调用方无法修改。若配置方式无法表达这个条件,应由后端接口承担权限查询,再接入平台管理。

下面的 PHP 函数展示同等的查询核心。$pdo 是应用注入的 MySQL PDO 连接,已设置 PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION 和 PDO::ATTR_EMULATE_PREPARES => false;$tenantId 是完成上述身份与权限校验后取得的正整数;$query 是接入层解析后的查询参数数组。它没有实现认证、HTTP 状态码或错误输出。

function queryProducts(PDO $pdo, int $tenantId, array $query): array
{
    foreach ($query as $key => $value) {
        if (!in_array($key, ['limit', 'after', 'public_id'], true)
            || !is_string($value)) {
            throw new InvalidArgumentException('INVALID_ARGUMENT');
        }
    }

    $limitText = $query['limit'] ?? '2';
    $after = $query['after'] ?? '';
    $wanted = $query['public_id'] ?? null;
    $idPattern = '/\Aprd_[0-9]{4}\z/';
    if (!preg_match('/\A(?:[1-9][0-9]?|100)\z/', $limitText)
        || ($after !== '' && !preg_match($idPattern, $after))
        || ($wanted !== null && !preg_match($idPattern, $wanted))) {
        throw new InvalidArgumentException('INVALID_ARGUMENT');
    }
    $limit = (int) $limitText;

    $sql = 'SELECT public_id, name, price_cent FROM products
            WHERE tenant_id = ? AND is_available = 1 AND public_id > ?';
    if ($wanted !== null) {
        $sql .= ' AND public_id = ?';
    }
    $sql .= ' ORDER BY public_id ASC LIMIT ?';

    $statement = $pdo->prepare($sql);
    $statement->bindValue(1, $tenantId, PDO::PARAM_INT);
    $statement->bindValue(2, $after, PDO::PARAM_STR);
    $position = 3;
    if ($wanted !== null) {
        $statement->bindValue($position++, $wanted, PDO::PARAM_STR);
    }
    $statement->bindValue($position, $limit + 1, PDO::PARAM_INT);
    $statement->execute();
    $rows = $statement->fetchAll(PDO::FETCH_ASSOC);

    $hasMore = count($rows) > $limit;
    $page = array_slice($rows, 0, $limit);
    $items = array_map(static fn(array $row): array => [
        'public_id' => (string) $row['public_id'],
        'name' => (string) $row['name'],
        'price_cent' => (int) $row['price_cent'],
    ], $page);

    return [
        'items' => $items,
        'has_more' => $hasMore,
        'next_cursor' => $hasMore ? $items[count($items) - 1]['public_id'] : null,
    ];
}

SQL 中的可变值通过绑定参数传入,LIMIT 显式绑定为整数。可选筛选片段来自服务端固定代码。PDO 占位符只能表示完整的数据值,不能代替表名、列名或任意查询片段,参见 PDO::prepare 官方文档。MySQL 的预处理查询支持在 LIMIT 使用占位符,参见 SELECT 文档。

接入层将 InvalidArgumentException 映射为下表的 400,数据库异常映射为 500。数据库异常细节保留在受控的服务端日志中,对外响应不包含 SQL、表名、连接地址或堆栈。

HTTP 状态 error.code error.message
400 INVALID_ARGUMENT 查询参数无效
401 UNAUTHENTICATED 请提供有效调用凭证
403 FORBIDDEN 当前应用没有商品查询权限
500 INTERNAL_ERROR 服务暂时不可用

例如,limit=101 的响应为 HTTP 400,JSON 如下:

{ "error": { "code": "INVALID_ARGUMENT", "message": "查询参数无效" } }

第五步:调用接口,对照固定数据检查响应

完成测试端点接线后,用下面的请求验证。api.example.com 和 DEMO_TOKEN_A 均为占位内容,替换成测试服务地址及租户 101 应用的测试凭证;请勿使用生产凭证分享命令或截图。

curl --get 'https://api.example.com/v1/products' \
  --header 'Authorization: Bearer DEMO_TOKEN_A' \
  --data-urlencode 'limit=2'

按第一步的数据,第一页应返回 HTTP 200:

{
  "items": [
    { "public_id": "prd_1001", "name": "陶瓷杯", "price_cent": 2990 },
    { "public_id": "prd_1002", "name": "笔记本", "price_cent": 1290 }
  ],
  "has_more": true,
  "next_cursor": "prd_1002"
}

继续取下一页,凭证保持不变:

curl --get 'https://api.example.com/v1/products' \
  --header 'Authorization: Bearer DEMO_TOKEN_A' \
  --data-urlencode 'limit=2' \
  --data-urlencode 'after=prd_1002'

响应为 HTTP 200。prd_1004 已下架,prd_2001 属于另一租户,均不返回:

{
  "items": [{ "public_id": "prd_1003", "name": "签字笔", "price_cent": 1990 }],
  "has_more": false,
  "next_cursor": null
}

若租户 101 精确查询 public_id=prd_2001,或查询 after=prd_1003,都应返回下面的空列表。该集合查询统一使用 HTTP 200,不向调用方说明目标商品是否属于其他租户:

{ "items": [], "has_more": false, "next_cursor": null }

切换为租户 202 的测试凭证、移除筛选和游标后,第一页应只含 prd_2001:名称为“保温杯”,price_cent 为 4590,has_more 为 false,next_cursor 为 null。

第六步:用反例验收权限与分页

以下是基于本例约定的预期结果,需要在实际测试端点执行并记录。看到一条正常响应,还不足以证明隔离、参数和分页正确。

测试 请求或条件 预期结果
未认证 不带调用凭证或使用失效凭证 401,UNAUTHENTICATED
无接口权限 使用 app_demo_a_denied 的测试凭证 403,FORBIDDEN,不执行商品查询
跨租户查询 租户 101 查询 public_id=prd_2001 200 空列表,不能看到保温杯
篡改租户 租户 101 添加 tenant_id=202 400,INVALID_ARGUMENT
SQL 注入输入 将 public_id 设为 prd_1001' OR 1=1 -- 400,INVALID_ARGUMENT;查询核心继续坚持参数绑定
数量与类型 limit=0、limit=101、limit=2.5 或 limit[]=2 400,INVALID_ARGUMENT
重复参数 同时发送 limit=2&limit=100 接入层返回 400,不能由解析顺序决定数量
字段隔离 检查每一条成功响应 只出现三个白名单字段,不含成本、租户或内部行号
多页连续性 租户 101,limit=2,按返回游标继续 依次得到 1001、1002 与 1003,无重复或跳过
恰好一页 租户 101,limit=3 返回三件商品,has_more=false、游标为 null
数据库异常 在测试环境模拟连接不可用 500,INTERNAL_ERROR,不泄露数据库信息

上线前还应结合真实数据量查看执行计划和慢查询,并为请求设置超时、访问频率与响应大小限制。查询结果有缓存时,缓存键必须包含可信租户与筛选条件,避免把一个租户的结果交给另一个租户。

低代码适合减少哪些工作

只读查询、固定字段映射和明确的筛选条件,适合通过配置减少接口与文档的重复工作。复杂联表、写入事务、库存扣减和跨系统审批需要额外的业务设计。数据库能够连接,也不等于任意 SQL、权限模型和事务都能直接配置完成。

YesAPI Pro 的低代码 API 开发能力包含可视化配置、数据库 API、Swagger 导入与在线调试。具体数据源类型、驱动、查询和服务端权限绑定方式,应结合 Java 企业版或 PHP 成熟版的实际方案核对。

可以携带这份脱敏表结构、目标返回字段和上面的验收表预约演示。演示围绕一条实际查询,逐项检查租户隔离、参数规则、分页与文档,便于确定哪些配置可以复用、哪些部分需要开发。

参考资料

以下为本文引用的官方资料。文中的通用示例与产品套餐能力分别说明。

接下来,如何选型?

用一条查询,核对低代码边界。

从数据库 API 与接口配置能力开始,结合团队技术栈选择版本。文中 SQL / PDO 为通用示例。

  • 准备脱敏表结构、返回字段、筛选条件与数据权限。
  • 将跨租户、无权限和分页边界作为演示用例。

需要把这些问题落到项目上?

整理目标接口、技术栈与部署边界,预约一次有重点的产品演示。

预约产品演示
↑